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

Task	Steps
Add docs section	Create folder in `website/docs/`, add `_category_.json`, add Markdown files
Change theme colors	Edit `src/css/custom.css` (`:root` and `[data-theme='dark']` variables)
Add custom component	Create in `src/components/MyComponent/index.js`, import with `@site/src/components/MyComponent`

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.

sidecar-website

Docusaurus Documentation Site

Quick Start

Project Structure