{"id":19684149,"url":"https://github.com/jupyter-book/myst-spec","last_synced_at":"2026-02-13T03:20:24.657Z","repository":{"id":41993299,"uuid":"465809594","full_name":"jupyter-book/myst-spec","owner":"jupyter-book","description":"MyST is designed to create publication-quality, computational documents written entirely in Markdown.","archived":false,"fork":false,"pushed_at":"2024-10-25T12:43:32.000Z","size":3545,"stargazers_count":14,"open_issues_count":35,"forks_count":6,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-10-25T12:49:01.631Z","etag":null,"topics":["commonmark","github-flavored-markdown","markdown","specification","sphinx"],"latest_commit_sha":null,"homepage":"https://mystmd.org/spec","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jupyter-book.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-03T17:00:14.000Z","updated_at":"2024-10-18T09:26:55.000Z","dependencies_parsed_at":"2024-10-24T15:53:10.765Z","dependency_job_id":"ae262523-e7e7-4517-9f9f-e4a89226ff97","html_url":"https://github.com/jupyter-book/myst-spec","commit_stats":{"total_commits":37,"total_committers":9,"mean_commits":4.111111111111111,"dds":0.6756756756756757,"last_synced_commit":"4116985a33e3c2171e6eac31fbd7679892f884a4"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyter-book%2Fmyst-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyter-book%2Fmyst-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyter-book%2Fmyst-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyter-book%2Fmyst-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jupyter-book","download_url":"https://codeload.github.com/jupyter-book/myst-spec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224151084,"owners_count":17264436,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commonmark","github-flavored-markdown","markdown","specification","sphinx"],"created_at":"2024-11-11T18:16:58.709Z","updated_at":"2026-02-13T03:20:24.630Z","avatar_url":"https://github.com/jupyter-book.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MyST Spec\n\n\u003e :warning: The MyST AST specification is still in dev; any structures or features present in the JSON schema may change at any time without notice.\n\nMyST (Markedly Structured Text) is designed to create publication-quality, computational documents written entirely in Markdown. The main use case driving the development and design of MyST is [JupyterBook](https://jupyterbook.org/), which creates educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST.\n\nMyST is a superset of [CommonMark](https://commonmark.org/) (a standard form of Markdown) and allows you to directly create “directives” and “roles” as extension points in the language. These extensions points are influenced by [ReStructured Text (RST)](https://en.wikipedia.org/wiki/ReStructuredText) and [Sphinx](https://www.sphinx-doc.org/) -- pulling on the nomenclature and introducing additional standards where appropriate. `directives` are block-level extension points, like callout panels, tabs, figures or embedded charts; and `roles` are inline extension points, for components like references, citations, or inline math.\n\n````md\n```{directive} Argument\nThe *content* of a directive can have {role}`with content`\n```\n````\n\n## Goals\n\n`myst-spec` is designed to standardize implementations and extensions to MyST, with the goal of making the MyST ecosystem as rich and interoperable as possible. The spec formalizes three formats:\n\n1. the MyST markup syntax, to ensure MyST works as expected across languages and implementations;\n2. 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\n3. suggested semantic HTML output and CSS class structure, to promote web-accessibility and interoperability of themes.\n\nThe `myst-spec` will be improved overtime through enhancement proposals which can be submitted by our multi-stakeholder community. [IN PROGRESS]\n\n## MyST Spec\n\nThis repository introduces tests to cover the MyST Spec. These tests cover three target formats: `myst`, `mdast`, and `html`. An simple example test case (in yaml) for a header looks like:\n\n```yaml\ncases:\n  - title: CommonMark headers\n    myst: |-\n      # Heading!\n    mdast:\n      type: root\n      children:\n        - type: heading\n          depth: 1\n          children:\n            - type: text\n              value: Heading!\n    html: |-\n      \u003ch1\u003eHeading!\u003c/h1\u003e\n```\n\n[TBD: Do we include latex here, maybe?]\n\n### Markdown Abstract Syntax Tree, `mdast`\n\nMarkdown AST, or `mdast`, is an intermediate format that builds upon the existing [mdast spec](https://github.com/syntax-tree/mdast), which is used throughout the [unifiedjs](https://unifiedjs.com/) Javascript community with hundreds of [existing transformations](https://unifiedjs.com/explore/), [utilities](https://unifiedjs.com/explore/keyword/unist-util/) and [serializers](https://unifiedjs.com/explore/keyword/rehype/). `mdast` is simple, with a `type` defining the node optional properties on the node and optional `children` (a leaf node has a `value`).\n\nBeyond CommonMark and GitHub Flavoured Markdown, MyST introduces new directives and roles (like admonitions, citations, equations) following existing standards where they are defined. `mdast` is serializable to JSON or YAML, and can be effectively shared between projects, languages and implementations. The output of this repository is a versioned JSON file that can be used in implementations of MyST.\n\n### Structure of the Repository\n\n```\nschema/\n|- myst.schema.json          // root schema definition\n|- myst.md                   // docs\n|- schema.spec.ts            // test for validating all examples against the schema\n|- unist/\n|  |- unist.schema.json      // unist base types\n|  |- unist.md               // docs\n|  |- unist.yml              // example mdast structures\n|- commonmark/\n|  |- commonmark.schema.json // commonmark mdast types\n|  |- commonmark.md          // docs\n|  |- commonmark.yml         // simple commonmark examples\n|  |- cmark_spec_0.30.yml    // commonmark spec examples\n...\n|- roles/                    // future myst features\n|  |- roles.schema.json\n|  ...\n|- directives/\n|  |- directives.schema.json\n|  ...\n```\n\n## Relation to other markup languages, frameworks\n\n[TODO]\n\n- CommonMark\n- GitHub Flavored Markdown\n- Pandoc\n- Unified\n- Markdown-It\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyter-book%2Fmyst-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjupyter-book%2Fmyst-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyter-book%2Fmyst-spec/lists"}