# Writing pages

Pages in EvoHub Docs are written in Markdown, with a small set of components for callouts, tabs, steps and the like. This page lists everything the renderer understands, how to reuse text with snippets, and how to add images and files. The same syntax works in the console editor and in files synced from GitHub.

## The editor

Open a page from the site's navigation tree. The editor has the Markdown on one side and a live preview on the other. The toolbar adds formatting, an **Insert** menu for every component below, an upload button, and the **Markdown cheat sheet** (with a second tab, **Writing in Git**, for files in a repository).

Raw HTML is never rendered. Use the components below instead.

The page title is shown above the page, so do not repeat it as a `# Heading` in the body. Start sections at `##`.

## Basic Markdown

| Element | Markdown |
| --- | --- |
| Headings | `## Install` and `### On macOS` |
| Bold, italic, strikethrough | `**bold**`, `_italic_`, `~~struck~~` |
| Link to a page | `[Quickstart](/quickstart)` |
| Link to a section | `[Install the CLI](/quickstart#install-the-cli)` |
| Lists | `- Item` and `1. First` |
| Task list | `- [x] Done` and `- [ ] To do` |
| Table | Columns separated by `\|`, with a `---` row under the header |
| Footnote | `Billed hourly.[^1]` and, anywhere below, `[^1]: Rounded up.` |

Every heading gets an anchor: lowercase, words joined by hyphens. Code blocks are highlighted by language and get a **Copy** button.

## Callouts

A blockquote whose first line is a marker becomes a callout. Text after the marker is its title.

```markdown
> [!NOTE]
> Changes take a minute to show up.

> [!TIP] Faster builds
> Turn on caching in the settings.

> [!WARNING]
> Rotating the key signs everyone out.
```

The five kinds are `[!NOTE]`, `[!TIP]`, `[!INFO]`, `[!WARNING]` and `[!DANGER]`. GitHub's `[!IMPORTANT]` reads as info and `[!CAUTION]` as danger.

## Tabs

```markdown
:::tabs
::tab{title="npm"}
npm install acme
::tab{title="pnpm"}
pnpm add acme
:::
```

## Code group

Code blocks in tabs that share one **Copy** button. The label in brackets after the language names the tab.

````markdown
:::code-group
```bash [npm]
npm install acme
```
```bash [pnpm]
pnpm add acme
```
:::
````

## Steps

Numbered steps; every `###` heading inside starts one.

```markdown
:::steps
### Install the CLI
Run the installer.
### Sign in
Use your account.
:::
```

## Cards

A grid of cards, one to four columns. A card with `href` is a link; `icon` takes an icon name such as `rocket`, `book`, `code`, `settings`, `key`, `shield` or `zap`.

```markdown
:::cards{cols=2}
::card{title="Quickstart" icon="rocket" href="/quickstart"}
Up and running in five minutes.
::card{title="API" icon="code" href="/api"}
Every endpoint, with examples.
:::
```

## Accordion

A section that folds away. Add `open` to show it unfolded.

```markdown
:::details{title="How is usage billed?"}
By the hour.
:::
```

## Columns

```markdown
:::columns{cols=2}
::col
Left column.
::col
Right column.
:::
```

## Badge

A small inline label. Colours: `gray`, `blue`, `green`, `yellow`, `red`, `purple` and `accent`.

```markdown
Webhooks :badge[New]{color=blue}
```

## Video embed

YouTube, Vimeo and Loom videos are embedded. Any other address shows as a link.

```markdown
::embed{url="https://www.youtube.com/watch?v=VIDEO_ID" title="Product tour"}
```

## Diagrams and math

Mermaid diagrams are drawn from a `mermaid` code block:

````markdown
```mermaid
flowchart LR
  A[Alert] --> B[On-call] --> C[Resolved]
```
````

Math uses KaTeX syntax: `$\pi r^2$` inside a sentence (no space after the opening `$` or before the closing one), or a block between `$$` lines.

## Snippets

A snippet is a piece of Markdown — a support notice, a version table — written once and included in any page. Change the snippet and every page that uses it changes.

:::steps
### Create the snippet
Open **Snippets** in the site's menu, name it (lowercase letters, digits and single hyphens, for example `support-contact`), and write its Markdown.

### Publish it
**Save draft**, then **Publish**. Like pages, snippets have a draft and a live copy, and readers see the live copy.

### Include it
Put `{{snippet:support-contact}}` on a line of its own in any page. The Insert menu lists your snippets.
:::

Snippets are not expanded inside code, and a snippet cannot include another snippet. An unknown name is shown as written. Unpublishing a snippet makes pages show the reference as plain text. A site holds up to 200 snippets per version.

## Reader variables

On a private site that signs readers in with JWT or with EvoHub members, `{{user.name}}`, `{{user.email}}` and any other claim of the reader's token are replaced with that reader's details when the page is shown:

```markdown
Welcome back, {{user.name}}. Your plan: {{user.plan}}.
```

On public sites and in previews they are left as written. See [Private docs](https://docs-dev.evohub.io/private-docs.md).

## Files and images

Paste or drop an image into the editor, or use the upload button, and EvoHub uploads it and inserts the Markdown. Uploaded PDFs are inserted as a link.

| Type | Largest file |
| --- | --- |
| PNG, JPEG, WebP, GIF | 5 MB |
| SVG, ICO | 1 MB |
| PDF | 20 MB |

SVG files are checked for anything that could run script and refused if they contain it. A site holds up to 500 MB and 2,000 files.

The **Assets** page lists every file with where it is used. **Copy URL** and **Copy Markdown** give you the reference. Deleting a file that a page still uses asks you to confirm, because it breaks those pages.

> [!NOTE]
> Uploaded files are reachable by their address even on a private site.

## Page settings

The settings button in the editor holds what is not part of the text: SEO title, description (up to 300 characters), link preview image, canonical address, **Hide from search engines**, **Sidebar title**, icon, **Hide from navigation**, and, on private sites, **Audience**. Settings are drafted with the page and go live when it is published.

## Writing in a repository

If your site is connected to GitHub, the same Markdown lives in files, with these settings as front matter. See [Docs as code with GitHub](https://docs-dev.evohub.io/github-sync.md).

## Related

- [Docs overview](https://docs-dev.evohub.io/docs-overview.md)
- [Docs as code with GitHub](https://docs-dev.evohub.io/github-sync.md)
- [API references and AI](https://docs-dev.evohub.io/api-references-and-ai.md)