Layout und Navigation

Build-Optionen stehen in ardo.config.ts. Alles um den Inhalt herum ist React in app/root.tsx. Meist reichen einige der folgenden Aufgaben; danach folgt die Referenz.

Häufige Aufgaben

Seite hinzufügen

Erstelle Markdown oder MDX unter app/routes/. Der Pfad bestimmt die URL: app/routes/guide/install.mdx wird unter /guide/install/ ausgeliefert. Der Entwicklungsserver erkennt die Datei sofort; sie erscheint in Seitenleiste und Suche.

---
title: Install
description: Add the package to your project.
---

# Install

Run the installer for your package manager.

title setzt Seitenleisten- und Browsertitel. Auch TSX-Dateien in app/routes/ werden zu Seiten. Die generierte Seitenleiste listet aber nur Markdown und MDX; verlinke TSX-Seiten daher in der Kopfzeile oder auf anderen Seiten.

Seiten sortieren

Seiten mit order stehen zuerst, aufsteigend nach Zahl. Die übrigen folgen alphabetisch nach Titel.

---
title: Install
order: 2
---

Seiten gruppieren

Lege verwandte Seiten in einen Ordner. Dessen index.mdx bestimmt Beschriftung, Reihenfolge und anfänglichen Klappzustand der Gruppe. Die Indexseite ist zugleich die Gruppenseite.

---
title: Releases
order: 20
collapsed: true
---

# Releases

Ohne Indexseite gilt der Ordnername als Beschriftung. Optionen unter Frontmatter.

Seite in der Seitenleiste ausblenden

Setze sidebar: false im Frontmatter. Die Seite wird weiterhin gebaut und bleibt per Link erreichbar.

Abschnitt hinzufügen

Jeder oberste Ordner unter app/routes/ wird ein Abschnitt mit eigenem Tab, etwa guide/ und api-reference/. Bekannte Namen wie guide, reference, api, examples und adr erhalten passende Texte und Icons. Andere nutzen den Ordnernamen. Der Tab öffnet Index oder erste Seite.

Sortiere Tabs in ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Docs",
  sidebar: { sectionOrder: ["guide", "reference", "api"] },
})

Manuelle Abschnitte beschreibt Abschnitte der Seitenleiste.

Links in der Kopfzeile

Übergib ArdoHeader mit Navigationslinks. ArdoNavLink ergänzt to um den Basispfad; href akzeptiert beliebige URLs. Social-Links gehören in ArdoHeaderActions:

import {
  ArdoHeader,
  ArdoHeaderActions,
  ArdoNav,
  ArdoNavLink,
  ArdoRoot,
  ArdoSocialLink,
} from "ardo/ui"

export default function Root() {
  return (
    <ArdoRoot>
      <ArdoHeader>
        <ArdoNav>
          <ArdoNavLink to="/guide/getting-started">Guide</ArdoNavLink>
          <ArdoNavLink href="https://github.com/example/project/releases">Releases</ArdoNavLink>
        </ArdoNav>
        <ArdoHeaderActions>
          <ArdoSocialLink href="https://github.com/example/project" icon="github" />
        </ArdoHeaderActions>
      </ArdoHeader>
    </ArdoRoot>
  )
}

ArdoSocialLink kennt Icons für github, discord, linkedin, npm, twitter und youtube.

Logo und Favicon ändern

Importiere Dateien und übergib sie an ArdoRoot. Vites Fingerprints bringen neue Logos beim nächsten Deployment zu den Lesern:

import { ArdoRoot } from "ardo/ui"

import icon from "./assets/icon.svg"
import logo from "./assets/logo.svg"

export default function Root() {
  return <ArdoRoot logo={logo} icon={icon} />
}

logo akzeptiert { light, dark }, appleTouchIcon ein 180×180-PNG für iOS. Ohne icon verlinkt Ardo seine Eulenicons. Details unter Theming.

Fußzeile ändern

Übergib ArdoFooter mit eigenem Text:

import { ArdoFooter, ArdoRoot } from "ardo/ui"

export default function Root() {
  return (
    <ArdoRoot>
      <ArdoFooter message="Released under the MIT License." copyright="© 2026 Example Co" />
    </ArdoRoot>
  )
}

