13.1. MyST Markdown Basics¶

MyST Markdown is Markdown with extra features for technical documentation. A MyST page is still plain text: write the content first, then use headings and links to make it easy to read and navigate.

This tutorial introduces the syntax you need for a first page. It also shows how to add a diagram, link to a section, add a footnote, and cite a source. The MyST reference covers these and other features in more detail.

13.1.1. 1. Write paragraphs and format text¶

Separate paragraphs with a blank line. Use asterisks for emphasis and backticks for short code or technical names:

Hermesbaby builds documentation from Markdown files.

Use **bold** for emphasis, *italics* for a lighter emphasis, and `inline code` for names.

For details, see Paragraphs and Basic Inline Formatting in the reference.

13.1.2. 2. Add headings¶

Use # for the page title and add more # characters for sections. Keep heading levels in order:

# Getting Started

## Install Hermesbaby

### Check the installation

Each page should have one title. Do not skip a level, such as going from ## directly to ####. See Headings for heading syntax and levels.

13.1.3. 3. Make lists¶

Use asterisks for unordered lists and numbers for steps:

* Source files are plain text.
* Pages can link to one another.

1. Write a page.
2. Build the documentation.
3. Check the rendered result.

Indent nested items by two spaces. See Lists for list syntax and variants.

13.1.4. 4. Make a table¶

Use a pipe table for a few short values:

| Command | Purpose |
| ------- | ------- |
| `hb html` | Build the documentation |
| `hb html --live` | Preview changes |

For details and longer tables, see Tables.

13.1.5. 5. Add links and code blocks¶

Use standard Markdown links for websites and other pages:

[Hermesbaby on PyPI](https://pypi.org/project/hermesbaby/)
[Another page](../12-Glossary/index.md)

See Links for external, page-relative, and labeled links.

Use backticks for a command or short code snippet. For multiple lines, put the code in a fenced block and add its language after the opening fence for syntax highlighting:

Run `hb html` to build the documentation.

```python
print("Hello, documentation!")
```

See Code for inline code, fenced blocks, and code-block options.

13.1.6. 6. Connect pages¶

When your documentation has more than one page, list child pages in a {toctree} on the section's index.md:

```{toctree}
:maxdepth: 1

getting-started
reference
```

Entries are paths relative to the current file and omit the .md extension. A folder's index.md is its entry point. See Table of Contents: {toctree} for toctree options and Document Structure for page and folder structure.

13.1.7. 7. Add a DrawIO figure¶

Save the diagram as a .drawio file in a _figures/ folder next to the page, then embed it with the {drawio-figure} directive:

```{drawio-figure} _figures/system_overview.drawio

System overview.
```

For a static exported .drawio.svg, use {figure} instead. See {drawio-figure} — DrawIO Source Diagrams and Figures for figure formats and options.

13.1.8. 8. Link to a section¶

Add a label immediately before the heading you want to link to, then use {ref} where the link should appear:

(sec_installation)=
## Installation

Install Hermesbaby before building the documentation.

See {ref}`sec_installation` for installation instructions.

Labels are stable identifiers; use lowercase words separated by underscores. To refer to a figure by its number, use {numref} with the figure label, such as {numref}fig_system_overview``. See Cross-Reference Labels for label and reference syntax.

13.1.9. 9. Add a footnote¶

Put a footnote marker where the extra detail belongs and define its text elsewhere on the page:

MyST supports footnotes[^myst-note].

[^myst-note]: Use footnotes for useful asides that would interrupt the main text.

See Footnotes for footnote syntax and guidance.

13.1.10. 10. Cite a source¶

Add a BibTeX entry to docs/bibliography.bib, then cite its key in your text with {cite}:

<!-- Add this entry to docs/bibliography.bib -->
```bibtex
@online{myst_docs,
  title = {MyST Markdown Documentation},
  author = {{Executable Books Project}},
  url = {https://myst-parser.readthedocs.io/}
}
```

MyST extends Markdown for technical documentation {cite}`myst_docs`.

To display the cited sources on a bibliography page, add the {bibliography} directive:

```{bibliography}
```

The project's docs/99-Appendix/04-Bibliography/index.md is an example. See {cite} — Bibliographic Citations for citations and bibliography display.

13.1.11. 11. Quote a passage¶

Start a line with > to format it as a blockquote:

> Clear documentation helps readers understand a system.

See Blockquotes for blockquote syntax.

13.1.12. 12. Add a callout¶

Use an admonition to make a note or warning stand out from the surrounding text:

```{note}
Run `hb html` to build the documentation.
```

```{warning}
Check the rendered page before publishing.
```

See Admonitions for callout types and Directives for the general directive syntax.

13.1.13. Next steps¶

Build and preview the page with Hermesbaby. Once the basics feel familiar, continue to the complete MyST reference for more options and examples.