AGENTS.md@website git:20260920.7250fc8A

Immutable. This exact content is served forever at /api/v1/blob/192d1bc542d995b2.

# AGENTS.md

This guidance applies to the `website/` directory.

This is the **documentation website** for the skillshare CLI. See the parent `../AGENTS.md` for CLI/Go codebase details and the project-wide rules (run frontend tooling inside the devcontainer, never on the host).

## Commands

```bash
pnpm start          # Dev server with hot reload (localhost:3000)
pnpm run build      # Production build → ./build/ (fails on broken links)
pnpm run serve      # Serve production build locally
pnpm run typecheck  # TypeScript type checking (tsc)
pnpm run clear      # Clear Docusaurus cache (.docusaurus/)
```

Run these inside the devcontainer (`docker exec <container> bash -lc 'cd /workspace/website && ...'`). CI uses `npm ci && npm run build`.

## Stack

Docusaurus 3.9.2 with React 19, TypeScript, MDX. Themes: `@docusaurus/theme-mermaid` (diagrams), `@easyops-cn/docusaurus-search-local` (search). Icons from `lucide-react`. Prism languages: bash, powershell, yaml.

## Structure

```
docs/                        ~100 Markdown pages, English only
  intro.md                   /docs/ landing page
  getting-started/           Install → first sync
  learn/                     Quickstarts by scenario
  how-to/                    daily-tasks/, sharing/, advanced/, recipes/
  understand/                Concepts, design philosophy
  reference/
    commands/                One page per CLI command (33 commands + index)
    targets/                 Supported targets, target config
    appendix/                URL formats, env vars, file structure
    filtering.md
  troubleshooting/           Errors, FAQ, Windows
blog/                        Blog posts (enabled, /blog)
src/
  pages/index.tsx            Homepage: interactive "string board" hero, install tabs,
                             four-moves diagram, feature-map teaser, CTA
  pages/index.module.css     Homepage styles (hand-drawn tokens from custom.css)
  pages/features.tsx         /features — Feature Map: all commands grouped by job, live filter
  pages/changelog.md         /changelog, updated by hand at release time alongside CHANGELOG.md
  data/featureMap.ts         Command groups shared by the homepage teaser and /features
  components/                AsciinemaPlayer
  css/custom.css             Design system (tokens, typography, dark/light)
static/img/                  Screenshots, logo, social card
```

## Key Config

- `docusaurus.config.ts` — Site config, navbar (Learn, How-To, Reference, Feature map, Blog, Changelog), footer, redirects from old `/docs/commands/*` paths
- `sidebars.ts` — Learn / How-To / Understand / Reference / Troubleshooting, with nested command subcategories
- `onBrokenLinks: 'throw'` — a bad link fails the build
- Color mode: default **light**, `respectPrefersColorScheme: false`
- Mermaid config lives in `themeConfig.mermaid`; no per-diagram `%%{init}%%`

## Docs Conventions

- Each doc has YAML frontmatter with `sidebar_position` for ordering
- Command docs follow: description, usage, flags table, examples
- Cross-reference with relative markdown links: `[sync](../commands/sync.md)`
- Before documenting a flag, grep `cmd/skillshare/` to confirm it exists
- Screenshots go in `static/img/` named `<feature>-demo.png`
- Mermaid: use `<br/>` for line breaks in node labels, keep labels short

## Homepage / Feature Map Notes

- Boards are laid out at a fixed design width (1168px) and scaled with a `ResizeObserver`; below 640px the hero board becomes a pin-chip list with the same state
- Interactive state is local React state only (no persistence)
- Counts (`COMMAND_COUNT`, `TARGET_COUNT`) live in `src/data/featureMap.ts`; update them when commands or targets change
- Every `href` in `featureMap.ts` must map to an existing page under `docs/` (the build's broken-link check covers them)

## Design System (custom.css)

- Hand-drawn "paper" look: dot-grid background, wobbly border radii (`--radius-wobbly*`), hard offset shadows (`--shadow-md`, `--shadow-lg`), post-it yellow highlights
- Palette tokens: `--color-paper`, `--color-pencil`, `--color-blue` (dark mode: amber), `--color-accent`, `--color-success`, `--color-danger`, `--color-postit`
- Fonts: Kalam (handwritten accents), Inter (headings), IBM Plex Sans (body), JetBrains Mono (code)
- Buttons: pill radius, `.button--primary` green, `.button--secondary` outlined
- Dark mode is a warm parchment palette; new components should use the tokens so they adapt automatically

## Deployment

Static site at `https://skillshare.runkids.cc`, built and deployed to GitHub Pages by `.github/workflows/website-pages.yml` on pushes to `main` that touch `website/`.