Ohne ArdoFooter erscheint die Standardfußzeile; footer={false} auf ArdoRoot blendet sie aus. Props unter Fußzeile.

Minimale Root-Komponente

<ArdoRoot /> liefert Kopfzeile mit Suche und Themewechsel, Seitenleiste mit Abschnitt pro oberstem Routenordner und Fußzeile. Konfiguration und Stylesheet kommen aus Ardos Einstiegspunkten. root.tsx braucht nur verwendete Komponenten zu importieren.

import { ArdoRoot } from "ardo/ui"

export default function Root() {
  return <ArdoRoot />
}

Komponiere Navigation mit React. Übergib ArdoHeader, ArdoSidebar und ArdoFooter als Kinder oder setze header, sidebar beziehungsweise footer zum Ausblenden auf false:

import {
  ArdoGeneratedSidebar,
  ArdoHeader,
  ArdoNav,
  ArdoNavLink,
  ArdoRoot,
  ArdoSidebar,
  ArdoSidebarSection,
} from "ardo/ui"

export default function Root() {
  return (
    <ArdoRoot>
      <ArdoHeader>
        <ArdoNav>
          <ArdoNavLink to="/guide/getting-started">Guide</ArdoNavLink>
        </ArdoNav>
      </ArdoHeader>

      <ArdoSidebar>
        <ArdoSidebarSection id="guide" label="Guide" to="/guide/getting-started">
          <ArdoGeneratedSidebar section="guide" />
        </ArdoSidebarSection>
      </ArdoSidebar>
    </ArdoRoot>
  )
}

ArdoRoot verwaltet Provider, Seiteninhalt und JSX-Layoutbereiche. Dieser Teil hydriert im Browser.

ArdoRoot

ArdoRoot erhält Website-Einstellungen als Props und Layoutelemente als Kinder.

Kopfzeile

ArdoHeader liefert die responsive Kopfzeile. Platziere ArdoNav direkt darin und rechte Aktionen in ArdoHeaderActions.

import { ArdoHeader, ArdoHeaderActions, ArdoNav, ArdoNavLink, ArdoSocialLink } from "ardo/ui"
import logo from "./assets/logo.svg"
;<ArdoHeader logo={logo} title="My Docs" searchPlaceholder="Search documentation...">
  <ArdoNav>
    <ArdoNavLink to="/guide/getting-started">Guide</ArdoNavLink>
    <ArdoNavLink to="/api-reference">API</ArdoNavLink>
  </ArdoNav>
  <ArdoHeaderActions>
    <ArdoSocialLink href="https://github.com/example/project" icon="github" />
  </ArdoHeaderActions>
</ArdoHeader>

Das an ArdoRoot übergebene logo gilt für Kopfzeile und mobiles Menü, sofern die Kopfzeile kein eigenes logo setzt.

Suche in der Kopfzeile

Mit search="auto" entscheidet das Layout:

• Dokumentseiten zeigen ein Suchfeld in der Mitte.
• Freie Seiten (handle = { layout: "bare" }, etwa die Startseite) zeigen ein Suchicon, damit der Hero im Mittelpunkt steht.

search="field" oder search="icon" wählt eine Darstellung für alle Seiten. Unter 1024 px wird das Feld zum Icon. ⌘K beziehungsweise Ctrl+K öffnet die Suche in jedem Modus.

Schmale Bildschirme

Unter 1024 px bleiben Menütaste, Logo und Suche. Das Menü endet mit Versions- und Sprachwahl, Themewechsel und den ArdoHeaderActions, etwa Social-Links.

Versionsauswahl

Mit versioning steht der Umschalter unten in der Seitenleiste, auf freien Seiten in der Fußzeile. Ältere Versionen zeigen einen Banner zur gleichen Seite der neuesten Version.

Eigene Layouts können ArdoVersionSwitcher als Select, ArdoVersionControl mit Beschriftung und ArdoVersionBanner als Hinweis einsetzen. Unter zwei Versionen zeigen sie nichts.

