Skip to main content

Getting started

From nothing to a running site in five steps.

You need Node.js 20+, Docusaurus 3.10+ and React 19. A site scaffolded with create-docusaurus@3.10 has all three; @docusaurus/faster and @docusaurus/theme-mermaid are peer dependencies that npm installs for you.

If you already have a Docusaurus site, skip step 1.

1. Scaffold a site​

npx create-docusaurus@3.10 my-docs classic --typescript
cd my-docs

2. Install the theme​

npm install @voraus/docusaurus-theme

The package is on the public npm registry, so there is no .npmrc to write, no registry to point at and no token to supply, in CI or on your machine.

3. Replace docusaurus.config.ts​

Delete what the scaffold generated and write this:

docusaurus.config.ts
import { createConfig } from '@voraus/docusaurus-theme'
import pkg from './package.json'

export default createConfig({
  title: 'voraus.example',
  tagline: 'voraus Example Project',
  projectName: 'voraus-example',
  version: pkg.version,
  docs: {
    sidebarPath: './sidebars.ts',
    editUrl: 'https://github.com/vorausrobotik/voraus-example/tree/main/docs/',
  },
})

That is the whole configuration. title and projectName are required, and projectName must be your repository name, which is also the path your docs are published under.

Do not add the theme to themes yourself. createConfig() does it, in the position that lets it wrap Docusaurus' own components instead of replacing them.

4. Clear out the demo content​

The scaffold ships a tutorial, a blog and two custom pages. The theme disables blog and pages, so remove them along with the sample docs:

rm -rf docs blog src/pages src/css && mkdir docs

Then write your landing page:

docs/index.md
---
slug: /
sidebar_position: 1
---

# Introduction

Welcome to the voraus.example documentation.

slug: / matters: without a page at the site root the build fails its own link check.

5. Run it​

npm start

You should see the voraus wordmark in the navbar, your project name and version beside it, a search bar, and Roboto everywhere.

npm run build

This is what gets published. It fails on broken links, anchors and images, on purpose.

Next​

Writing content shows what you can put in a page. Worth reading before you write much: the theme uses strict MDX, and three familiar spellings no longer work.