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
.tsxcomponents. - 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β
| Variable | Light | Dark | Use for |
|---|---|---|---|
--ifm-background-color | #FFFFFF | #1b1b1d | page background |
--ifm-background-surface-color | #FFFFFF | #242526 | cards, panels |
--ifm-color-emphasis-100 | very light | very light | subtle backgrounds |
--ifm-color-emphasis-200 | light | light | borders |
--ifm-color-emphasis-300 | medium | medium | disabled elements |
--ifm-color-emphasis-600 | dark | dark | secondary text |
--ifm-color-emphasis-800 | very dark | very dark | primary text |
--ifm-color-primary | #FF9900 | #FFB340 | primary actions |
--ifm-color-primary-dark | darker | darker | hover states |
--ifm-color-primary-light | lighter | lighter | active 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:
| Source | Served 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" />
Links (MUST)β
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 for | templates, guidelines, portable content | interactive features β colour palettes, logo previews |
| React components | not allowed | allowed |
| Portability | copies cleanly into another repository | Docusaurus-specific |
- Plain Markdown SHOULD be preferred; MDX is for pages that genuinely need a component.
- A folder's
README.mdMUST 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)' |