Based on the team meeting yesterday, and follow up conversations with @chrisjsewell, @mmcky, @choldgraf and @fwkoch, we are starting to put together a repository that will house the technical documentation and test cases for a MyST Spec. This will be housed at https://spec.myst.tools in the future (see https://github.com/executablebooks/meta/issues/538).
To build on the MyST markup language and to make the ecosystem as rich and interoperable as possible, we need to formalize three formats:
1) the MyST markup syntax, to ensure MyST works as expected across languages and implementations;
2) the MyST abstract syntax tree (AST), to promote an ecosystem of transformations and exports to diverse formats (e.g. latex/word/html/docutils/etc.); and
3) suggested semantic HTML output and CSS class structure, to promote web-accessibility and interoperability of themes.
There is additional standardization on optional extensions (e.g. dollarMath, and configuration), that is likely outside the scope of this repository and more coordination between packages. Additionally, MyST as a community standard requires ways to improve and enhance these formalizations over time in our multi-stakeholder community. We will aim to start to introduce more formalization on this process over the coming months (e.g. MEPs in an extension proposals repo)!
There are a number of places where test-cases and documentation already live. @fwkoch @rowanc1 and @chrisjsewell will be doing some initial work to pull these together to get a first pass spec (CommonMark + GFM + Base directives/roles + Admonitions). There is existing work is in:
Documentation of the spec, choices and properties of both the AST and MyST syntax
These are based on extensions to MDAST, GFM, and CommonMark
Single built json file of all test cases with links back to the docs
JSON Schema
Typescript types
Limited duplication on the source of truth for examples, properties and test-cases.
Next steps
For the next few weeks @chrisjsewell will be working on the CommonMark/GFM side and documentation, as well as familiarizing with Mdast work done in mystjs, and @rowanc1 and @fwkoch will be working on the MyST side bringing these over to json schema and formalizing the mdast naming and properties.
Based on the team meeting yesterday, and follow up conversations with @chrisjsewell, @mmcky, @choldgraf and @fwkoch, we are starting to put together a repository that will house the technical documentation and test cases for a MyST Spec. This will be housed at https://spec.myst.tools in the future (see https://github.com/executablebooks/meta/issues/538).
To build on the MyST markup language and to make the ecosystem as rich and interoperable as possible, we need to formalize three formats: 1) the MyST markup syntax, to ensure MyST works as expected across languages and implementations; 2) the MyST abstract syntax tree (AST), to promote an ecosystem of transformations and exports to diverse formats (e.g. latex/word/html/docutils/etc.); and 3) suggested semantic HTML output and CSS class structure, to promote web-accessibility and interoperability of themes.
There is additional standardization on optional extensions (e.g. dollarMath, and configuration), that is likely outside the scope of this repository and more coordination between packages. Additionally, MyST as a community standard requires ways to improve and enhance these formalizations over time in our multi-stakeholder community. We will aim to start to introduce more formalization on this process over the coming months (e.g. MEPs in an extension proposals repo)!
There are a number of places where test-cases and documentation already live. @fwkoch @rowanc1 and @chrisjsewell will be doing some initial work to pull these together to get a first pass spec (CommonMark + GFM + Base directives/roles + Admonitions). There is existing work is in:
Goals:
Next steps
For the next few weeks @chrisjsewell will be working on the CommonMark/GFM side and documentation, as well as familiarizing with Mdast work done in mystjs, and @rowanc1 and @fwkoch will be working on the MyST side bringing these over to json schema and formalizing the mdast naming and properties.
🚀🚀🚀
Whiteboard from our call today: