Zum Hauptinhalt springen

Docusaurus

πŸ€– Generated with Claude Code

⚠️ Not yet reviewed

Co-Authored-By: Claude (noreply@anthropic.com)

How to write pages and components for the documentation site. Where a document belongs, and how its prose is written, is DOCUMENTATION-GUIDELINES.md in the repository root; this page covers only the Docusaurus mechanics.

Dark Mode (MUST)​

The site ships both themes and defaults to dark. A hardcoded colour therefore breaks half the readers.

  • Inline styles MUST use Docusaurus CSS variables, never literal colour values.
  • MDX components MUST follow the same rule as .tsx components.
  • A theme-dependent value MUST NOT be branched in JavaScript β€” the variable already resolves per theme.

❌ Wrong β€” light mode only:

<div style={{
backgroundColor: '#f8f8f8',
color: '#666',
border: '1px solid #e0e0e0'
}}>

βœ… Correct β€” works in both themes:

<div style={{
backgroundColor: 'var(--ifm-background-surface-color)',
color: 'var(--ifm-color-emphasis-600)',
border: '1px solid var(--ifm-color-emphasis-200)'
}}>

The One Exception: Colours That Are the Content (MAY)​

A page whose subject is a colour MAY use the literal value, because the swatch has to show the actual brand colour β€” var(--ifm-…) would show the wrong one. This applies to the swatch itself only. Everything around it β€” labels, captions, card backgrounds, borders β€” MUST still use variables.

// The swatch: literal, because the hex is the subject
<span style={{background: '#FFC056'}} />

// Its caption: variable, because it is ordinary page chrome
<span style={{color: 'var(--ifm-color-emphasis-600)'}}>#FFC056</span>

CSS Variables​

Colours​

VariableLightDarkUse for
--ifm-background-color#FFFFFF#1b1b1dpage background
--ifm-background-surface-color#FFFFFF#242526cards, panels
--ifm-color-emphasis-100very lightvery lightsubtle backgrounds
--ifm-color-emphasis-200lightlightborders
--ifm-color-emphasis-300mediummediumdisabled elements
--ifm-color-emphasis-600darkdarksecondary text
--ifm-color-emphasis-800very darkvery darkprimary text
--ifm-color-primary#FF9900#FFB340primary actions
--ifm-color-primary-darkdarkerdarkerhover states
--ifm-color-primary-lightlighterlighteractive states

Spacing and Typography​

style={{
padding: 'var(--ifm-spacing-horizontal)',
margin: 'var(--ifm-spacing-vertical)',
fontFamily: 'var(--ifm-font-family-base)',
fontSize: 'var(--ifm-font-size-base)',
lineHeight: 'var(--ifm-line-height-base)'
}}

Asset Paths (MUST)​

baseUrl is /, so there is no path prefix. Two static directories are mounted, and both are served from the site root:

SourceServed at
site/static// β€” site/static/logos/… β†’ /logos/…
assets/ (repository root)/ β€” its children are copied, so assets/colors/… β†’ /colors/…
// Correct
<img src="/logos/TOGETHER/Together_Logo.svg" />

// Wrong β€” /docs/ is not the base path
<img src="/docs/logos/TOGETHER/Together_Logo.svg" />

A component's own asset SHOULD be imported rather than referenced by path:

import logo from './logo.svg';

<img src={logo} alt="Logo" />

Internal navigation MUST use @docusaurus/Link, so the router handles it and the build can check the target. A native <a> reloads the whole page and is not checked.

import Link from '@docusaurus/Link';

// Correct
<Link to="/development/brand-guide/">Brand Guide</Link>

// Wrong
<a href="/development/brand-guide/">Brand Guide</a>

// Anchors work the same way
<Link to="/development/brand-guide/diagrams/style-guide#accessibility">
Accessibility
</Link>

Links inside Markdown follow the table in DOCUMENTATION-GUIDELINES.md, section 8 β€” relative within a root, site-absolute between roots.

React Components​

import React from 'react';
import Layout from '@theme/Layout';

export default function MyPage(): JSX.Element {
return (
<Layout title="My Page">
<main style={{padding: '2rem 0'}}>
<div className="container">
<div style={{
backgroundColor: 'var(--ifm-background-surface-color)',
border: '1px solid var(--ifm-color-emphasis-200)',
borderRadius: '8px',
padding: '2rem'
}}>
<h2>Content</h2>
</div>
</div>
</main>
</Layout>
);
}

In MDX, a component is imported from @site:

import { ColorSwatch } from '@site/src/components/Colors';

<ColorSwatch hex="#FF9900" name="TOGETHER Orange" />

MDX or Markdown (SHOULD)​

.md.mdx
Use fortemplates, guidelines, portable contentinteractive features β€” colour palettes, logo previews
React componentsnot allowedallowed
Portabilitycopies cleanly into another repositoryDocusaurus-specific
  • Plain Markdown SHOULD be preferred; MDX is for pages that genuinely need a component.
  • A folder's README.md MUST record which of its files are MDX.

Every page is compiled as MDX regardless of extension, so < and { are markup in both β€” see DOCUMENTATION-GUIDELINES.md, section 6.

Build (MUST)​

cd site
npm run build
  • The build MUST pass before committing.

  • Broken links are reported as warnings, so the build succeeds with them. The output MUST be read, not just the exit code:

    npm run build 2>&1 | grep -i broken
  • MDX compilation errors and missing assets MUST be fixed, not ignored.

Before Committing​

Check
npm run build passesβœ…
no broken links in the outputβœ…
light mode correctβœ…
dark mode correctβœ…
mobile view correctβœ…
assets loadβœ…

Common Pitfalls​

βŒβœ…
color: '#666'color: 'var(--ifm-color-emphasis-600)'
src="/docs/logos/cca.svg"src="/logos/cca.svg"
<a href="/guide">Guide</a><Link to="/guide">Guide</Link>
backgroundColor: isDark ? '#1a1a1a' : '#f8f8f8'backgroundColor: 'var(--ifm-background-surface-color)'

References​