Imported from casys-kaist/LLMServingSim (docs/AGENTS.md). Install upstream with npx skills add casys-kaist/LLMServingSim --skill docs. Copyright stays with the author.

LLMServingSim Documentation Site (docs/)

Guidelines for collaborators (humans and AI coding agents) updating the LLMServingSim documentation site at https://llmservingsim.ai.

The repo's README.md is intentionally minimal and points readers here for everything beyond install + run. Long-form content (CLI flag tables, dataset schema, profiler walkthroughs, validation results) lives on this site, not in the README. See the root AGENTS.md for the README and docs split.

What this is

A Docusaurus 3 site (TypeScript, classic preset) that serves the public LLMServingSim documentation. The site is split into two top-level navbar sections:

• For Users — installation, simulator/profiler/bench guides, configuration reference. (Currently the only populated section.)
• For Contributors — onboarding for people developing LLMServingSim itself. Placeholder only at this stage.

The reference design is the vLLM docs — sidebar-first navigation, deep hierarchy, audience segmentation.

Local development

Requirements: Node.js ≥ 20 (the site uses Docusaurus 3, which dropped Node 18 support) and pnpm.

cd docs/
pnpm install
pnpm start          # dev server on http://localhost:3000
pnpm build          # static build to docs/build/
pnpm serve          # serve the production build locally

Run pnpm build at least once before sending a PR — the dev server is more forgiving than the production build (broken links, dead anchors, etc. fail the build).

Repository layout

docs/
├── docusaurus.config.ts        site metadata, navbar, footer, theme
├── sidebars.ts                 sidebar trees (userSidebar, contributorSidebar)
├── docs/                       markdown content (one folder per top-level section)
│   ├── getting-started/
│   ├── simulator/
│   ├── profiler/
│   ├── bench/
│   ├── validation/
│   ├── workloads/
│   ├── reference/
│   └── contributor/
├── src/
│   ├── pages/index.tsx         landing page (Hero + feature cards)
│   ├── pages/index.module.css  landing page styles
│   ├── components/
│   │   └── HomepageFeatures/   the four feature cards on the landing page
│   └── css/custom.css          global theme overrides (primary color, etc.)
└── static/
    ├── CNAME                   custom domain (llmservingsim.ai)
    └── img/                    favicon, logo, social card
        ├── llmservingsim_full_primary_transparent.png       light-mode logo (indigo + black)
        ├── llmservingsim_full_primary_dark_transparent.png  dark-mode logo (indigo + white)
        ├── llmservingsim_full_reverse_white_transparent.png all-white reverse
        ├── llmservingsim_full_mono_black_transparent.png    all-black mono
        └── llmservingsim_compact_primary_transparent.png    navbar/compact mark

The dark-mode logo is referenced from the root README.md via <picture> + prefers-color-scheme; the light variant is the website's hero/navbar default with a CSS invert(1) hue-rotate(180deg) filter for dark mode.

Adding a new doc page

1. Pick the section folder under docs/ (or create a new one, see below).

2. Create a markdown file:

   ---
   sidebar_position: 3
   title: Reading the Output
   ---
   
   # Reading the Output
   
   ...content...

   sidebar_position controls ordering inside the section. title controls the sidebar label (defaults to the H1 if omitted).

3. The page appears automatically in the relevant sidebar — sidebars are autogenerated from the folder structure (see sidebars.ts).

Adding a new section (top-level folder)

1. Create the folder, e.g. docs/new-section/.

2. Add a _category_.json:

   {
     "label": "New Section",
     "position": 8,
     "link": {
       "type": "generated-index",
       "description": "What this section is about."
     }
   }

3. Add the section to sidebars.ts under userSidebar or contributorSidebar.

Editing the landing page

• Hero (title, tagline, buttons): src/pages/index.tsx
• Feature cards (the four icons + text below the hero): src/components/HomepageFeatures/index.tsx — edit the FeatureList array.
• Hero / card styles: src/pages/index.module.css and src/components/HomepageFeatures/styles.module.css.
• Global colors / fonts: src/css/custom.css.

Editing navbar / footer / metadata

docusaurus.config.ts:

