website

Imported from runkids/skillshare (website/AGENTS.md). Install upstream with npx skills add runkids/skillshare --skill website. Copyright stays with the author.

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

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/.