Auf freien Seiten teilen sich Kopfzeile, ArdoHero, ArdoFeatures und ArdoFooter dieselbe Breite. Dokumentseiten behalten eine volle Kopfzeile. Ändere --ardo-layout-pageMaxWidth und nutze vars.layout.pageMaxWidth für eigene Abschnitte.

Abschnitte der Seitenleiste

Die linke Navigation besteht aus Abschnittsleiste und Panel. ArdoSidebarSection definiert mit Props den Abschnitt und mit Kindern das Panel.

import { ArdoGeneratedSidebar, ArdoSidebar, ArdoSidebarSection } from "ardo/ui"
import { BookOpen, Code } from "ardo/icons"
;<ArdoSidebar>
  <ArdoSidebarSection
    id="guide"
    label="Guide"
    to="/guide/getting-started"
    icon={<BookOpen size={18} />}
  >
    <ArdoGeneratedSidebar section="guide" />
  </ArdoSidebarSection>

  <ArdoSidebarSection id="api-reference" label="API" to="/api-reference" icon={<Code size={18} />}>
    <ArdoGeneratedSidebar section="api-reference" />
  </ArdoSidebarSection>
</ArdoSidebar>

ArdoGeneratedSidebar rendert generierte Markdown- und API-Navigation für den obersten Abschnitt. Für manuelle Navigation kombinierst du Links und Gruppen:

<ArdoSidebarSection id="guide" label="Guide" to="/guide/getting-started">
  <ArdoSidebarGroup title="Guide">
    <ArdoSidebarLink to="/guide/getting-started">Getting Started</ArdoSidebarLink>
    <ArdoSidebarLink to="/guide/configuration">Configuration</ArdoSidebarLink>
  </ArdoSidebarGroup>
</ArdoSidebarSection>

Fußzeile

Übergib ArdoFooter als Kind von ArdoRoot.

<ArdoFooter
  sponsor={{ text: "Example Co", link: "https://example.com" }}
  message="Released under the MIT License."
  copyright="Copyright 2026 Example Co"
/>

Bearbeitungslinks und Änderungsdatum

editLink und lastUpdated gelten für alle Markdown- und MDX-Dokumentseiten. Frontmatter kann sie mit editLink: false oder lastUpdated: false abschalten.

<ArdoRoot
  editLink={{
    pattern: "https://github.com/example/project/edit/main/docs/app/routes/:path",
    text: "Edit this page on GitHub",
  }}
  lastUpdated={{
    enabled: true,
    text: "Last updated",
    formatOptions: { dateStyle: "medium" },
  }}
  tocLabel="On this page"
>
  {/* Header, sidebar, and footer here */}
</ArdoRoot>

:path ist der Quelldateipfad relativ zu app/routes oder routesDir, einschließlich Dateiendung. Repository- und Quellordnerpräfix bleiben im Muster. Bearbeitungslinks sind optional.

Änderungsdaten stammen aus dem letzten Git-Commit. Lade in CI die ganze Historie (fetch-depth: 0 bei actions/checkout). Ohne Historie gilt die Dateizeit. Daten nutzen aktive Sprache und UTC, sofern formatOptions keine andere Zeitzone setzt. Generierte APIs deaktivieren Links und Dateidaten; materialisierte Inhalte ebenfalls, außer eine Frontmatter-Abbildung aktiviert sie mit passendem Quellmuster.

Bis 1280 px erscheint das Inhaltsverzeichnis ausklappbar unter dem Titel, die Seitenaktionen am Artikelende. Breitere Bildschirme nutzen die rechte Spalte.

Layout je Route

Exportiere handle, um Layoutteile pro Route auszublenden:

export const handle = { layout: "bare", chrome: false }

chrome: false entfernt Kopf- und Fußzeile. layout: "bare" entfernt Seitenleiste und rechte Spalte.

Freie Routen mit eigenem Layout

export const handle = { layout: "bare", chrome: false } eignet sich für eigene Kopf- und Fußzeilen. Ardo reserviert keinen Kopfzeilenplatz und keinen zusätzlichen Sprunglink; Innenabstand, Hintergrund und Überlauf des Hauptbereichs gehören dir. Stelle einen eigenen Tastatur-Sprunglink bereit.

