13.1. MyST Markdown

This documentation uses MyST Markdown — a superset of CommonMark that adds directives, roles, and cross-referencing to plain Markdown. This guide walks through every syntax construct used in this project, starting from the basics you'll need every day and ending with the more specialized features.

13.1.1. Document Structure

Every file is a self-contained page. The minimal skeleton looks like this:

(sec_my_section_label)=
# My Page Title

First paragraph of content.

13.1.1.1. Table of Contents: {toctree}

Every section index file defines which child pages appear under it using the {toctree} directive:

```{toctree}
:maxdepth: 2

01-Introduction/index
02-Setup/index
03-Reference/index
```

Paths are relative to the current file and omit the .md extension. The :hidden: option keeps the entries out of the rendered page body while still building the navigation tree.

13.1.2. Headings

Use ATX-style headings. Each file should have exactly one H1 (#) as its page title. Subsequent levels provide section hierarchy:

# Page Title (H1 — one per file)
## Major Section (H2)
### Subsection (H3)
#### Minor subsection (H4)

Note

Heading levels also determine navigation depth. Avoid skipping levels (e.g. jumping from ## to ####).

13.1.3. Paragraphs and Basic Inline Formatting

Separate paragraphs with a blank line. Inline formatting:

Effect

Syntax

Result

Bold

**text**

text

Italic

*text*

text

Inline code

`code`

code

Inline code (backtick) is the most common inline element — use it for identifiers, file names, configuration keys, and technical terms.

13.1.4. Lists

13.1.4.1. Unordered Lists

Use * as the bullet marker (see Conventions for the rationale):

* System Engineering
* Software Engineering
* Hardware Engineering

13.1.4.2. Ordered Lists

1. Define the system boundary
2. Identify stakeholders
3. Elicit requirements

13.1.4.3. Nested Lists

Indent with two spaces to nest:

* Engineering disciplines
  * System Engineering
  * Software Engineering
* Management disciplines
  * Risk Management

Note

Keep nesting shallow. Two levels is usually enough; three or more levels is a sign the content wants to be a subsection instead.

13.1.4.4. Task Lists

Checkbox lists mark completion status (used primarily in requirement checklists):

* [x] Done
* [ ] Not yet done

13.1.6. Figures

All figures — raster images, exported SVGs, and DrawIO source files — live in a _figures/ subfolder next to your index.md and are embedded with a directive, not plain Markdown image syntax. Directives give you captions, cross-reference labels, and layout options.

13.1.6.1. {figure} — Images and Exported SVGs

Use {figure} for any static image file (.png, .svg, .jpg, .drawio.svg):

(fig_my_diagram)=
```{figure} _figures/my-diagram.png
:align: center
:width: 80%

Caption text that appears below the image.
```

The (fig_my_diagram)= line directly above the directive creates an anchor so you can cross-reference this figure from anywhere:

As shown in {numref}`fig_my_diagram`, the system has three layers.

Common options:

Option

Example

Effect

:align:

center

Horizontal alignment (left, center, right)

:width:

80% or 15cm

Rendered width

:scale:

60%

Scale relative to original size

:alt:

"a graph"

Accessibility / screen-reader text

:name:

fig_my_name

Inline label, alternative to the (label)= prefix

13.1.6.2. DrawIO File Formats Compared

DrawIO diagrams can be committed and embedded in three ways. Each has different trade-offs for git, IDE preview, and build complexity:

Aspect

.drawio.png

.drawio.svg

.drawio

Directive

{figure}

{figure}

{drawio-figure}

Git diff

binary — no diff

text-based XML diff

text-based XML diff

Git LFS needed

recommended

no

no

IDE / GitHub preview

instant raster preview

renders as vector

renders as diagram (GitHub)

Vector / scalable

no

yes

yes

Print / high-DPI quality

limited by export resolution

crisp at any size

crisp at any size

Build-time dependency

none

none

DrawIO plugin required

Multi-page support

one export per page

one export per page

:page-name: selects page

Hyperlinks in diagram

lost on export

lost on export

preserved

Embedded source in file

yes (in PNG metadata)

yes (in SVG XML)

the file is the source

.drawio.png — Simplest to preview everywhere but bloats the repository over time and produces binary diffs. Export at 2× or higher resolution to stay readable on high-DPI screens. Use only when the build environment has no SVG renderer or when a raster is explicitly required.

.drawio.svg — Best default for most diagrams. Scales losslessly, diffs as text, previews in the IDE and on GitHub, and requires no build plugin. The SVG file also carries the DrawIO XML source in an embedded attribute, so the original diagram is always recoverable. Use {figure} to embed it:

```{figure} _figures/architecture.drawio.svg
:align: center
:width: 90%

System context overview.
```

.drawio — Use when you need multi-page navigation or hyperlinks between diagram nodes. The {drawio-figure} plugin renders the raw source server-side during the build.

13.1.6.3. {drawio-figure} — DrawIO Source Diagrams

Use {drawio-figure} when you want to embed a .drawio file directly — the plugin renders it server-side and preserves navigation links between diagram pages:

(fig_architecture_overview)=
```{drawio-figure} _figures/architecture.drawio
:page-name: Overview

Caption text.
```

The :page-name: option selects which tab of the multi-page DrawIO file to render. If the file has only one page the option can be omitted.

Note

If you exported a DrawIO diagram as a static .drawio.svg file, use the plain {figure} directive instead — {drawio-figure} expects the raw .drawio XML source.

13.1.7. Tables

13.1.7.1. Pipe Tables

Standard Markdown pipe syntax works for simple tables with short, plain-text cells:

| Version | Change | Reviewer |
| ------- | ------ | -------- |
| 1.0 | Initial release | J. Smith |
| 1.1 | Added appendix | A. Jones |

13.1.7.1.1. Column Alignment

Control per-column alignment with colons in the separator row:

Alignment

Separator syntax

Typical use

Left

:---

Text, names, descriptions (default)

Center

:---:

Short labels, status values, icons

Right

---:

Numbers, versions, sizes

Example combining all three:

| Name | Status | Count |
| :--- | :----: | ----: |
| Alpha | active | 42 |
| Beta | draft | 7 |

Use pipe tables when the source reads well at a glance — two or three short columns. For longer cell content, mixed inline markup, or more than three columns, use {list-table} instead.

13.1.7.2. {list-table} Directive

{list-table} is more structured and handles long cell content reliably:

```{list-table}
:header-rows: 1

* - Version
  - Change
  - Reviewer
  - Comment
* - 1.0
  - Initial release
  - J. Smith
  - Approved
```

Each row starts with * - and subsequent cells are indented two spaces followed by -. The :header-rows: 1 option makes the first row a header. Cells can contain any inline markup, code spans, or even nested lists.

13.1.8. Code

13.1.8.1. Inline Code

Use single backticks for short code snippets, commands, or technical terms inline with text:

Run `git tag -m <msg> <tagname>` to create an annotated tag.

13.1.8.2. Fenced Code Blocks

Use triple backticks with an optional language identifier for multi-line code:

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

Common language tags used in this project: python, bash, json, yaml, xml, cpp, javascript, sql, console, text.

For a plain block without highlighting, omit the language tag.

13.1.8.3. {code-block} Directive

The directive form gives you additional options (line numbers, highlighted lines, captions). Use it when you need those features; otherwise the fenced form is simpler:

```{code-block} json
:linenos:

{
    "key": "value"
}
```

13.1.8.4. Nesting Code Inside Directives

If a code block appears inside a directive, wrap the outer directive with four backticks so the three-backtick fence inside is not misread:

````{note}
Here is an example:

```python
print("hello")
```
````

13.1.9. Blockquotes

Use > for quotations from external sources:

> A system is an arrangement of parts or elements that together exhibit behavior
> or meaning that the individual parts do not.
> (Quote from {cite}`iso_24748_1_2024`)

13.1.10. Admonitions

Admonitions are colored call-out boxes that use the directive syntax.

13.1.10.1. Standard Admonition Types

```{note}
Use `note` for neutral supplemental information.
```

```{hint}
Use `hint` to give the reader a helpful tip.
```

```{important}
Use `important` for information the reader must not overlook.
```

```{attention}
Use `attention` as a lighter-weight alternative to `warning`.
```

```{warning}
Use `warning` when incorrect actions could cause problems.
```

```{danger}
Use `danger` for irreversible or destructive actions.
```

Hint

All admonition types accept any MyST content inside them: lists, code blocks, inline roles, and even nested directives.

13.1.10.2. Generic {admonition} with Custom Title

When you want a custom title, use the generic {admonition} directive and set :class: to a standard type name:

```{admonition} Caveat: Build Environment Configuration
:class: warning

The `commit ID` of the source code must be recorded at build time.
```

13.1.10.3. {todo} — Editorial Placeholders

Use {todo} to mark content that still needs to be written. Rendered visibly in draft builds; can be suppressed in release builds. Can carry a title:

```{todo}
Describe the release branching strategy.
```

```{todo} Describe Content Creation Process
Explain how to manage branches and create content.
```

13.1.11. Directives

Directives are the core building block of MyST. The syntax is a fenced code block where the language is a directive name in curly braces:

```{directive-name} optional-argument
:option-key: option-value

Content body (optional).
```

The argument goes on the same line as the directive name. Options are :key: value lines immediately after the opening fence, before any blank line. The content comes after any options and an optional blank line.

13.1.11.1. Figures and Images

Use {figure} for images that need a caption or a cross-reference label:

(fig_my_diagram)=
```{figure} _figures/my-diagram.drawio.svg
:align: center
:width: 80%

Caption text that appears below the image.
```

Common figure options:

Option

Example

Effect

:align:

center

Horizontal alignment

:width:

80% or 15cm

Rendered width

:scale:

60%

Scale relative to original

:alt:

"a graph"

Accessibility text

:name:

fig_my_name

Alternative to the (label)= syntax

The line (fig_my_diagram)= directly above the directive creates an anchor for cross-referencing.

13.1.11.2. Draw.io Diagrams

For .drawio source files with embedded navigation links, use {drawio-figure}:

```{drawio-figure} _figures/architecture.drawio
:page-name: Overview

Caption text.
```

The :page-name: option selects which tab of the DrawIO file to render. For static exported .drawio.svg files, use the plain {figure} directive instead. See Conventions for details on the two formats.

13.1.11.3. UML Diagrams

For PlantUML .puml files, use {uml}:

```{uml} _figures/sequence.puml
:caption: Sequence diagram title
:width: 25cm

```

13.1.11.4. Code Blocks with Options

The {code-block} directive adds options unavailable in plain fenced blocks:

```{code-block} python
:linenos:
:emphasize-lines: 3

def greet(name):
    # This line is highlighted
    return f"Hello, {name}!"
```

13.1.11.5. Glossary

Define terms in a {glossary} directive:

```{glossary}

My Term
    This is the definition. It can span multiple paragraphs.

Another Term
    Another definition. Refer to related terms with {term}`My Term`.
```

13.1.11.6. Card

The {card} directive renders a bordered box, useful for prominent notices:

```{card}
This is a preview of the VITRONIC Engineering Handbook.
The Handbook has not been approved so that there is no released version yet.
```

13.1.12. Roles (Inline Directives)

Roles are inline elements that produce rich output. The syntax is:

{role-name}`content`

13.1.12.1. {ref} — Internal Cross-References

See {ref}`sec_authoring_guide` for details.

13.1.12.2. {numref} — Numbered Figure References

The diagram {numref}`fig_my_diagram` shows the architecture.

13.1.12.3. {term} — Glossary Terms

Links a term to its definition in the glossary:

The {term}`Digitaler Zwilling` is the core data model.

13.1.12.4. {abbr} — Abbreviations with Expansions

Renders the abbreviation with a tooltip showing the full form:

The {abbr}`SoI(System of Interest)` defines the scope.

13.1.12.5. {cite} — Bibliographic Citations

Links to an entry in the bibliography:

As defined in {cite}`iso_24748_1_2024`, the lifecycle has six stages.

13.1.12.7. Project-Specific Roles

Role

Example

Renders as

{jira}

{jira}`PJBIO-1060`

Link to Jira ticket

{user}

{user}`AMAN`

Mention a team member

{repo}

{repo}`biom/BiomechWebGui`

Link to repository

{param}

{param}`«component» WebGui`

Highlight a parameter

{kbd}

{kbd}`Ctrl+S`

Keyboard shortcut: Ctrl+S

{download}

{download}`_attachments/spec.pdf`

File download link

13.1.13. Definition Lists

For term–definition pairs (API methods, glossary-like content within a page):

`method_name(arg)`:
: What the method returns or does.

`another_method()`:
: Another definition. Can span
  multiple lines.

The term line ends with :, and the definition starts with : on the next line.

13.1.14. Footnotes

Place a footnote marker inline, then define it anywhere in the file:

This concept[^fn1] is important.

[^fn1]: Full explanation of the concept.

The rendered footnote appears at the bottom of the page. Use footnotes for tangential clarifications that would interrupt the main flow if inlined.

13.1.14.1. File Frontmatter

Frontmatter is a YAML block between --- delimiters at the very top of the file. It is optional but used when needed:

---
orphan: true
---

The orphan: true key suppresses Sphinx warnings for pages not included in any {toctree}. Use it for standalone pages or drafts not yet wired into the navigation. See Conventions for the full policy.

13.1.15. HTML Comments

Use HTML comments to hide editorial notes, disabled content, or temporarily disabled directives from the rendered output:

<!--
This section is intentionally left blank until the review is complete.
-->

Comments also work to disable a directive block:

<!--
```{todo}
Add example project walkthrough
```
-->

13.1.16. Alternative Directive Fence Style

Directives can also use ::: fences instead of backtick fences. The two styles are equivalent — use whichever you prefer, but be consistent within a file:

:::{drawio-figure} _figures/diagrams.drawio
:page-name: Overview
:::

The ::: style is useful when the directive content itself contains backtick fences, avoiding ambiguity.

13.1.17. Quick Reference

Element

Syntax

When to use

Bold

**text**

Emphasize important terms or values

Italic

*text*

Titles of external works, gentle emphasis

Inline code

`code`

File names, identifiers, commands

Fenced code

```lang

Multi-line code samples

Code block (options)

```{code-block} lang

Line numbers, highlights, captions

Section label

(sec_name)=

Before any heading to cross-reference

Figure label

(fig_name)=

Before {figure} directive

Cross-reference

{ref}`sec_name`

Link to a labeled section or figure

Numbered fig ref

{numref}`fig_name`

Reference a numbered figure

Page link

{doc}`/path/index`

Link to another document by path

List table

```{list-table}

All tabular data

Figure

```{figure} path

Images with captions

Draw.io figure

```{drawio-figure} path

Draw.io source diagrams

UML

```{uml} path

PlantUML diagrams

Toctree

```{toctree}

Navigation tree in index files

Glossary

```{glossary}

Term definitions

Card

```{card}

Bordered notice box

Note

```{note}

Supplementary information

Hint

```{hint}

Helpful tip

Important

```{important}

Must-not-overlook information

Attention

```{attention}

Must-read before proceeding

Warning

```{warning}

Hazards or actions that cause problems

Danger

```{danger}

Irreversible or destructive actions

Custom admonition

```{admonition} Title

Admonition with a custom title

Todo

```{todo}

Placeholder for missing content

Glossary term

{term}`Term`

Link to glossary entry

Abbreviation

{abbr}`ABC(Full Name)`

First use of an acronym

Citation

{cite}`bib-key`

Cite a bibliography entry

Jira ticket

{jira}`PJBIO-1234`

Reference a Jira issue

User mention

{user}`ABC`

Mention a team member

Repository

{repo}`biom/repo-name`

Link to a repository

Keyboard key

{kbd}`Ctrl+C`

Keyboard shortcut

Footnote

[^key] / [^key]: text

Supplementary notes

Definition list

`term`: / : definition

Term–definition pairs within a page

Blockquote

> text

Quotations from external sources

HTML comment

<!-- text -->

Hide editorial notes or disabled content