Files
skillshare/website/AGENTS.md
T
Willie 7250fc8558 docs: rename website/CLAUDE.md to AGENTS.md
Claude Code now reads AGENTS.md, so the repo keeps one instruction
file format instead of two.
2026-09-21 01:46:37 +08:00

4.5 KiB

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