Background

The MyST Parser has grown quite a lot in adoption, extended syntax, and has the potential to begin diversifying into other non-Sphinx parsing use-cases as well (e.g., Javascript, Nikola, etc).

I think that it'd be easier for people to find the usecase-specific information they need about MyST if we re-structured the documentation a little bit. I think a main goal should be to separate the MyST core specification from the Sphinx-specific functionality. That way it's clearer to others how they could use MyST in a non-Sphinx context, and should be clearer where new documentation should go when we add it in the future.

A proposed structure

I'd imagine a high-level structure similar to the Diataxis framework with the following major sections:

• Tutorials
  • Get started with MyST in Sphinx <-- tutorial focused on using MyST with Sphinx
  • (future tutorials could cover more usecase-specific things like substitutions, or developer tutorials like "write your own MyST parser")
• Topic Guides
  • MyST Markdown Syntax <-- parser-agnostic MyST syntax, no Sphinx-specific features in here
    • Core Syntax Guide
    • Extended Syntax Guide
    • Syntax Reference
  • MyST in Sphinx <-- focuses on Sphinx-specific functionality of the MyST Parser
    • MyST behavior that is unique to Sphinx (e.g., []() link syntax as a short-hand for {any} role)
    • Explanations about relationship between MyST/rST/Sphinx
  • Parse with the Python API <-- focuses on MyST from a developer's perspective. Could include discussion of markdown-it-py as well.
• About MyST <-- "meta" categories about the project itself
  • Contributing
  • Changelog

Does this seem like a reasonable separation of functionality and topics? Does it seem straightforward to extend and grow moving forward?