mystmd
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
mystmd
project is in beta. It is being used to explore a full MyST implementation 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.
The mystmd
project provides a command line tool (mystmd
) for working with MyST Markdown projects.
- Provides functionality for cross-referencing, external structured links, and scientific citations
- Translate and render MyST Markdown 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
- Parse MyST into a standardized AST, that follows the MyST Markdown Spec
See the documentation.
The MyST Markdown CLI is available through Node and NPM:
npm install -g mystmd
myst init
myst build my-doc.md --tex
All packages for mystmd
are included in this repository (a monorepo!).
mystmd
uses npm as a package manager. It includes the following packages/apps:
Command Line Tools:
mystmd
this provides CLI functionality formyst build mystdoc.md
Core Packages:
myst-cli
this is the package that provides CLI functionality formystmd
, it does not export the CLI directlyjtex
a templating library (see docs)myst-frontmater
definitions and validation for scientific authorship/affiliation frontmatter (see docs)myst-config
Validation and reading of configuration filesmyst-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 MySTmyst-roles
core roles for MySTmyst-parser
converts markdown-it token stream to mdast
Readers
tex-to-myst
convert LaTeX to MyST ASTjats-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 archivesmyst-to-tex
convert MyST to LaTeX, to be used in combination with jtex to create stand alone LaTeX documentsmyst-to-html
convert MyST to HTML
Extensions:
myst-ext-card
: Card directivesmyst-ext-grid
: Grid directivesmyst-ext-tabs
: Tab directivesmyst-ext-reactive
: Reactive directives
Utilities
myst-common
Some common utilities for working with ASTsmyst-spec-ext
Extensions tomyst-spec
used throughout this repository, before pushing upstreamcitation-js-utils
utility functions to deal with citationsmyst-cli-utils
some shared utils between jtex, and myst-clisimple-validators
validation utilities, that print all sorts of nice warnings
Each package is 100% TypeScript and ESM only.
mystmd
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
.
mystmd
is built and developed using:
- TypeScript for static type checking
- ESLint for code linting
- Prettier for code formatting
To build all apps and packages, run the following command:
cd mystmd
npm run build
For the mystmd library on GitHub, git clone
and you can install the dependencies and then create a local copy of the library with the npm run dev
command.
git clone [email protected]:executablebooks/mystmd.git
cd mystmd
npm install
npm run build
npm run dev
This will create a local copy of myst
for use on the command line and start various web-servers for testing.
As of v1.0.0 this package is ESM only.