jupyter-book / myst-spec

MyST is designed to create publication-quality, computational documents written entirely in Markdown.
https://mystmd.org/spec
MIT License
14 stars 6 forks source link

Commonmark json-schema and validation of examples #2

Closed fwkoch closed 2 years ago

fwkoch commented 2 years ago

Overview video: https://www.loom.com/share/633e84c35a574a7cb09059323ab80efb

This PR provides a framework for building the MyST mdast schema with json schema. This follows the existing commonmark markdown mdast schema. It is similar to the json schema defined here, but is a bit more verbose / explicit and broken into multiple files to simplify extensibility with new MyST features.

Currently, the json schema supports all commonmark features; the commonmark spec examples are all included and validated.

The current structure is schema/ folder and subfolders, each of which has schema definitions, documentation md files, and example yaml files. There is also a test suite which validates all the example yaml files against the schema. We will add additional subfolders for new MyST features:

schema/
|- myst.schema.json          // root schema definition
|- myst.md                   // docs
|- schema.spec.ts            // test for validating all examples against the schema
|- unist/
|  |- unist.schema.json      // unist base types
|  |- unist.md               // docs
|  |- unist.yml              // example mdast structures
|- commonmark/
|  |- commonmark.schema.json // commonmark mdast types
|  |- commonmark.md          // docs
|  |- commonmark.yml         // simple commonmark examples
|  |- cmark_spec_0.30.yml    // commonmark spec examples
...
|- roles/                    // future myst features
|  |- roles.schema.json
|  ...
|- directives/
|  |- directives.schema.json
|  ...
welcome[bot] commented 2 years ago

Congrats on your first merged pull request in this project! :tada: congrats
Thank you for contributing, we are very proud of you! :heart: