From 943e3dc057eca53e68ddec51529bd6a1279ebd8e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 29 Apr 2024 06:23:02 +0200 Subject: Adding upstream version 0.18.1. Signed-off-by: Daniel Baumann --- docs/intro.md | 250 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 docs/intro.md (limited to 'docs/intro.md') diff --git a/docs/intro.md b/docs/intro.md new file mode 100644 index 0000000..dc65728 --- /dev/null +++ b/docs/intro.md @@ -0,0 +1,250 @@ +(intro/get-started)= +# Get Started + +This page describes how to get started with the MyST parser, with a focus on enabling it in the Sphinx documentation engine. + +## Installation + +[![PyPI][pypi-badge]][pypi-link] +[![Conda][conda-badge]][conda-link] + +To install use [pip](https://pip.pypa.io): + +```bash +pip install myst-parser +``` + +or [Conda](https://docs.conda.io): + +```bash +conda install -c conda-forge myst-parser +``` + +[pypi-badge]: https://img.shields.io/pypi/v/myst-parser.svg +[pypi-link]: https://pypi.org/project/myst-parser +[conda-badge]: https://anaconda.org/conda-forge/myst-parser/badges/version.svg +[conda-link]: https://anaconda.org/conda-forge/myst-parser + +(intro/sphinx)= +## Enable MyST in Sphinx + +To get started with Sphinx, see their [Quickstart Guide](https://www.sphinx-doc.org/en/master/usage/quickstart.html). + +To use the MyST parser in Sphinx, simply add the following to your `conf.py` file: + +```python +extensions = ["myst_parser"] +``` + +This will activate the MyST Parser extension, causing all documents with the `.md` extension to be parsed as MyST. + +:::{tip} +To parse single documents, see the [](docutils.md) section +::: + +(intro/writing)= +## Write a CommonMark document + +MyST is an extension of [CommonMark Markdown](https://commonmark.org/), +that includes [additional syntax](../syntax/syntax.md) for technical authoring, +which integrates with Docutils and Sphinx. + +To start off, create an empty file called `myfile.md` and give it a markdown title and text. + +```md +# My nifty title + +Some **text**! +``` + +To parse to HTML, try the CLI: + +```html +$ myst-docutils-html5 --stylesheet= myfile.md + + + + + +My nifty title + + + +

My nifty title

+ +

Some text!

+ + +``` + +To include this document within a Sphinx project, +include `myfile.md` in a [`toctree` directive](sphinx:toctree-directive) on an index page. + +## Extend CommonMark with roles and directives + +MyST allows any Sphinx role or directive to be used in a document. +These are extensions points allowing for richer features, such as admonitions and figures. + +For example, add an `admonition` directive and `sup` role to your Markdown page, like so: + +````md +# My nifty title + +Some **text**! + +```{admonition} Here's my title +:class: tip + +Here's my admonition content.{sup}`1` +``` +```` + +Then convert to HTML: + +```html +$ myst-docutils-html5 --stylesheet= myfile.md +... +

Here's my title

Here's my admonition content.¹

+... +``` + +:::{seealso} +The full [](syntax/roles-and-directives.md) section +::: + +(intro/reference)= +## Cross-referencing + +MyST-Parser offers powerful cross-referencing features, to link to documents, headers, figures and more. + +For example, to add a section *reference target*, and reference it: + +```md +(header-label)= +# A header + +[My reference](header-label) +``` + +```html +$ myst-docutils-html5 --stylesheet= myfile.md +... + +

A header

+ +

My reference

+... +``` + +:::{seealso} +The [](syntax/referencing) section,\ +and the [ReadTheDocs cross-referencing](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html) documentation +::: + +## Configuring MyST-Parser + +The [](configuration.md) section contains a complete list of configuration options for the MyST-Parser. + +These can be applied globally, e.g. in the sphinx `conf.py`: + +```python +myst_enable_extensions = [ + "colon_fence", +] +``` + +Or they can be applied to specific documents, at the top of the document: + +```yaml +--- +myst: + enable_extensions: ["colon_fence"] +--- +``` + +## Extending Sphinx + +The other way to extend MyST in Sphinx is to install Sphinx extensions that define new roles, directives, etc. + +For example, let's install the `sphinxcontrib.mermaid` extension, +which will allow us to generate [Mermaid diagrams](https://mermaid-js.github.io/mermaid/#/) with MyST. + +First, install `sphinxcontrib.mermaid`: + +```shell +pip install sphinxcontrib-mermaid +``` + +Next, add it to your list of extensions in `conf.py`: + +```python +extensions = [ + "myst_parser", + "sphinxcontrib.mermaid", +] +``` + +Now, add a **mermaid directive** to your markdown file. +For example: + +````md +# My nifty title + +Some **text**! + +```{admonition} Here's my title +:class: warning + +Here's my admonition content +``` + +(section-two)= +## Here's another section + +And some more content. + +% This comment won't make it into the outputs! +And here's {ref}`a reference to this section `. +I can also reference the section {ref}`section-two` without specifying my title. + +:::{note} +And here's a note with a colon fence! +::: + +And finally, here's a cool mermaid diagram! + +```{mermaid} +sequenceDiagram + participant Alice + participant Bob + Alice->John: Hello John, how are you? + loop Healthcheck + John->John: Fight against hypochondria + end + Note right of John: Rational thoughts
prevail... + John-->Alice: Great! + John->Bob: How about you? + Bob-->John: Jolly good! +``` +```` + +When you build your documentation, you should see something like this: + +```{mermaid} +sequenceDiagram + participant Alice + participant Bob + Alice->John: Hello John, how are you? + loop Healthcheck + John->John: Fight against hypochondria + end + Note right of John: Rational thoughts
prevail... + John-->Alice: Great! + John->Bob: How about you? + Bob-->John: Jolly good! +``` -- cgit v1.2.3