Writing content

Everything below is shown twice: the source to copy, and what it renders to. If it works here, it works in your site: this page is built by the theme's own test suite on every run.

The heading has to come first in the file, before any MDX expression: Docusaurus reads the sidebar label from a leading #, and falls back to the filename when something else is in the way.

Admonitions

:::warning[Mind the baseUrl]

vdoc serves each release from `/static/projects/<project>/<version>/`.

:::

Mind the baseUrl

vdoc serves each release from /static/projects/<project>/<version>/.

Five types are available, and the title in brackets is optional:

:::note[Note]
:::tip[Tip]
:::info[Info]
:::warning[Warning]
:::danger[Danger]

Note

Grey. For an aside.

Tip

Green. Colors come from the voraus style guide.

Info

Blue.

Danger

Red. For something that breaks.

Diagrams

Fenced mermaid blocks render as diagrams. No import, no setup.

```mermaid
flowchart LR
  A[Write] --> B[Build] --> C[Publish]
```

A diagram can carry a caption and an anchor, so that the prose can point at it. Both go on the fence line, in quotes:

```mermaid title="How a page reaches the reader" id="serving-a-page"
sequenceDiagram
  Reader ->> vdoc: opens /voraus-example/1.2.0/
  vdoc ->> Site: frames the published build
  Site -->> Reader: rendered page
```

How a page reaches the reader

With an id, a link anywhere on the site reaches the diagram: this page's is how a page reaches the reader. Broken anchors fail the build, so a link to a diagram that was renamed or removed is caught rather than shipped.

Mermaid draws in the browser, so the static HTML for a diagram is empty until the page hydrates.

Both diagrams above sit in a viewer that zooms, pans and opens full screen. See Diagrams for the controls.

Code blocks

```ts title="docusaurus.config.ts" {2} showLineNumbers
import { createConfig } from '@voraus/docusaurus-theme'
export default createConfig({
  title: 'voraus.example',
  projectName: 'voraus-example',
})
```

docusaurus.config.ts

import { createConfig } from '@voraus/docusaurus-theme'
export default createConfig({
  title: 'voraus.example',
  projectName: 'voraus-example',
})

Every code block gets a copy button. title= names the file, {2} highlights a line.

Links

Link between pages by file path. Docusaurus rewrites them to routes at build time, so the same link also works when someone reads the file in the repository.

See [Deployment](04-deployment.mdx) and [its version section](04-deployment.mdx#pass-version-from-your-own-packagejson).

Broken links and broken anchors fail the build, so a typo cannot ship.

Sidebar order

Number-prefix your files. Docusaurus strips the prefix from the URL:

docs/01-getting-started.md   ->   /getting-started
docs/02-writing-content.mdx  ->   /writing-content

A directory becomes a category, and an index.md inside it becomes that category's page.

Native MDX only

The theme turns on the Docusaurus v4 flags, which switches off the MDX v1 compatibility shims. Three old spellings stop working, and two of them fail silently, so grep for them once when migrating an existing site:

Instead of	Write
:::warning Pay Attention	:::warning[Pay Attention]
<!-- comment -->	{/* comment */}
## My Heading {#my-id}	## My Heading {/* #my-id */}

This command converts existing heading ids for you:

npx docusaurus write-heading-ids --syntax mdx-comment --migrate

Both extensions are compiled as MDX, because Docusaurus leaves markdown.format at mdx and the theme does not change it. So an HTML comment is a syntax error in a .md file too: the rules above apply to every page, whatever you name it.

Name a file .mdx when it uses MDX syntax anyway: Prettier, ESLint and GitHub parse by extension, and .md promises them CommonMark.