• title, tagline, url, favicon — top-level site metadata
• themeConfig.navbar.items — nav links (sidebar links use type: 'docSidebar')
• themeConfig.footer.links — footer columns
• presets[0][1].docs.editUrl — "Edit this page" link target

Deployment

The site auto-deploys via GitHub Actions on every push to main that touches docs/**:

1. Action checks out the repo and installs Node 22 + pnpm.
2. Runs pnpm install --frozen-lockfile && pnpm build in docs/.
3. Uploads docs/build/ as a Pages artifact via actions/upload-pages-artifact@v3.
4. actions/deploy-pages@v4 publishes the artifact to GitHub Pages (repo Settings → Pages → Source = GitHub Actions). The custom domain llmservingsim.ai is preserved by docs/static/CNAME.

A successful deploy typically takes ~2 minutes after the merge. If the build fails, the previous deploy stays live.

The Pages-source toggle (GitHub Actions vs. Deploy from a branch) is a one-time repo-settings choice; the workflow runs but the deploy step is silently a no-op if the source is set to anything else.

Conventions

• Language: English only. Match the rest of the LLMServingSim repo.
• Code blocks: always specify the language (```bash, ```python, ```yaml). The site's Prism config preloads bash, python, json, yaml.
• Images: under static/img/, reference as /img/<file>.png.
• Internal links: use relative paths like /docs/simulator/cli-overview, not full URLs. onBrokenLinks: 'throw' will fail the build on dead links.
• Component names: PascalCase (HomepageFeatures).
• File naming: kebab-case.md for docs, matches the URL slug.
• Admonitions: the title goes in brackets — :::caution[Title here], closed by :::. The bare form :::caution Title here is Docusaurus v2 syntax: v3 does not recognise it as a directive, so the whole block renders as a literal paragraph starting :::caution .... Nothing warns — not the build, not onBrokenLinks: 'throw' — and it sat on 13 pages before anyone looked at the rendered output. A titleless :::note needs no brackets.
• A fact the code owns does not go in prose. Counts, file lists, flag sets, defaults: if a script or config decides it, prose that repeats it goes silently wrong the first time the code changes, and readers take prose as specification. Write "every scenario in serving/validate-baselines.txt", not "58 scenarios". Sample output and quoted examples are exempt — readers already read a terminal block or a blockquote as a snapshot from one particular run. Point at the generator instead of mirroring it: --list and --help cannot go stale.

Checks that run on the site

• pnpm build runs two hooks around it. prebuild regenerates src/pages/changelog.md from the repo-root CHANGELOG.md (scripts/sync-changelog.mjs) — edit CHANGELOG.md only; the page is generated, and committed so a fresh clone works. postbuild runs scripts/check-rendered.mjs.
• scripts/check-rendered.mjs scans the built HTML for source syntax that survived into visible text — unparsed admonitions, bold, links, headings, table rows, doubled list markers, visible HTML comments, JSX brace leaks. It strips <pre>/<code>/<script> first, since syntax is legitimate there, and exits non-zero on any hit. It exists because this whole class of bug is not an error: markup Docusaurus cannot parse becomes text, so the only way to catch it is to look at the output. Run it with pnpm check-rendered after a build.
• Mermaid is checked structurally, from the source. theme-mermaid leaves no <pre class="mermaid"> in the static HTML — the diagram source goes into the JS bundle and renders in the browser — so the HTML scan cannot see diagrams at all. The checker reads the ```mermaid blocks out of the .md/.mdx files instead and reports file:line. It catches an unknown diagram type, an empty diagram, and a subgraph with no matching end. It is not mermaid's parser, which needs a DOM even to parse (mermaid.parse() in bare node fails on DOMPurify.addHook) and would mean a jsdom dependency. So bad node syntax inside a structurally sound diagram, and anything visual — overflow, colour contrast, a diagram that renders but says the wrong thing — still needs you to open the page.

Things explicitly not in scope yet

These are deferred until the site has more content and traction:

• Full content for any docs page (most are stubs)
• Algolia DocSearch integration
• Versioned docs (latest vs. v1.x.y)
• Internationalization
• Versioned changelog page (footer "Changelog" still links out to GitHub)
• Blog
• API reference auto-generation from Python source

Reference site

When in doubt about layout or tone, look at the vLLM docs: https://docs.vllm.ai/en/latest/.