mds

The server renders GitHub Flavored Markdown with a few additions: Mermaid diagrams, heading anchors, and slides mode.

Tables¶⎘

GFM table syntax with pipes and hyphens:

| Name    | Type   | Required |
| ------- | ------ | -------- |
| title   | string | yes      |
| summary | string | no       |

The above renders as a table with three columns. Alignment markers (:---, :---:, ---:) work in the header-separator row.

Task lists¶⎘

- [ ] and - [x] render as checkboxes:

- [x] Write the spec
- [ ] Review the implementation
- [ ] Ship it

Checked items carry a strikethrough. See mds.on_check for how that key controls what happens when a checkbox is toggled--checked items can be hidden or moved to a ## Done section automatically.

Code blocks¶⎘

Wrap code in triple-backtick fences with a language identifier:

```go
func greet(name string) string {
    return "hello, " + name
}
```

Supported language identifiers: bash / sh, css, diff, go, html / xml, javascript / js / jsx, json, markdown / md, python / py, rust / rs, sql, typescript / ts / tsx, yaml / yml. Syntax highlighting is provided by highlight.js. Fences with an unrecognized identifier render as plain monospace.

Mermaid diagrams¶⎘

Fenced ```mermaid blocks render to SVG inline:

```mermaid
graph LR
    A[Write doc] --> B[Push]
    B --> C[Deploy]
```

MDS renders labels as SVG text and rejects HTML label elements. Use a Mermaid Markdown string for emphasis and <br/> for an explicit line break:

```mermaid
flowchart TD
    os["`**os/**<br/>listeners and connections`"]
    init["`InitOutput()<br/>_supplied by the final DDX_`"]
```

<br>, <br/>, and <br /> are supported. Elements such as <b>, <i>, <span>, <div>, and <img> are not. For example, replace <b>os/</b> with **os/** inside a backtick-delimited Mermaid Markdown string. Uploads containing unsupported label markup fail with a source-positioned error.

Labels remain centered unless the diagram requests left alignment with a class:

```mermaid
flowchart TD
    os["`**os/**<br/>listeners and connections`"]
    dix["`**dix/**<br/>dispatch, resources, and windows`"]

    classDef prose text-align:left
    class os,dix prose
```

Mermaid accepts text-align:left but does not yet position SVG labels correctly; see mermaid#6706 and mermaid#1177. MDS supplies the missing SVG positioning behavior.

Use subgraphs for containment and arrows only for relationships that are directional. Before authoring Mermaid, run mds guide mermaid; before pushing, run mds lint <file>. mds push --dry-run performs the same validation as a real push.

Agent workspaces can include this instruction:

Before authoring Mermaid for MDS, run `mds guide mermaid`.
Before pushing an authored document, run `mds lint <file>`.
MDS uses SVG-only Mermaid labels and rejects HTML label markup.

See mermaid.js.org for the full syntax reference. Flowcharts, sequence diagrams, Gantt charts, and most other diagram types are supported subject to the SVG-label restrictions above.

Heading anchors¶⎘

Every heading gets a slug-based id and a paragraph-mark permalink appended. Deep-link to any section with #slug--the slug is the heading text lowercased with spaces replaced by hyphens. Duplicate headings get a numeric suffix (-1, -2, ...).

## My Section

Link to it with [anchor](#my-section).

Slides mode¶⎘

Setting kind: slides in frontmatter splits the document into a slide deck at --- thematic breaks. Each slide occupies the full viewport; advance through the deck with the keyboard or by clicking.

---
kind: slides
---

## Slide one

Content for the first slide.

---

## Slide two

Content for the second slide.

See Frontmatter for the full kind: slides frontmatter reference. In regular docs (no kind: slides), --- renders as a horizontal rule.