search

executablebooks / meta

A community dedicated to supporting tools for technical and scientific communication and interactive computing
https://executablebooks.org
132 stars 167 forks source link

Define a MyST markdown syntax standard + process #118

Open choldgraf opened 4 years ago

choldgraf commented 4 years ago

As discussed a bit in https://github.com/executablebooks/jupyter-book/pull/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 commented 4 years ago

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 commented 2 years ago

I think this can close with #843 when merged.