Aller au contenu principal

Markdown syntax

Docsio supports standard markdown plus a few extras. If you've used Mintlify or GitBook, this will look familiar.

Headings

# H1 (only one per page — used for the page title)
## H2
### H3
#### H4

H1 is set by your frontmatter title. Don't add a second H1 in the body.

Paragraphs and emphasis

This is a paragraph. **Bold**, *italic*, ~~strikethrough~~, `inline code`.

This is the second paragraph.
[External link](https://example.com)
[Internal page](/getting-started/quickstart)
[Anchor on same page](#headings)

Internal links use the slug, not the file path. Docsio fixes broken internal links automatically when you rename a page.

Lists

- Bullet
- Another bullet
  - Nested

1. First
2. Second
3. Third

Code blocks

Triple-backtick fenced blocks with language hints for syntax highlighting:

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

Supported languages: any common one (typescript, javascript, python, rust, go, ruby, bash, json, yaml, html, css, markdown, sql, etc.). Docsio uses Prism under the hood, full language list in the build output.

For a copy button, no extra syntax — every code block has one automatically.

Tables

| Feature | Free | Pro |
|---|---|---|
| Custom domains | ✓ | ✓ |
| Search bar | — | ✓ |
| Doc versioning | — | ✓ |

Renders to:

FeatureFreePro
Custom domains✓✓
Search bar—✓
Doc versioning—✓

Admonitions

Five types: note, tip, info, warning, danger.

:::tip
Use admonitions sparingly — they catch the eye, but lose impact if every paragraph has one.
:::

Renders as a colored callout box. Tip and info use your brand color; warning is amber; danger is red.

Images

![Alt text](/img/screenshot.png)

For control over size or alignment, use HTML:

<img src="/img/screenshot.png" alt="..." width="600" />

See Images and media.

Embeds

Most embeddable URLs (YouTube, Loom, Vimeo, Twitter) work via plain link:

[Watch the demo](https://youtu.be/dQw4w9WgXcQ)

For inline iframes, use HTML directly.

Frontmatter

Every page starts with YAML frontmatter:

---
title: My page title
sidebar_position: 2
description: "What this page is about (used for meta description and previews)."
slug: /custom-url           # optional
sidebar_custom_props:
  icon: rocket              # Phosphor icon shown in the sidebar
---

→ Frontmatter reference

MDX components

Pages can be .mdx instead of .md to use built-in components:

import {Card, CardGrid} from '@site/src/components/Card';

<CardGrid cols={2}>
  <Card title="Quickstart" href="/docs/getting-started/quickstart" icon={<i className="ph ph-rocket" />}>
    Get up and running in five minutes.
  </Card>
</CardGrid>

→ Components reference

Things that don't work

  • HTML <script> tags (security)
  • Custom React components (you can't write your own — built-in only)
  • Inline styles via style="..." (use Custom CSS via classNames instead)

Tips

  • Use sentence case for headings. "Get started" reads better than "Get Started".
  • Keep paragraphs short. 2-4 sentences max. Docs aren't blog posts.
  • Code blocks have language hints. Always specify (e.g. bash, typescript) — you'll get syntax highlighting and the AI agent uses the hint when reading.
  • Lead each page with one sentence describing what it covers. That sentence often becomes the meta description automatically.