Files
skillshare/website/AGENTS.md
T
Willie 2782294b01 feat(website): generate llms.txt and llms-full.txt at build time
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.
2026-09-28 22:58:33 +08:00

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/* paths
  • sidebars.ts — Learn / How-To / Understand / Reference / Troubleshooting, with nested command subcategories
  • plugins/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 from sidebars.ts are left out of both
  • 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/.