Markdown Reference

mdsite supports standard GitHub Flavored Markdown (GFM) along with several specialized extensions for a premium reading experience.

1. GFM Alerts

Use the following syntax:

> [!NOTE]
> Valuable information that users should bear in mind even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

These are rendered with distinct colors and icons (Info, Check, Primary, Warning, Error) based on our Material Design theme.

2. Blockquotes

Standard markdown blockquotes are rendered as beautiful Material Design Cards:

For example:

> This is a blockquote. It will appear inside a styled card with a left border matching your primary/secondary theme color.
>> This is a nested blockquote.

Will be rendered as:

3. Tables of Contents

A Table of Contents is automatically generated for every page based on the h2 and h3 headings. You don't need to add anything to your markdown files to enable this.

4. Code Blocks

Code blocks support syntax highlighting and are rendered in a monospaced font with a subtle background.

```typescript
// Example code block
const message = "Hello from Nuxt Content!"
console.log(message)
```

This will render as:

// Example code block
const message = "Hello from Nuxt Content!"
console.log(message)

5. Tables with lists

Tables with lists are supported and will be rendered as beautiful Material Design Tables:

For example:

| Plain text       | Line breaks                | List                                                                  |
| ---------------- | -------------------------- | --------------------------------------------------------------------- |
| Blah, blah, blah | Line 1<br/>Line2<br/>Line3 | <ul><li>List item 1</li><li>List item 2</li><li>List item 3</li></ul> |

Will be rendered as:

6. Images

Images are supported using standard Markdown syntax. You can reference local images by their relative path.

For example, to include the project logo:

![MD-Site Logo](../logo.svg)

Will be rendered as:

7. Mermaid Diagrams

You can create diagrams using Mermaid syntax:

```mermaid
flowchart LR
    subgraph authoring[Authoring]
        A[Write Markdown] --> B[Preview locally]
        B --> C{Ready to publish?}
        C -- No --> A
    end

    subgraph publishing[Publishing]
        D[Generate site] --> E[Deploy]
        E --> F[Readers view docs]
    end

    C -- Yes --> D
    F -. Feedback .-> A
```

Will be rendered as:

This will be rendered as a beautiful interactive diagram.

8. Inline TeX formulas

Wrap inline TeX in single dollar signs: $...$. Formulas work in paragraphs, list items, and pipe-table cells without changing the source notation.

For example:

Einstein's mass–energy relation is $E=mc^2$.

Will be rendered as:

Einstein's mass–energy relation is $E=mc^2$.

KaTeX renders formulas during Markdown compilation, with bundled styles and fonts in both mdsite live and mdsite generate. Generated pages contain HTML and MathML, so formulas remain readable with browser JavaScript disabled.

An unmatched dollar sign such as $20 stays literal. Escape dollar signs for currency or literal notation: \$20 and \$30, or \$A_y\$. Two unescaped dollar signs can delimit math even in currency text, so escape each currency dollar when multiple prices appear together. Inline code and fenced code blocks keep $...$ literal.

Use KaTeX-supported commands. Malformed TeX (for example $A_{y$) renders the original TeX in red with a katex-error class and a diagnostic title. Unsupported commands appear literally in red inside the formula. Neither case aborts the site build. An unclosed $ delimiter remains ordinary text, not a TeX error.