/sidecar-website

name: sidecar-website
description: Writing and maintaining the Sidecar Docusaurus documentation site, including page structure, doc authoring, blog posts, styling, images, and deployment workflow. Use when writing documentation, updating the docs site, adding pages or blog posts, or working with Docusaurus configuration.

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

**README / repo doc screenshots**:

• Store in: `docs/screenshots/` (project root)
• Reference: `` (from repo root)

**General website images** (logos, icons):

• Store in: `website/static/img/`
• Reference: ``

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 Mark