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

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.

> [!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

:::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.

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

#Steps

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

:::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.

:::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.

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

#Columns

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

#Badge

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

Webhooks :badge[New]{color=blue}

#Video embed

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

::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:

```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.

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:

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

On public sites and in previews they are left as written. See Private docs.

#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.

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.

#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.

#Related

• Docs overview
• Docs as code with GitHub
• API references and AI