Markdown & Komponenten

DocPlatform verwendet CommonMark-konformes Markdown mit YAML-Frontmatter und 7 benutzerdefinierten Komponenten für reichhaltige, interaktive Dokumentation.

Markdown-Grundlagen

DocPlatform unterstützt die vollständige CommonMark-Spezifikation sowie gängige Erweiterungen.

Überschriften

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Überschriften generieren automatisch Anker-IDs für Deep Linking: ## My Section → #my-section.

Textformatierung

**Bold text**
*Italic text*
~~Strikethrough~~
`Inline code`
[Link text](https://example.com)
![Image alt text](./assets/screenshot.png)

Listen

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Another item

- [ ] Task item (unchecked)
- [x] Task item (checked)

Blockzitate

> This is a blockquote.
>
> It can span multiple paragraphs.

Codeblöcke

Umzäunte Codeblöcke mit sprachspezifischem Syntax-Highlighting (über 200 Sprachen via Shiki):

```go
func main() {
    fmt.Println("Hello, DocPlatform!")
}
```

Tabellen

| Feature | Status | Notes |
|---|---|---|
| Editor | Complete | Tiptap-based |
| Search | Complete | Bleve engine |
| Git sync | Complete | Bidirectional |

Tabellen unterstützen links-, zentrierte und rechtsbündige Ausrichtung:

| Left | Center | Right |
|:-----|:------:|------:|
| A    |   B    |     C |

Horizontale Linien

---

Links zwischen Seiten

Verlinken Sie auf andere Seiten in Ihrem Workspace mit relativen Pfaden:

See the [Installation guide](../getting-started/installation.md).
Check the [API reference](../reference/api.md) for endpoint details.

DocPlatform validiert interne Links. Der doctor-Befehl meldet defekte Referenzen.

Frontmatter

Jede Seite beginnt mit einem YAML-Frontmatter-Block, der durch --- begrenzt wird:

---
title: Page Title
description: A brief summary for search results and SEO.
tags: [guide, getting-started]
published: true
access: public
allowed_roles: []
---

Frontmatter-Felder

Benutzerdefinierte Komponenten

DocPlatform enthält 7 integrierte Komponenten, die als reichhaltige, interaktive Elemente sowohl in der Web-Editor-Vorschau als auch in veröffentlichten Dokumenten gerendert werden.

Komponenten verwenden eine Direktiven-Syntax:

:::component-name{attributes}
Content goes here.
:::

Callout

Heben Sie wichtige Informationen mit stilisierten Callout-Boxen hervor.

:::callout{type="info"}
DocPlatform automatically indexes all content for search.
:::

:::callout{type="warning"}
Changing the workspace slug will break existing published URLs.
:::

:::callout{type="danger"}
Running `rebuild` drops the pages table and re-indexes from the filesystem.
This is irreversible.
:::

:::callout{type="tip"}
Press Cmd+K to open search from anywhere in the editor.
:::

:::callout{type="note"}
This feature is available in Community Edition.
:::

Verfügbare Typen: info, warning, danger, tip, note

Codeblock (erweitert)

Standard-umzäunte Codeblöcke werden automatisch erweitert mit:

• Syntax-Highlighting — über 200 Sprachen via Shiki
• Kopier-Button — Ein-Klick-Kopie in die Zwischenablage
• Sprachlabel — wird in der oberen rechten Ecke angezeigt
• Zeilennummern — optional, aktiviert mit showLineNumbers

```typescript {showLineNumbers}
interface Page {
  id: string;
  title: string;
  content: string;
  published: boolean;
}
```

Tabs

Gruppieren Sie verwandte Inhalte in umschaltbare Tab-Panels.

:::tabs
::tab{label="macOS"}
```bash
brew install docplatform

:: ::tab{label=“Linux”}

curl -fsSL https://valoryx.org/install.sh | sh

:: ::tab{label=“Docker”}

docker pull ghcr.io/valoryx-org/docplatform:latest

:: :::

Die Tab-Auswahl bleibt über Seitennavigation hinweg bestehen — wenn ein Benutzer "Docker" auswählt, werden alle Tab-Gruppen auf nachfolgenden Seiten standardmäßig auf "Docker" gesetzt, wenn dieses Label vorhanden ist.

### Accordion

Einklappbare Abschnitte für ergänzende Inhalte.

```markdown
:::accordion{title="What happens during initialization?"}
The `init` command creates a `.docplatform` directory, initializes the SQLite
database, generates an RS256 signing key, and optionally clones a git repository.
:::

:::accordion{title="Can I use an existing database?"}
No. DocPlatform manages its own SQLite database and does not support connecting
to external database servers in Community Edition.
:::

Cards

Raster verlinkter Karten für Navigationsseiten oder Funktionsübersichten.

:::cards
::card{title="Getting Started" link="/getting-started"}
Install and configure DocPlatform in under 10 minutes.
::
::card{title="Git Integration" link="/guides/git-integration"}
Bidirectional sync between the web editor and your git repository.
::
::card{title="Publishing" link="/guides/publishing"}
Publish beautiful documentation sites with dark mode and SEO.
::
::card{title="Search" link="/guides/search"}
Instant full-text search with permission filtering.
::
:::

Steps

Nummerierte Schritt-für-Schritt-Anleitungen mit visuellen Fortschrittsanzeigen.

:::steps
::step{title="Download"}
Get the latest binary from GitHub Releases.
::
::step{title="Initialize"}
Run `docplatform init` to create your workspace.
::
::step{title="Start the server"}
Run `docplatform serve` and open http://localhost:3000.
::
::step{title="Register"}
Create your admin account — the first user becomes Super Admin.
::
:::

API Block

Dokumentieren Sie API-Endpunkte mit Methoden-Badges, Parametern und Antwortbeispielen.

:::api{method="POST" path="/api/v1/auth/login"}
Authenticate a user and receive JWT tokens.

**Request body:**
```json
{
  "email": "[email protected]",
  "password": "your-password"
}

Response: 200 OK

{
  "access_token": "eyJhbG...",
  "refresh_token": "eyJhbG...",
  "expires_in": 900
}

Errors:

• 401 Unauthorized — Invalid credentials
• 429 Too Many Requests — Rate limit exceeded :::

## Komponentenverwendung im Editor

### Rich-Text-Modus

Im Rich-Editor werden Komponenten als interaktive Blöcke gerendert. Fügen Sie sie ein mit:

- **Symbolleiste** — fügen Sie Komponenten über die Editor-Symbolleiste ein
- **Symbolleiste** — klicken Sie auf den **+** Button → wählen Sie eine Komponente
- **Raw-Markdown-Modus** — schreiben Sie die Direktiven-Syntax direkt

### Raw-Markdown-Modus

Im Raw-Modus schreiben Sie die Direktiven-Syntax direkt. Der Editor bietet Syntax-Highlighting für Komponentenblöcke.

## Markdown-Erweiterungen

Über CommonMark hinaus unterstützt DocPlatform:

| Erweiterung | Syntax | Beschreibung |
|---|---|---|
| **Aufgabenlisten** | `- [ ] item` | Interaktive Checkboxen |
| **Durchgestrichen** | `~~text~~` | Durchgestrichener Text |
| **Tabellen** | GFM-Tabellen | Mit Ausrichtungsunterstützung |
| **Autolinks** | `https://...` | URLs werden automatisch verlinkt |
| **Fußnoten** | `[^1]` | Referenzstil-Fußnoten |
| **Überschriftenanker** | Automatisch generiert | Deep Linking zu Abschnitten |