An extended commonmark compliant parser, with bridges to docutils & sphinx.

pip install -e "git https://github.com/ExecutableBookProject/MyST-Parser.git#egg=myst-parser[sphinx]"

Or for package development:

git clone https://github.com/ExecutableBookProject/MyST-Parser
cd MyST-Parser
git checkout develop
pip install -e .[sphinx,code_style,testing,rtd]

Note, this parser currently requires the ExecutableBookProject/mistletoe fork of mistletoe (included in the above installation).

To use the MyST parser in Sphinx, simply add: extensions = ["myst_parser"] to your conf.py.

For more information, also see the CommonMark Spec.

• FrontMatter: A YAML block at the start of the document enclosed by ---
• HTMLBlock: Any valid HTML (rendered in HTML output only)
• LineComment: % this is a comment
• BlockCode: indented text (4 spaces)
• Heading: # Heading (levels 1-6)
• SetextHeading: underlined header
• Quote: > this is a quote
• CodeFence: enclosed in 3 or more backticks. If it starts with a {name}, then treated as directive.
• ThematicBreak: ---
• List: bullet points or enumerated.
• Table: Standard markdown table styles.
• Footnote: A substitution for an inline link (e.g. [key][name]), which can have a reference target (no spaces), and an optional title (in "), e.g. [key]: https://www.google.com "a title"
• Paragraph: General inline text

• Role: `{name}`interpreted text`
• Math: $a=1$ or $$a=1$$
• HTMLSpan: any valid HTML (rendered in HTML output only)
• EscapeSequence: \*
• AutoLink: <http://www.google.com>
• Target: (target)= (precedes element to target, e.g. header)
• InlineCode: `a=1`
• LineBreak: Soft or hard (ends with spaces or \)
• Image: ![alt](src "title")
• Link: [text](target "title") or [text][key] (key from Footnote)
• Strong: **strong**
• Emphasis: *emphasis*
• RawText

Code style is tested using flake8, with the configuration set in .flake8, and code formatted with black.

Installing with myst-parser[code_style] makes the pre-commit package available, which will ensure this style is met before commits are submitted, by reformatting the code and testing for lint errors. It can be setup by:

>> cd MyST-Parser
>> pre-commit install

Optionally you can run black and flake8 separately:

>> black .
>> flake8 .

Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.

To contribute, make Pull Requests to the develop branch (this is the default branch). A PR can consist of one or multiple commits. Before you open a PR, make sure to clean up your commit history and create the commits that you think best divide up the total work as outlined above (use git rebase and git commit --amend). Ensure all commit messages clearly summarise the changes in the header and the problem that this commit is solving in the body.

Merging pull requests: There are three ways of 'merging' pull requests on GitHub:

• Squash and merge: take all commits, squash them into a single one and put it on top of the base branch. Choose this for pull requests that address a single issue and are well represented by a single commit. Make sure to clean the commit message (title & body)
• Rebase and merge: take all commits and 'recreate' them on top of the base branch. All commits will be recreated with new hashes. Choose this for pull requests that require more than a single commit. Examples: PRs that contain multiple commits with individually significant changes; PRs that have commits from different authors (squashing commits would remove attribution)
• Merge with merge commit: put all commits as they are on the base branch, with a merge commit on top Choose for collaborative PRs with many commits. Here, the merge commit provides actual benefits.