Files
skillshare/website/AGENTS.md
T
Willie c1596262d5 build(website): compile the docs with Rspack
The docs build spent over five minutes in webpack for five locales.
@docusaurus/faster swaps in Rspack and SWC and cuts a local build from
161s to 25s, with the same pages and an identical search index.

Rspack orders one Infima rule after the search box's padding, which
pushed the navbar items right; custom.css restores the padding.
2026-09-27 19:28:48 +08:00

4.7 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. Builds with Rspack and SWC (future.experimental_faster, @docusaurus/faster); CSS order can differ from a webpack build, so compare screenshots after changing global styles. 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 Cloudflare Pages by .github/workflows/website-pages.yml on pushes to main that touch website/.