sidecar-website

# Docusaurus Documentation Site

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

## Quick Start

```bash
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:

```markdown
---
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

```markdown
# 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:

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

### Sidebar Configuration

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

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

### Using MDX

Docs support MDX (Markdown + JSX):

```mdx
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.

```jsx
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:
```jsx
import screenshot from '@site/static/img/logo.png';
<img src={screenshot} alt="Logo" />
```

## Blog Posts

Date-prefixed Markdown files in `blog/`:

```markdown
---
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`).

```jsx
<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

```bash
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'`. T