mystmd
MyST Markdown Command Line Interface,
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.
Overview
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.
Get Started
Ensure that you have an updated version of Node installed (https://nodejs.org/):
node -v
>> v20.4.0
The MyST Markdown CLI is available through NPM, PyPI and Conda:
# Using npm, yarn, or pnpm
npm install -g mystmd
# Or using PyPI
pip install mystmd
# Or using Conda / Mamba
conda install mystmd -c conda-forge
Usage:
myst init
myst start
myst build my-doc.md --tex
Development
All packages for mystmd
are included in this repository (a monorepo!).
What's inside?
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.
Versioning & Publishing
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
.
Utilities
mystmd
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 mystmd
npm run build
Developing
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.