Docs Site Structure

This page sets out how the website is organised: the header links, the docs sidebar, the URL of every page, page templates, what moves from this wiki to the site, and the 404 page. Use it when adding, moving or renaming a page.

The page list and URLs below are Proposed until the owner approves them; the third quickstart's name and trailingSlash: true are decided (Design System). Each docs page is marked with where its content comes from today:

• Exists: written, in the repository or the wiki; needs adapting.
• Partial: some of it exists.
• Gap: nothing written yet.

Header links

Item	Goes to
Logo	/ (landing page)
Docs	/docs/
Migrating	/docs/guides/migrating-from-businesstimedelta/
Playground	/playground/
Benchmarks	/docs/benchmarks/
Search, GitHub, theme toggle	(icons and field, Components)

"Migrating" is in the header because businesstimedelta users are a large share of the first readers. Changelog and FAQ are in the sidebar and footer.

Sidebar and pages

All URLs start with https://workclock.karthik.nz. Sections in sidebar order:

Start

Page	URL	Content today	Status
Overview	/docs/	README intro and "Use cases"; wiki Home	Exists
Install	/docs/install/	README "Install", "Requirements", "Time zone data"; Getting Started; FAQ on toolchains	Exists
Quickstart: Rust	/docs/quickstart/rust/	README "Rust"; crates/workclock/examples/sla.rs	Exists
Quickstart: Python	/docs/quickstart/python/	README "Python"; examples/python/sla.py	Exists
Quickstart: JavaScript	/docs/quickstart/javascript/	README "JavaScript"; js/README.md; js/examples/sla.mjs	Exists

Concepts

Page	URL	Content today	Status
Schedules	/docs/concepts/schedules/	DESIGN.md "Model", "Combining rules" (examples U); Concepts	Exists
Rules	/docs/concepts/rules/	DESIGN.md "Rules": WorkDay (O), Break (K), Holidays (H), zones of rules (Z)	Exists
Adding time	/docs/concepts/adding-time/	DESIGN.md "add(t, d) and sub(t, d)" (A)	Exists
Measuring time	/docs/concepts/measuring-time/	DESIGN.md "between(a, b)" (B)	Exists
Periods	/docs/concepts/periods/	DESIGN.md "next_period(t) and previous_period(t)" (P)	Exists
Time zones and DST	/docs/concepts/time-zones-and-dst/	DESIGN.md "Time zones and DST" (D); README "Time zone data"	Exists
Errors	/docs/concepts/errors/	DESIGN.md "Errors and termination", "Error types" (E); js/README.md "Errors"	Exists
Inputs and precision	/docs/concepts/inputs-and-precision/	DESIGN.md "Inputs and precision" (N); js/README.md "Instants and durations"	Exists. Proposed addition: not in the brief's list, but the section has no other home and agents often get instants and units wrong.

Guides

Page	URL	Content today	Status
Support SLAs	/docs/guides/support-slas/	The README scenario and the three sla examples	Exists
Payroll and overtime	/docs/guides/payroll-and-overtime/	README "Use cases"; a worked example with between over a shift	Exists
Overnight shifts	/docs/guides/overnight-shifts/	DESIGN.md "WorkDay" overnight examples (O); README "Correct"	Exists
Delivery ETAs	/docs/guides/delivery-etas/	README "Use cases"; a worked example with add over operating hours	Exists
Batch operations	/docs/guides/batch-operations/	README (Python batch methods), js/README.md (betweenMany, Float64Array), Concepts, the benchmarks' "batch" case	Exists
Migrating from businesstimedelta	/docs/guides/migrating-from-businesstimedelta/	MIGRATING.md; DESIGN.md "Compatibility layer" (C); Migrating from businesstimedelta	Exists

Guides use only operations workclock has. DESIGN.md "Scope" lists what 0.1.1 does not do (business days or weeks as units, per-date overrides of working hours); a guide that needs either is not written.

Reference

Page	URL	Content today	Status
Rust	external link to https://docs.rs/workclock	rustdoc, built by docs.rs on publish	Exists, first in the Reference section
Python	/docs/reference/python/	Docstrings in python/workclock/_schedule.py, _errors.py, _arrays.py	Exists
Python: workclock.compat	/docs/reference/python-compat/	Docstrings in python/workclock/compat.py; MIGRATING.md	Exists
JavaScript	/docs/reference/javascript/	TSDoc in the generated js/pkg/web/workclock.d.ts and js/errors.d.ts; js/README.md	Exists

Hand-written, with Markdown tables for parameters (decision log on Design System).

More

Page	URL	Content today	Status
Playground	/playground/ (outside /docs/, full width)	The interactive week strip with every input, plus the three-language code for the current inputs	Exists
Benchmarks	/docs/benchmarks/	benchmarks/RESULTS.md, benchmarks/README.md; DESIGN.md "Performance"	Exists
Changelog	/docs/changelog/	CHANGELOG.md	Exists
FAQ	/docs/faq/	FAQ	Exists

The content folder

Fumadocs builds the sidebar from website/content/docs/ and each folder's meta.json (page conventions). A folder name in parentheses groups files without adding to the URL, so (start)/install.mdx is /docs/install/; ...folder lifts a folder's pages into the parent list; ---Label--- is a separator; external:[Text](url) is an external link.