Freie Routen mit Ardo-Kopfzeile behalten Versatz und Sprunglink. Dokumentrouten behalten das innere Scroll-Layout.

Layoutteile ersetzen

Reicht CSS nicht aus, ersetze Layoutteile durch eigene React-Komponenten:

import { useArdoConfig } from "ardo/runtime"

export function MyHeader() {
  const config = useArdoConfig()

  return (
    <header className="my-custom-header">
      <h1>{config.title}</h1>
      {/* Your custom header content */}
    </header>
  )
}

Übergib ihn an ArdoRoot und behalte für andere Teile die Standards:

import { ArdoRoot } from "ardo/ui"

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

export default function Root() {
  return <ArdoRoot header={<MyHeader />} />
}

header, sidebar und footer akzeptieren React-Elemente oder false, um den Teil auszublenden. Als Kinder erkennt ArdoRoot nur Ardos ArdoHeader, ArdoSidebar und ArdoFooter; andere Kinder ersetzen den Seiteninhalt. Behalte ArdoRoot als Hülle: Sie liefert den Kontext für die folgenden Runtime-Hooks.

message und copyright rendern React-Inhalt; Strings werden maskiert. Für vertrauenswürdiges HTML gibt es trustedMessageHtml und trustedCopyrightHtml. Übergib dort keine Benutzer- oder CMS-Inhalte.

Suche und mobile Navigation wiederverwenden

ArdoHeaderSearch und ArdoMobileNavigation aus ardo/ui verwenden dieselben Dialoge, Kürzel und Fokusregeln wie die Standardkopfzeile. Rendere sie im header-Slot von ArdoRoot für gemeinsame Provider.

import { useState } from "ardo/react"
import {
  ArdoGeneratedSidebar,
  ArdoHeaderSearch,
  ArdoMobileNavigation,
  ArdoRoot,
  ArdoSidebar,
  ArdoSidebarSection,
} from "ardo/ui"

function SiteHeader() {
  const [menuOpen, setMenuOpen] = useState(false)
  return (
    <header className="site-header">
      <a href="/">My project</a>
      <ArdoMobileNavigation open={menuOpen} onOpenChange={setMenuOpen}>
        <ArdoSidebar>
          <ArdoSidebarSection id="guide" label="Guide" to="/guide/install/">
            <ArdoGeneratedSidebar section="guide" />
          </ArdoSidebarSection>
        </ArdoSidebar>
      </ArdoMobileNavigation>
      <ArdoHeaderSearch variant="icon" onActivate={() => setMenuOpen(false)} />
    </header>
  )
}

export default function Root() {
  return <ArdoRoot header={<SiteHeader />} scrollMode="document" />
}

Ohne open verwaltet ArdoMobileNavigation seinen Zustand selbst. nav, actions, logo, title und themeToggle gestalten das Panel; label, trigger und className die Taste. Sie folgt dem 1024-px-Breakpoint. Gesteuerter Zustand kann die Navigation vor der Suche schließen. Escape schließt beide Dialoge und stellt den Fokus wieder her. ArdoHeaderSearch akzeptiert variant="field" oder variant="icon".

Markdown-Komponenten anpassen

Übergib components an ArdoRoot, um Standardkomponenten zu ergänzen oder einzelne zu ersetzen. Die Standards bleiben verfügbar; die explizite MDX-Prop components einer Seite hat Vorrang, und ein eigenes MDX-Standardlayout behält den Wrapper. Definiere Map und React-Komponenten außerhalb der Root-Funktion für stabile Identitäten.

import type { ReactNode } from "ardo/react"
import { useArdoPageData } from "ardo/runtime"
import { ArdoDocContent, ArdoRoot } from "ardo/ui"

function Article({ children }: { children: ReactNode }) {
  const page = useArdoPageData()
  return (
    <ArdoDocContent
      header={
        <header className="article-hero">
          <h1>{page?.title}</h1>
        </header>
      }
      tocSource="dom"
    >
      {children}
    </ArdoDocContent>
  )
}

const components = { wrapper: Article }

export default function Root() {
  return <ArdoRoot components={components} />
}

Ersetze etwa table, a und CodeBlock oder registriere eigene MDX-Namen. Ein eigenes a sollte interne Basispfade erhalten. Ein eigenes CodeBlock ersetzt auch Kopiertasten und Syntaxdarstellung.

