Authoring Markdown

Our sites support writing content in Markdown, with some additions from GitHub Flavored Markdown as well as other custom syntaxes.

This page outlines the Markdown syntax we support as well as our style guidelines for authoring Markdown.

Prefer using Markdown syntax over custom HTML and components. Raw Markdown is easier to maintain, easier for tools to understand, and easier to migrate in the future if necessary.

Don't use Markdown's indented code blocks, only use fenced code blocks using backticks and always specify a language. For example:

```dart
void main() {
  print('Hello world!');
}
```

To learn more about customizing code blocks, check out the dedicated documentation on Code blocks.

To render flowcharts, sequence diagrams, and other charts within a Markdown file, use a fenced code block with the mermaid language identifier:

```mermaid
flowchart LR
    A[Start] --> B(Process)
    B --> C{Decision}
    C -->|Yes| D[Done]
    C -->|No| B
```

Mermaid diagrams are rendered to SVG on the server, once for each theme. Both variants ship in the page and CSS shows the one matching the site's current light or dark theme. Diagrams inherit the default Google Sans Flex typography.

When you need custom colors for specific nodes, define them directly in the diagram using Mermaid's built-in classDef and :::styleName syntax:

To adjust the global diagram layout, border, or background across the site, edit _mermaid.scss:

.mermaid-container {
  // Container styling (padding, margins, background, border)

  // Fallback shown only if server rendering the diagram failed
  pre.mermaid {
    // Fallback styles
  }

  .mermaid-theme {}

  .mermaid-theme-light {}

  .mermaid-theme-dark {}

  svg {
    // Custom SVG element overrides (requires !important)
  }
}