content/docs/
├── meta.json
├── index.mdx
├── (start)/
│   ├── install.mdx
│   └── quickstart/
│       ├── meta.json
│       └── rust.mdx, python.mdx, javascript.mdx
├── concepts/
│   ├── meta.json
│   └── schedules.mdx, rules.mdx, adding-time.mdx, measuring-time.mdx,
│       periods.mdx, time-zones-and-dst.mdx, errors.mdx, inputs-and-precision.mdx
├── guides/
│   ├── meta.json
│   └── support-slas.mdx, payroll-and-overtime.mdx, overnight-shifts.mdx,
│       delivery-etas.mdx, batch-operations.mdx, migrating-from-businesstimedelta.mdx
├── reference/
│   ├── meta.json
│   └── python.mdx, python-compat.mdx, javascript.mdx
├── benchmarks.mdx
├── changelog.mdx
└── faq.mdx

content/docs/meta.json:

{
  "title": "Docs",
  "pages": [
    "index",
    "---Start---",
    "...(start)",
    "---Concepts---",
    "...concepts",
    "---Guides---",
    "...guides",
    "---Reference---",
    "...reference",
    "---More---",
    "[Playground](/playground/)",
    "benchmarks",
    "changelog",
    "faq"
  ]
}

content/docs/reference/meta.json:

{
  "pages": [
    "external:[Rust (docs.rs)](https://docs.rs/workclock)",
    "python",
    "python-compat",
    "javascript"
  ]
}

Each folder's meta.json lists its pages in the order of the tables above. Check in the first build that ...(start) works on a folder group; if not, use a full path or move the item.

URL rules

• One site, https://workclock.karthik.nz/: landing page at /, docs under /docs/, playground at /playground/.
• Lowercase plain-English words joined with hyphens: time-zones-and-dst, not tz-dst.
• No version, date or language code in a URL; one version of the docs for now.
• Pages end with / (trailingSlash: true).
• A slug never changes once published; a moved page leaves a redirect page at the old URL (Agent Experience).
• Heading anchors come from heading text; rewording a published heading breaks links to it (Writing Style).
• Every docs page has a Markdown version at its URL without the trailing slash plus .md (Agent Experience).

Page templates

Every page's front matter has title (shown in the sidebar and llms.txt; sentence case, under 28 characters) and description (one sentence: what the reader will learn).

---
title: Adding time
description: Find the instant reached after adding or subtracting an amount of working time, with add and sub.
---

Template	Sections, in order
Quickstart	What the reader will have at the end, in one sentence; the install block for that language; the README scenario as a complete program ending in the result; "What just happened" in three or four sentences naming Schedule, the rules and the call; next links to Concepts: Schedules and the nearest guide.
Concept	A one- or two-sentence definition; a static week strip or compact diagram of the page's scenario; code tabs in all three languages; "Edge cases", a table of the relevant DESIGN.md examples with their IDs (O1, D8, E7) so readers can find the test; "See also".
Guide	The problem in the reader's words ("A ticket is due 8 working hours after it is opened. When is that?"); the schedule as a short list of rules; code tabs, one complete program per language; the result and its week strip; edge cases (holidays, DST, overnight), each linked to its concept page; "See also".
Reference	One page per language. Per type or function: signature, TypeTable of parameters, return value, what it raises or throws (from DESIGN.md's error table), one short example. Order: Schedule, rule types, operations, batch methods, errors.
FAQ	Accordions with one Accordion per question, each with an id (Components).

Proposed: Benchmarks, Changelog and the migration guide's "Fixed" and "Intentional differences" lists include the repository files with Fumadocs MDX's <include> (Markdown: include), so the site cannot drift from them. First check that <include> accepts a path outside content/ (such as ../../../CHANGELOG.md), and decide how to handle relative links inside those files.

What moves from the wiki to the site

The site becomes the place for people who use workclock. The wiki keeps what contributors and the maintainer need.

Wiki page	After the site launches
Home	Stays, shortened: what workclock is, a link to the site, the contributor pages
Getting Started	Moves to Install and the quickstarts; the wiki page becomes one line linking to the site
Concepts	Moves to Concepts; becomes a link
Migrating from businesstimedelta	Moves to the migration guide; becomes a link
Benchmarks	Moves to Benchmarks (RESULTS.md); becomes a link
FAQ	Moves to FAQ; becomes a link
Design and ADRs, Release Process, Contributing	Stay
The Design System section	Stays, for whoever builds the site

Check facts against the repository before moving a page; the repository wins.

Agent files

llms.txt, llms-full.txt and the .md version of each page are route handlers that write files at build time. What they contain, their URLs and how they are built under a static export are on Agent Experience.

404 page

app/not-found.tsx becomes out/404.html (Next.js: static exports, deploying), which GitHub Pages serves for a missing URL. It uses the landing page's layout (fumadocs-ui also exports fumadocs-ui/layouts/home/not-found).

• H1 "Page not found", then "There is no page at this address. It may have moved, or the link may be mistyped."
• Links: Docs home, Install, a button that opens search, llms.txt.
• "If a link on this site brought you here, report it." linking to the "Docs problem" issue form (Components, Feedback link).
• No illustration, no joke.

Open items

None.