AI coding agents and docs tooling increasingly look for /llms.txt to get a site overview without crawling HTML. A local plugin builds both files from the docs plugin's loaded content in sidebar order, so they never drift from the published docs and need no extra dependency. Only the English build emits them, since translated locales would otherwise duplicate the content.
5.0 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
plugins/llms-txt.ts Local plugin: writes build/llms.txt and llms-full.txt
Key Config
docusaurus.config.ts— Site config, navbar (Learn, How-To, Reference, Feature map, Blog, Changelog), footer, redirects from old/docs/commands/*pathssidebars.ts— Learn / How-To / Understand / Reference / Troubleshooting, with nested command subcategoriesplugins/llms-txt.ts— On the English build, writes/llms.txt(sidebar-ordered link index with first-sentence descriptions) and/llms-full.txt(all sidebar docs concatenated). Docs missing fromsidebars.tsare left out of bothonBrokenLinks: '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_positionfor 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 insrc/data/featureMap.ts; update them when commands or targets change - Every
hrefinfeatureMap.tsmust map to an existing page underdocs/(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--primarygreen,.button--secondaryoutlined - 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/.