Artikelbereiche

ArdoDocContent und ArdoDocPage akzeptieren folgende React-Slots. Ohne Angabe bleibt der Standard; false oder null blendet aus.

ArdoContent bietet dieselben header-, outline- und footer-Slots. Ein eigenes outline hat Vorrang vor Frontmatter outline: false.

Überschriften aus Komponenten erkennen

Standardmäßig stammt das Inhaltsverzeichnis aus Markdown-Metadaten. tocSource="dom" auf ArdoDocContent oder ArdoDocPage erkennt nach Hydrierung echte Komponentenüberschriften. Server-HTML und erster Clientrender bleiben statisch; danach werden Ergänzungen, Löschungen und Titeländerungen verfolgt.

Für ein eigenständiges Inhaltsverzeichnis verwendest du <ArdoTOC source="dom" scope="#article-body" />. Das optionale scope ist ein CSS-Selektor für den Inhaltscontainer. Ohne Selektor liest Ardo .ardo-content-body in #main-content oder bei einer eigenen Seite #main-content selbst. Beide Modi nutzen markdown.toc.level für die Überschriftenebenen. Navigation, Inhaltsverzeichnis, versteckte Überschriften und mit data-ardo-toc="exclude" markierte Teilbäume bleiben außen vor. Markiere damit Beispiele, deren Überschriften keine Artikelabschnitte bilden sollen.

Vergib eindeutige feste Überschriften-IDs für dauerhafte Links. DOM-Modus ergänzt fehlende IDs mit kollisionsfreien ardo-heading-N, abhängig von der Reihenfolge. Er erweitert weder Build-Suche noch Sitemap oder LLM-Export. Schreibe benötigte indexierbare Inhalte in Markdown.

Runtime-Hooks

Komponenten lesen Ardos Zustand über Hooks aus ardo/runtime:

Bearbeitungslink aus Website-Einstellungen und aktueller Seite:

import { useArdoPageData, useArdoSiteConfig } from "ardo/runtime"

function MyEditLink() {
  const { editLink } = useArdoSiteConfig()
  const page = useArdoPageData()
  if (!editLink?.pattern || !page?.relativePath || page.frontmatter.editLink === false) {
    return null
  }
  const sourcePath = page.relativePath.split("/").map(encodeURIComponent).join("/")
  const href = editLink.pattern.replace(":path", sourcePath)
  return <a href={href}>{editLink.text ?? "Edit this page"}</a>
}

findCurrentSidebarItem und getPrevNextLinks helfen beim Ersetzen der Vor-/Zurück-Navigation:

import {
  ArdoLink,
  findCurrentSidebarItem,
  getPrevNextLinks,
  useArdoPageData,
  useArdoPath,
  useArdoSidebar,
} from "ardo/runtime"

function MyPrevNext() {
  const pathname = useArdoPath()
  const page = useArdoPageData()
  const sidebar = useArdoSidebar()
  if (!page) return null

  const current = findCurrentSidebarItem(sidebar, pathname)
  const { prev, next } = getPrevNextLinks(sidebar, pathname)

  return (
    <nav>
      <span>{current?.text}</span>
      {prev?.link && <ArdoLink to={prev.link}>{prev.text}</ArdoLink>}
      {next?.link && <ArdoLink to={next.link}>{next.text}</ArdoLink>}
    </nav>
  )
}

ArdoLink ergänzt den Basispfad und rendert <a>; jeder Klick lädt das vorgerenderte Ziel. ArdoProvider und ArdoSiteConfigProvider liefern denselben Kontext in Tests und isolierten Vorschauen.

Layout: Die HTML-Hülle

Ardo rendert jede Seite in einer HTML-Hülle aus <html>, <head> und <body>. Sie wird nur auf dem Server bei ardo dev und ardo build gerendert; die Root-Komponente darin hydriert. Standardmäßig liefert ArdoRootLayout aus ardo/ui Zeichensatz, Viewport, Theme-Skript, Favicons, Seitentitel, Metadaten, Stylesheets und Clientskript. Meist brauchst du keinen Layout-Export.

