Docusaurus Documentation Site

The documentation site lives in website/. It uses Docusaurus with Node.js >= 20.

Quick Start

cd website
npm install    # First time only
npm start      # Dev server at http://localhost:3000

Project Structure

website/
├── docs/                    # Markdown documentation pages
├── blog/                    # Blog posts (date-prefixed markdown)
│   ├── authors.yml         # Blog author definitions
│   └── tags.yml            # Blog tag definitions
├── src/
│   ├── pages/              # Custom React pages (non-docs)
│   │   ├── index.js        # Front page (/)
│   │   └── index.module.css
│   ├── components/         # Reusable React components
│   └── css/
│       └── custom.css      # Global style overrides
├── static/                  # Static assets (copied as-is to build)
│   └── img/                # Images
├── docusaurus.config.js    # Main site configuration
├── sidebars.js             # Docs sidebar structure
└── package.json

Writing Documentation

Principles

• User-first: Answer "what can I do?" before "how does it work?"
• Scannable: Use headers, code blocks, tables for keyboard shortcuts
• Progressive disclosure: Quick overview -> detailed usage -> full reference
• Working examples: Every feature needs runnable code, not ... placeholders

Creating a New Doc

Add a Markdown file in website/docs/ with YAML frontmatter:

---
sidebar_position: 2
title: My New Page
---

# My New Page

Content here. Supports **Markdown** and MDX.

Frontmatter options:

• sidebar_position: Order in sidebar (lower = higher)
• sidebar_label: Override sidebar text
• title: Page title
• description: Meta description for SEO
• slug: Custom URL path

Plugin Documentation Pattern

# Plugin Name

One-line description.

![Screenshot](../../docs/screenshots/plugin-name.png)

## Overview
Brief explanation of UI layout and core purpose.

## Feature Section
Description with keyboard shortcut table:

| Key | Action |
|-----|--------|
| `s` | Stage file |
| `d` | View diff |

## Navigation
How to move around.

## Command Reference
Complete shortcut list by context.

Organizing Docs in Folders

docs/
├── intro.md
├── guides/
│   ├── _category_.json    # Folder metadata
│   ├── installation.md
│   └── configuration.md

_category_.json controls folder appearance:

{
  "label": "Guides",
  "position": 2,
  "collapsible": true,
  "collapsed": false
}

Sidebar Configuration

Auto-generates from docs/ folder structure. To customize, edit sidebars.js:

const sidebars = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Guides',
      items: ['guides/installation', 'guides/usage'],
    },
  ],
};

Using MDX

Docs support MDX (Markdown + JSX):

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm">npm install</TabItem>
  <TabItem value="yarn">yarn add</TabItem>
</Tabs>

Front Page

The front page is at website/src/pages/index.js -- a React component using Docusaurus Layout and theming.

export default function Home() {
  return (
    <Layout title="Home" description="...">
      <HomepageHeader />
      <main className="container">
        {/* Add content here */}
      </main>
    </Layout>
  );
}

Styling: index.module.css for page-specific, src/css/custom.css for global overrides.

Images and Screenshots

Website doc screenshots (for pages in website/docs/):

• Store in: docs/screenshots/ (project root)
• Reference: ![Alt text](../../docs/screenshots/filename.png)

README / repo doc screenshots:

• Store in: docs/screenshots/ (project root)
• Reference: ![Alt text](docs/screenshots/filename.png) (from repo root)

General website images (logos, icons):

• Store in: website/static/img/
• Reference: ![Alt text](/img/filename.png)

In JSX:

import screenshot from '@site/static/img/logo.png';
<img src={screenshot} alt="Logo" />

Blog Posts

Date-prefixed Markdown files in blog/:

---
slug: my-post
title: Post Title
authors: [default]
tags: [announcement, release]
---

Preview text shown in list.

<!-- truncate -->

Full content below the fold.

Style Guidelines

No Emoji Policy

Never use emoji in site content, components, or documentation. Use Lucide icons instead.

Icons (Lucide)

The site uses Lucide icon font (CDN import in docusaurus.config.js).

<i className="icon-terminal" />
<i className="icon-check" />
<i className="icon-git-branch" />

Common icons: icon-eye, icon-terminal, icon-rocket, icon-check, icon-copy, icon-external-link, icon-git-branch, icon-zap, icon-keyboard, icon-layers, icon-code.

Browse all: https://lucide.dev/icons

Terminal Aesthetic

• Monospace fonts (JetBrains Mono, Google Sans Code)
• Dark backgrounds with muted colors
• Bright accents from Monokai palette (green, blue, pink, yellow)
• Clean 1px borders, subtle gradients and glows

Building and Deploying

cd website
npm run build      # Outputs to website/build/
npm run serve      # Preview built site locally

Deploys automatically via GitHub Actions when changes to website/ merge to main.

• .github/workflows/deploy-docs.yml -- Deploys to GitHub Pages
• .github/workflows/test-docs.yml -- Validates PR builds
• Live site: https://marcus.github.io/sidecar

Common Tasks

Troubleshooting

• Build fails with broken links: Config uses onBrokenLinks: 'throw'. Temporarily change to 'warn' for local dev.
• Styles not updating: npm run clear && npm start
• GitHub Pages 404: Verify baseUrl matches repo name (/sidecar/).

Reference

For detailed site configuration (navbar, footer, theme config, future compatibility), see references/site-configuration.md.