Markdown und MDX

Ardo beginnt mit Markdown, beschränkt dich aber nicht darauf. Starte mit Text und Codeblöcken. Benötigt eine Seite ein interaktives React-Beispiel, eine eigene Komponente oder einen Designsystem-Hinweis, wechsle ohne Werkzeugwechsel zu MDX.

Seitendateinamen

Dateien in app/routes/ werden zu Seiten-URLs. Nutze aussagekräftige Namen wie guide/getting-started.mdx oder guide/c-sharp.mdx. # und ? sind in Datei- und Verzeichnisnamen nicht erlaubt, weil sie URL-Fragmente und Queries abgrenzen. In Titeln und Inhalten kannst du sie verwenden.

Grundlegende Syntax

Überschriften

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

Hervorhebungen

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

Listen

- Unordered item 1
- Unordered item 2
  - Nested item

1. Ordered item 1
2. Ordered item 2

Links und Bilder

[Link text](https://example.com)
![Alt text](/path/to/image.png)

GitHub Flavored Markdown

Ardo unterstützt GitHub Flavored Markdown (GFM) direkt.

Tabellen

Aufgabenlisten

• Dokumentation schreiben
• Syntaxhervorhebung ergänzen
• In Produktion veröffentlichen

Automatische Links

URLs werden automatisch zu Links:https://vite.dev

Syntaxhervorhebung

Ferromark hebt Codeblöcke beim Build mit seiner nativen Ferriki-Integration hervor. Standardgrammatiken und Themes werden beim ersten Einsatz heruntergeladen und zwischengespeichert. Beispiele:

interface User {
  id: string
  name: string
  email: string
}

function greetUser(user: User): string {
  return `Hello, ${user.name}!`
}

Zeilen hervorheben

Hebe einzelne Zeilen mit der Syntax {lines} hervor:

function example() {
  const highlighted = true
  const normal = false
  const alsoHighlighted = true
  const highlighted = true
  const notHighlighted = false
}

Zeilennummern

Aktiviere Zeilennummern mit showLineNumbers:

const first = 1
const second = 2
const third = 3

Titel

Ergänze einen Codeblocktitel. Er lässt sich mit hervorgehobenen Zeilen kombinieren:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  api: {
    entryPoints: ["./src/index.ts"],
    tsconfig: "./tsconfig.json",
    title: "API Reference",
  },
})

Prompts

Nutze die Sprache prompt für Text, den Leser in einen Coding-Agenten kopieren. Die Zeilen werden umgebrochen statt horizontal gescrollt. Schreibe jeden Absatz in eine einzelne Quellzeile:

```prompt
Add a Deployment page that explains the GitHub Pages workflow of this repository.
```

Codegruppen

Zeige mehrere Codevarianten in Tabs an:

function greet(name) {
  return `Hello, ${name}!`
}

function greet(name: string): string {
  return `Hello, ${name}!`
}

def greet(name):
    return f"Hello, {name}!"

Callouts

Einfaches Markdown ohne Importe: Ardo erkennt GitHubs Hinweissyntax und ordnet jeden Typ der passenden Komponente zu.

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

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

Das Ergebnis:

Nutze für eigene Titel Komponenten wie <Tip title="Pro Tip">, beschrieben unter Komponenten.

Komponenten

Ardos Komponenten funktionieren in MDX ohne Import: Hinweise, Badges, Karten, Tabs, Akkordeons, Schritte, Codeblöcke und Icons. Komponenten zeigt sie mit MDX und Props in Aktion.

Eigene Komponenten

Importiere React-Komponenten in MDX und nutze sie wie HTML. Lege sie außerhalb von app/routes/ ab, etwa in app/components/: Jede .tsx-Datei im Routenordner wird sonst zur Seite.

import { MyComponent } from "../../components/MyComponent"

# My Page

<MyComponent prop="value" />

Wiederverwendbare Ausschnitte

Ardo nutzt gewöhnliche MDX-Module. Wiederverwendbare Inhalte benötigen daher keine besondere Syntax und kein Plugin. Lege gemeinsame Fragmente in snippets/ ab und importiere sie an den gewünschten Stellen.

Definiere beispielsweise einen gemeinsamen Voraussetzungshinweis in app/snippets/prerequisites.mdx. Innerhalb einer anderen Seite benötigen Ausschnitte kein Frontmatter:

<Tip title="Before you start">
  This guide assumes you have {props.runtime} installed and can run packages with{" "}
  {props.packageManager}.
</Tip>

Importiere ihn anschließend in einer MDX-Seite und rendere ihn innerhalb von ArdoBareContent, damit er keinen eigenen Seitenwrapper mitbringt:

import { ArdoBareContent } from "ardo/ui"
import Prerequisites from "../../snippets/prerequisites.mdx"

# Getting Started

<ArdoBareContent>
  <Prerequisites runtime="Node.js 22.22.0+" packageManager="pnpm" />
</ArdoBareContent>

Ausschnitte können Props über MDX-Ausdrücke empfangen, Ardo-Komponenten kombinieren und neben dem Anwendungscode liegen. Vite behandelt Hot Reload und Importe wie bei anderen Routenabhängigkeiten.

In TSX-Routen

Ein in eine .tsx-Route importiertes .mdx-Modul rendert normalerweise im vollständigen Content-Wrapper mit Artikel, Kopf- und Fußzeile sowie Navigation. Für vollständige Seiten ist das sinnvoll; Ausschnitte sollen meist ohne diese Oberfläche erscheinen. Um MDX in TSX als reinen Inhaltsausschnitt einzubetten, nutze ArdoBareContent:

import { ArdoBareContent } from "ardo/ui"
import MySnippet from "./snippet.mdx"

export default function MyPage() {
  return (
    <ArdoBareContent>
      <MySnippet />
    </ArdoBareContent>
  )
}

So wird MDX kompiliert

Ferromark parst .md und .mdx. MDX ergänzt JavaScript-Ausdrücke, Importe, Exporte und JSX-Komponenten; React kompiliert das generierte JSX über Vite. Metadaten stehen in YAML-Frontmatter.

Ferromark kompiliert jede Route als MDX-Modul nach demselben Vertrag wie @mdx-js/mdx:

• import und export sind JavaScript. TypeScript-Syntax führt dort zu einem Fehler; lagere typisierten Code in ein importiertes .ts-Modul aus.
• Importierte Komponenten werden direkt verwendet. Andere Komponenten kommen zuerst aus Ardos Komponenten, dann aus dem Prop components. Fehlt eine Komponente, nennt die Fehlermeldung ihren Namen.
• export default wird zum Seitenlayout und ersetzt Ardos Inhaltswrapper; statt ArdoDocContent umgibt dein Layout die Seite.
• JSX in JavaScript-Ausdrücken wie {items.map((item) => <Card />)} sieht Ardos Komponenten nicht. Importiere sie dort explizit.
• Reservierte Namen im generierten Code sind _components, _createMdxContent, _missingMdxReference, _provideComponents, MDXLayout, MDXContent, _ArdoPageDataProvider, _ardoFrontmatter, _ardoRoute und _ardoToc. Eigene Deklarationen dieser Namen führen zu einem Compilerfehler.

Frontmatter

Ergänze Metadaten mit YAML-Frontmatter:

---
title: Page Title
description: Page description for SEO
order: 2
---

Alle Optionen stehen in der Frontmatter-Referenz.