• Stars
    star
    161
  • Rank 233,470 (Top 5 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 4 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Command line tools for working with MyST Markdown.

MyST Markdown Command Line Interface, mystmd

MIT License CI Discord Chat

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 for myst build mystdoc.md

Core Packages:

  • myst-cli this is the package that provides CLI functionality for mystmd, it does not export the CLI directly
  • 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 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:

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.


More Repositories

1

jupyter-book

Create beautiful, publication-quality books and documents from computational content.
Python
3,698
star
2

MyST-Parser

An extended commonmark compliant parser, with bridges to docutils/sphinx
Python
690
star
3

markdown-it-py

Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed. Now in Python!
Python
626
star
4

sphinx-autobuild

Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.
Python
480
star
5

sphinx-book-theme

A clean book theme for scientific explanations and documentation with Sphinx
Jupyter Notebook
438
star
6

mdformat

CommonMark compliant Markdown formatter
Python
401
star
7

thebe

Turn static HTML pages into live documents with Jupyter kernels.
Jupyter Notebook
378
star
8

sphinx-tabs

Tabbed views for Sphinx
HTML
265
star
9

sphinx-copybutton

Add a "copy" button to code blocks in Sphinx
JavaScript
231
star
10

MyST-NB

Parse and execute ipynb files in Sphinx
Jupyter Notebook
207
star
11

sphinx-design

A sphinx extension for designing beautiful, screen-size responsive web components.
Python
180
star
12

cookiecutter-jupyter-book

Cookiecutter template for a simple jupyter book
TeX
138
star
13

jupyterlab-myst

Use MyST Markdown directly in Jupyter Lab
TypeScript
129
star
14

meta

A community dedicated to supporting tools for technical and scientific communication and interactive computing
129
star
15

sphinx-panels

A sphinx extension for creating panels in a grid layout
Python
85
star
16

rst-to-myst

Convert ReStructuredText to MyST Markdown
Python
58
star
17

github-activity

Simple markdown changelogs for GitHub repositories
Python
48
star
18

jupyter-cache

A defined interface for working with a cache of executed jupyter notebooks
Jupyter Notebook
44
star
19

sphinx-togglebutton

Show and hide content with a button in Sphinx
JavaScript
42
star
20

myst-vs-code

A syntax highlighter for the MyST Markdown format
TypeScript
35
star
21

quantecon-mini-example

A short example showing how to write a lecture series using Jupyter Book 2.0.
Python
34
star
22

sphinx-external-toc

A sphinx extension that allows the site-map to be defined in a single YAML file
Python
31
star
23

sphinx-proof

A Sphinx extension for producing proof, theorem, lemma, definition, remark, conjecture, corollary and algorithm directives.
Python
30
star
24

sphinx-jupyterbook-latex

Supporting LaTeX infrastructure for Jupyter Book
Python
28
star
25

sphinx-thebe

A Sphinx extension to convert static code into interactive code cells with Jupyter, Thebe, and Binder.
Python
28
star
26

mdit-py-plugins

Collection of core plugins for markdown-it-py
Python
28
star
27

sphinx-comments

hypothes.is interaction layer with Sphinx
Python
21
star
28

sphinx-exercise

A Sphinx extension for producing exercise and solution directives.
HTML
18
star
29

sphinx-multitoc-numbering

A Sphinx extension to support continuous numbering of sections across multiple tocs in HTML output.
Python
14
star
30

sphinx-remove-toctrees

Speed up Sphinx builds by selectively removing toctrees from some pages
Python
14
star
31

github-action-demo

A demonstration repository to build and host a book with GitHub Actions
TeX
14
star
32

quantecon-example

A demonstration of Jupyter Book functionality using QuantEcon Python programming source material.
Python
14
star
33

myst-spec

MyST is designed to create publication-quality, computational documents written entirely in Markdown.
TypeScript
13
star
34

markdown-it-docutils

A markdown-it plugin for implementing docutils style roles/directives.
TypeScript
12
star
35

mdformat-tables

An mdformat plugin for rendering tables
Python
11
star
36

mdurl

URL utilities for markdown-it (a Python port)
Python
11
star
37

jupyterlab-mystjs

Jupyterlab extension using the MySTjs parser
TypeScript
8
star
38

myst-enhancement-proposals

MyST Enhancement Proposals (MEPs)
8
star
39

myst-theme

Packages for creating MyST websites themes using React and Remix
TypeScript
8
star
40

mdformat-myst

Mdformat plugin for MyST compatibility
Python
7
star
41

cli

πŸ›‘πŸ›‘DEPRECATED, see https://github.com/ExecutableBookProject/jupyter-bookπŸ›‘πŸ›‘
Python
7
star
42

web-compile

A CLI to compile/minify SCSS & JS, and associated pre-commit hook.
Python
7
star
43

unified-myst

A repository of packages for working with MyST in the https://unifiedjs.com/ ecosystem
JavaScript
6
star
44

markdown-it-plugin-template

A template for creating a markdown-it plugin.
JavaScript
6
star
45

sphinx-ext-mystmd

Integrate existing Sphinx projects with MyST-MD
Python
5
star
46

sphinx-examples

A Sphinx extension to create examples of source markdown and the result of rendering it.
Python
5
star
47

sphinx-ext-autodoc

Auto-documentation for sphinx extension components
Python
5
star
48

sphinx-tomyst

A sphinx translator for producing myst syntax files
Python
4
star
49

mistletoe-ebp

The EPB fork of mistletoe: A fast, extensible and spec-compliant Markdown parser in pure Python.
Python
4
star
50

jupyterlab-myst-quickstart

Quickstart examples for working with MyST in Jupyter
Jupyter Notebook
4
star
51

mdformat-plugin

A template for creating an mdformat parser extension plugin
Python
4
star
52

rst2myst

Tools for converting RST files to MyST-NB files
Python
4
star
53

myst-react

A web-based UI for rendering MyST Markdown
TypeScript
4
star
54

.github

Community health files: Contributing guidelines, Code of Conduct, ...
4
star
55

markdown-it-dollarmath

A markdown-it plugin for $-delimited math
TypeScript
4
star
56

myst

Myst - Markedly Structured Text
3
star
57

python-pkg-cookiecutter

A cookiecutter for python packages, with docs and GitHub Actions CI
Python
3
star
58

mdformat-footnote

Footnote format addition for mdformat
Python
3
star
59

markdown-it-amsmath

A markdown-it plugin for amsmath LaTeX environments.
TypeScript
3
star
60

markdown-it-myst-extras

Additional plugins required for the MyST specification
TypeScript
2
star
61

myst-standard

A meta-repository to discuss and plan for the MyST standard
2
star
62

mystmd-quickstart

Repository to be used in the mystjs quickstart guide
Jupyter Notebook
2
star
63

myst-book-theme

A lightweight MyST theme designed to mimic the look-and-feel of an interactive book.
TypeScript
2
star
64

sphinx-jupyter-book-theme

An experimental Sphinx theme for Jupyter Book
HTML
2
star
65

myst-article-theme

A light-weight theme for rendering scientific articles and associated notebooks
TypeScript
2
star
66

mystmd.org

The website theme and landing content for mystmd.org
TypeScript
2
star
67

write_ups

Write ups and publications that document the project
1
star
68

sphinx-conditional-asset

A small extension for developers of Sphinx to conditionally add assets to a page.
Python
1
star
69

sphinx-yaml-config

Python
1
star