Exportiere Layout aus root.tsx, um ArdoRootLayout Optionen zu übergeben:

import type { ReactNode } from "ardo/react"
import { ArdoRootLayout } from "ardo/ui"

export function Layout({ children }: { children: ReactNode }) {
  return <ArdoRootLayout colorScheme="light">{children}</ArdoRootLayout>
}

Eine vollständig eigene Hülle rendert ArdoHead in <head> und ArdoScripts am Ende von <body>. Beide stammen aus ardo/runtime. ArdoHead rendert die meta-Deskriptoren, Stylesheets und Modul-Preloads; ArdoScripts lädt den Client-Einstieg zur Hydration. Die Hülle muss children rendern:

import type { ReactNode } from "ardo/react"
import { ArdoHead, ArdoScripts } from "ardo/runtime"

export function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <ArdoHead />
      </head>
      <body>
        {children}
        <ArdoScripts />
      </body>
    </html>
  )
}

Eine eigene Hülle enthält weder Theme-Bootstrap noch Favicons von ArdoRootLayout. Bevorzuge einen Wrapper um ArdoRootLayout, solange die Website keine vollständige Dokumentkontrolle benötigt.

Fehlerseiten

root.tsx kann ErrorBoundary exportieren. Fehlende Seiten erscheinen damit innerhalb der Root samt Navigation. Renderfehler ersetzen die Root, damit defektes Layout den Fehler nicht versteckt. Ohne Export gilt ArdoErrorBoundary aus ardo/ui.

import { ArdoErrorBoundary } from "ardo/ui"

export const ErrorBoundary = ArdoErrorBoundary

Farbschema von RootLayout

ArdoRootLayout nutzt mit colorScheme="auto" zuerst gespeichertes ardo-theme, danach prefers-color-scheme. Setze ein festes Farbschema, wenn Benutzer nicht wählen sollen:

export function Layout({ children }: { children: ReactNode }) {
  return <ArdoRootLayout colorScheme="light">{children}</ArdoRootLayout>
}

Dokument-Scrollen mit eigenem Layout

scrollMode="document" eignet sich für externe Kopf- oder Fußzeilen und normales Dokument-Scrollen. Standard bleibt die Viewport-Hülle. Im Dokumentmodus haften Seitenleiste und rechte Spalte unter der eingestellten Kopfzeilenhöhe; eine externe Fußzeile bleibt erreichbar. Auch mit eigener className gilt der Modus, aber du musst benötigte Display- und Breitenregeln selbst liefern.

Platziere eigene haftende Kopf- und Fußzeile neben ArdoRoot. Deaktiviere Ardos Varianten, wenn beide extern sind:

export default function Root() {
  return (
    <>
      <SiteHeader />
      <ArdoRoot scrollMode="document" header={false} footer={false} />
      <SiteFooter />
    </>
  )
}

--ardo-layout-headerHeight bestimmt Haftpositionen und Ankerabstände. Setze die Variable über Layout auf ArdoRootLayout, damit beide Layouts sie teilen. Passe sie am Breakpoint einer höheren mobilen Kopfzeile an:

export function Layout({ children }: { children: ReactNode }) {
  return <ArdoRootLayout className="docs-site">{children}</ArdoRootLayout>
}

.docs-site {
  --ardo-layout-headerHeight: 4rem;
}

@media (max-width: 640px) {
  .docs-site {
    --ardo-layout-headerHeight: 6rem;
  }
}

.site-header {
  position: sticky;
  top: 0;
  height: var(--ardo-layout-headerHeight);
}

Eine haftende Kopfzeile bleibt im Dokumentfluss und braucht keinen zusätzlichen oberen Abstand. Eine fixierte Kopfzeile liegt außerhalb des Flusses; reserviere ihre Höhe einmal mit padding-top: var(--ardo-layout-headerHeight) in der Website-Hülle. Für eine MDX-Route mit eigenem Layout exportierst du:

export const handle = { chrome: false }

Externe Kopf- und Fußzeilen folgen derselben Regel; Ardo behält Seitenleiste und rechte Spalte. Routen ohne Ardo-Layout benötigen einen eigenen Sprunglink.