Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define a MyST markdown syntax standard + process #118

Open
choldgraf opened this issue Aug 29, 2020 · 2 comments
Open

Define a MyST markdown syntax standard + process #118

choldgraf opened this issue Aug 29, 2020 · 2 comments
Labels
enhancement New feature or request

Comments

@choldgraf
Copy link
Member

choldgraf commented Aug 29, 2020

As discussed a bit in jupyter-book/jupyter-book#911, now that we have multiple syntax options to enable in the MyST parser, it will be important to define what is "core MyST markdown". This will make it easier for others to build applications that depend on MyST and libraries that use MyST under the hood - it will also help us define a standard across implementations of MyST parsers.

So I guess this issue is two things:

  1. What do we think of as "core MyST markdown"? E.g. if we had a validator to say "is this MyST markdown?" what would it check?
  2. What process do we want for changing this definition over time? E.g., if we wanted to add ::: syntax to the core spec, how would we go about doing this?

I think there are at least two things to consider:

Core vs. extended syntax: For example, tables are core syntax, while definition lists are extended. Do we want the current "core vs. extended" split to be constant? Or evolve over time so that extended syntax can become part of core?

Roles and Directives to support: because roles and directives are extension points, there are an infinite number of possible roles/directives to support. We should define a subset of roles and directives that are "official" in MyST Markdown (or at least, that we guarantee support for in both the Python and JS implementations of the MyST parser)

Reference

For reference, the Jupyter community tends to use JEPs to change the .ipynb format. Here's an example proposal to add a cell_id field. Perhaps we can use these as inspiration.

@choldgraf choldgraf added the enhancement New feature or request label Aug 29, 2020
@choldgraf
Copy link
Member Author

Another update from a conversation that I just had with @rowanc1, who has been making some great progress in markdown-it-myst. Now that there are two parsers for MyST in Python + Javascript, the issue of defining a common spec is probably more timely. Is anybody interested in writing up a JEP-style document to define the minimal spec that we wish to support?

@rowanc1
Copy link
Member

rowanc1 commented Oct 11, 2022

I think this can close with #843 when merged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants