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

88 lines
5.0 KiB
Markdown

# 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
```bash
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/`.