Markdown & Components

DocPlatform uses CommonMark-compliant Markdown with YAML frontmatter, wikilinks, and 15 custom components for rich, interactive documentation.

Markdown basics

DocPlatform supports the full CommonMark specification plus common extensions.

Headings

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

Headings automatically generate anchor IDs for deep linking: ## My Section → #my-section.

Text formatting

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

Lists

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Another item

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

Blockquotes

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

Code blocks

Fenced code blocks with language-specific syntax highlighting (200+ languages via Chroma):

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

Tables

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

Tables support left, center, and right alignment:

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

Horizontal rules

---

Links between pages

Link to other pages using standard Markdown relative paths:

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

DocPlatform validates internal links. The doctor command reports any broken references.

Wikilinks

DocPlatform supports wikilinks for linking between pages without specifying full paths. Wikilinks use double-bracket syntax:

See [[Getting Started]] for setup instructions.
Check [[API Authentication|the auth guide]] for token details.
Link by page ID for rename-proof references: [[01HJK...]]

Wikilink features:

• Hover preview — hovering a wikilink shows a preview popup with the target page’s title and description
• Auto-repair on rename — when a page is renamed or moved, all wikilinks pointing to it are automatically updated across the workspace
• Broken link detection — docplatform doctor reports wikilinks that point to nonexistent pages

Frontmatter

Every page starts with a YAML frontmatter block delimited by ---:

---
title: Page Title
description: A brief summary for search results and SEO.
tags: [guide, getting-started]
published: true
access:
  read: ["engineering", "product"]
  write: ["engineering"]
---

Frontmatter fields

The id field is auto-generated as a ULID when a page is created. On git import, if the id is missing, DocPlatform generates one and writes it back on the next sync. This ID enables rename-proof wikilinks and survives database rebuilds.

Custom components

DocPlatform includes 15 built-in components that render as rich, interactive elements in both the web editor preview and published docs.

Components use a directive syntax:

:::component-name[attributes]
Content goes here.
:::

Callout

Highlight important information with styled callout boxes.

:::callout[info]
DocPlatform automatically indexes all content for search.
:::

:::callout[warning]
Changing the workspace slug will break existing published URLs.
:::

:::callout[danger]
Running `rebuild` drops the pages table and re-indexes from the filesystem.
This is irreversible.
:::

:::callout[tip]
Press Cmd+K to open search from anywhere in the editor.
:::

:::callout[note]
This feature is available in Community Edition.
:::

Available types: info, warning, danger, tip, note

Code block (enhanced)

Standard fenced code blocks are automatically enhanced with:

• Syntax highlighting — 200+ languages via Chroma
• Copy button — one-click copy to clipboard
• Language label — displayed in the top-right corner
• Line numbers — optional, enabled with showLineNumbers

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

Tabs

Group related content into switchable tab panels.

:::tabs
::tab[macOS]
```bash
brew install docplatform

:: ::tab[Linux]

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

:: ::tab[Docker]

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

:: :::

Tab selection persists across page navigation — if a user selects "Docker", all tab groups on subsequent pages default to "Docker" when that label exists.

### Accordion

Collapsible sections for supplementary content.

```markdown
:::accordion[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[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

Grid of linked cards for navigation pages or feature overviews.

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

Steps

Numbered step-by-step instructions with visual progress indicators.

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

API Block

Document API endpoints with method badges, parameters, and response examples.

:::api[POST /api/auth/login]
Authenticate a user and receive JWT tokens.

**Request body:**
```json
{
  "email": "user@example.com",
  "password": "your-password"
}

Response: 200 OK

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

Errors:

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

The API Block renders with Scalar-powered method badges and expandable parameter/response sections.

### File tree

Display directory structures with syntax highlighting.

```markdown
:::filetree
- .docplatform/
  - data.db
  - jwt-key.pem
  - backups/
  - search-index/
  - workspaces/
    - {workspace-id}/
      - docs/
      - assets/
      - .git/
:::

Mermaid diagrams

Render diagrams from text using Mermaid syntax.

```mermaid
graph TD
    A[Web Editor] --> B[Content Ledger]
    C[Git Push] --> B
    B --> D[Filesystem]
    B --> E[Database]
    B --> F[Search Index]
```

Supports flowcharts, sequence diagrams, class diagrams, state diagrams, and more.

KaTeX math

Render mathematical notation using LaTeX syntax.

Inline math: $E = mc^2$

Block math:
$$
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Component usage in the editor

Rich text mode

In the rich editor, components render as interactive blocks. Insert them using:

• Slash commands — type / then the component name (e.g., /callout, /tabs)
• Toolbar — click the + button → select a component
• Keyboard — no dedicated shortcuts (use slash commands)

Raw Markdown mode

In raw mode, write the directive syntax directly. The editor provides syntax highlighting for component blocks.

Markdown extensions

Beyond CommonMark, DocPlatform supports: