MyST Markdown Tools

mystjs is a set of open-source, community-driven tools designed for scientific communication, including a powerful authoring framework that supports blogs, online books, scientific papers, reports and journals articles.

Note The mystjs project is in beta. It is being used to explore a full MyST implementation in JavaScript and will change significantly and rapidly. The project is being developed by a small team of people on the Executable Books Project, and may make rapid decisions without fully public/inclusive discussion. We will continue to update this documentation as the project stabilizes.

Overview

The mystjs project provides a parser in Javascript (mystjs) and command line tool (myst-cli) for working with MyST Markdown projects.

Parse MyST into a standardized AST, that follows the MyST Spec
Provides functionality for cross-referencing, external structured links, and scientific citations
Translate and render MyST into:
- HTML for static websites, and modern React for interactive websites (like this website!)
- PDFs and LaTeX documents, with specific templates for over 400 journals
- Microsoft Word export

See the documentation.

Get Started

The MyST CLI is available through Node and NPM:

npm install -g myst-cli
myst init
myst build my-doc.md --tex

Development

All packages for mystjs are included in this repository (a monorepo!).

What's inside?

myst-cli uses npm as a package manager. It includes the following packages/apps:

Core Packages:

myst-cli this will provide CLI functionality for myst build mystdoc.md
jtex a templating library (see docs)
myst-frontmater definitions and validation for scientific authorship/affiliation frontmatter (see docs)
myst-config Validation and reading of configuration files
myst-templates types and validation for templates (LaTeX, web and word)

Markdown Parsing

markdown-it-myst markdown-it plugin to handle tokenizing roles and directives.
myst-directives core directives for MyST
myst-roles core roles for MyST
myst-parser converts markdown-it token stream to mdast

Readers

tex-to-myst convert LaTeX to MyST AST
jats-to-myst convert JATS xml to MyST AST

Transformers

myst-transforms a number of transformations for use with myst AST to transform, e.g. links, citations, cross-references, admonitions

Export Tools

myst-to-docx convert MyST documents to word docs!
myst-to-jats convert MyST to JATS, for use in scientific archives
myst-to-tex convert MyST to LaTeX, to be used in combination with jtex to create stand alone LaTeX documents
myst-to-html convert MyST to HTML

Extensions:

myst-ext-card: Card directives
myst-ext-grid: Grid directives
myst-ext-tabs: Tab directives
myst-ext-reactive: Reactive directives

Utilities

myst-common Some common utilities for working with ASTs
myst-spec-ext Extensions to myst-spec used throughout this repository, before pushing upstream
citation-js-utils utility functions to deal with citations
myst-cli-utils some shared utils between jtex, and myst-cli
simple-validators validation utilities, that print all sorts of nice warnings

Each package is 100% TypeScript.

Versioning & Publishing

mystjs uses changesets to document changes to this monorepo, call npm run changeset and follow the prompts. Later, npm run version will be called and then npm run publish.

Utilities

mystjs is built and developed using:

TypeScript for static type checking
ESLint for code linting
Prettier for code formatting

Build

To build all apps and packages, run the following command:

cd mystjs
npm run build

Develop

To develop all apps and packages, run the following command:

cd mystjs
npm run dev

This will create a local myst CLI interface that you can use to develop and test locally.

executablebooks / mystjs