Docs Site for Plank Packages

[kfriars]

Destination

A build-ready spec for the infrastructure that lets each Plank Package's release workflow build and deploy its own Docs Versions (one per Major Line) to its own path on a single Docs Site (packages.plank.co/<package>) — a faithful-but-lightweight extension of plank.co's design, hosted on Cloudflare for $0 recurring with no third-party runtime services. No Package Docs are authored in this effort.

Notes

• Planning only. Tickets resolve decisions; building the Docs Site is handed off once the way is clear.
• One question at a time, and requirements come from the User (record costs, never verdicts) — both in AGENTS.md, both override skill defaults.
• Vocabulary lives in CONTEXT.md: Package, Package Docs, Major Line, Docs Version, Docs Site, Docs Tooling, Docs Config.
• Set by the User while charting (2026-09-11):
  • Package Docs are written in each Package's own repo; this repo holds infrastructure only.
  • Each Package's release workflow builds and deploys its own section (the Laminas / Spring model), using the Docs Tooling.
  • One Docs Version per Major Line (e.g. /snapshots/13.x), not per release tag.
  • Faithful extension of plank.co "as much as possible without burdening ourselves".
  • $0 recurring cost and no third-party runtime services.
  • Markdown Package Docs only.
• Set by the User in Which static site generator does the Docs Site use? (2026-09-11):
  • The Docs Site is built with Astro Starlight.
  • Follow Starlight's conventions as much as possible; break them only for a good reason.
• Set by the User on 2026-09-11: the Docs Site's hostname is packages.plank.co, because docs.plank.co already serves a WordPress site. See Confirm packages.plank.co can host the Docs Site.
• Set by the User on 2026-09-11: readers switch between a Package's Docs Versions in the UI. Search and links in Package Docs don't need to span Docs Versions.
• Set by the User on 2026-09-12: the Docs Site is served by a Pages router in front of a Worker per Docs Version, and plank.co's DNS stays at Namecheap. See Confirm packages.plank.co can host the Docs Site and ADR 0003.
• Set by the User on 2026-09-13 in How does the Docs Site move from the stand-ins to Plank's account, domain and Package repos?: there are no stand-ins. The Docs Site is built in the open on Plank's Cloudflare account and plank/docs from the start, with throwaway test Packages in plank, and packages.plank.co is pointed at it last, once a go-live checklist has passed and the User says go. This replaces the Note of 2026-09-12 about stand-ins. The map stays planning only.
• Set by the User on 2026-09-12: a private repo never has published docs. Ever. See How do the landing page and version switcher learn which Packages and Docs Versions exist?.
• Set by the User on 2026-09-12 in What do the landing page and a doc page look like?: the landing page is a showcase of Plank's open-source work for Laravel developers only, and it lists only the Packages on the Docs Site.
• Set by the User on 2026-09-13 in What must a Package provide to the Docs Site?: Package Docs stay plain GitHub markdown, readable on GitHub and Packagist. The Docs Tooling converts them, and Starlight frontmatter is optional.
• Set by the User on 2026-09-13 in How does a change in a Package deploy its Docs Version?: a Docs Version is built only from its Major Line's highest release, never from the branch head, so a docs-only fix waits for the next release. ADR 0006.
• Set by the User on 2026-09-13 in What moves on the Docs Site, and how does it respect reduced motion?: the Docs Site moves like plank.co, and its reduced-motion controls are plank.co's. On doc pages the theme and reduced motion share one dropdown behind plank.co's accessibility icon, replacing the one-click theme toggle from Does the Docs Site have a dark mode, and what does it look like? there.
• First Packages: plank/snapshots (README only) and plank/publisher (docs/ folder).
• Skills: grilling tickets → grilling + domain-modeling; research → research; prototype → prototype (plus impeccable for visual design).

Decisions so far

• How can a Package's Docs Versions share one path on Cloudflare's free plan?: four serving shapes costed — Worker per Docs Version + a root Worker per Package (Major Lines + 1 Workers per Package, 100/account); one Worker per Package redeploying every Major Line each release (needs a concurrency queue for lockstep releases); router/R2/KV Workers (every request counts toward 100k/day; KV 1k writes/day); R2 alone (payment method, hostname-only domains). Nested route precedence untested.
• How can search span independently deployed sections?: Pagefind bundle per Docs Version merged in the browser (mergeIndex, filters per Package/Docs Version; ~160 KB fixed runtime, publisher's index ≈ 50 KB); new sections become searchable only via a runtime list of sections, and one missing bundle breaks the merge; alternatives are a central combined index (second deploy per release) or other static libraries (no index merging, full index download). The User later ruled out search across Packages (see Out of scope).
• Which static site generator fits per-package, per-Major-Line builds?: seven candidates built on real Package Docs — only MkDocs Material and Zensical took today's markdown unchanged; Starlight/VitePress bring Shiki (blade) and Starlight bundles Pagefind; Eleventy/Hugo give full design freedom but no docs chrome; health costs (MkDocs unmaintained, Zensical alpha, VitePress 2.0 alpha, Starlight pre-1.0); 33–118 files per Docs Version.
• Which static site generator does the Docs Site use?: the User chose Astro Starlight, a ready-made docs UI rather than building our own, over Docusaurus. No React; Starlight's conventions unless there's a good reason to break them. Measured first-load JS was 3.9 KB vs 171.7 KB gzipped. Costs taken on: 0.x breaking minors, required title frontmatter, .md links not rewritten, content in src/content/docs/. ADR 0001.
• Where does the shared build tooling live, and how do Packages use it?: the Docs Tooling lives in plank/docs (made public by the User) as a reusable workflow, which Packages call at a moving @v1 tag; breaking changes ship as v2. Costs: no steps inside the called job, a Package picks up changes only on its next build, and each Major Line branch carries its own copy of the docs workflow. ADR 0002.
• Gather plank.co brand assets and confirm the Klim font licence covers packages.plank.co: the User chose free OFL lookalikes, Newsreader for headings (in place of Gascogne) and Instrument Sans for body (in place of Untitled Sans), so no commercial font licence is relied on. The logos, shape SVGs, icons and colour tokens live in the private plank/plankco repo under themes/plank/assets/. No Figma file was found.
• How do a Pages router and Cloudflare for SaaS behave on Cloudflare's free plan?: a Pages router puts every routed request against 100k/day, and past it fail-open serves only the router project's own files; Worker-to-Worker binding calls are one request, but serving a Docs Version's files through a binding isn't documented. SaaS on Free needs a card on file and a second domain (annual fee); path routes on a custom hostname aren't documented; certificates renew over HTTP with only the CNAME at Namecheap.
• Prove a Pages router can serve a Docs Version's Worker on Cloudflare's free plan: it works. Tested live, a Pages Function forwarded through a Service binding to a Docs Version Worker holding only static files, byte-identical, search included. Every router request counts once against 100k/day (first visit 9, later pages 1–4, first search 9); the Docs Version Worker recorded none. Each Docs Version needs a _headers file for immutable hashed files, and the router a 404.html. The agent recommends the Pages router; the User decides in Confirm packages.plank.co can host the Docs Site.
• Confirm packages.plank.co can host the Docs Site: the User chose the Pages router. packages.plank.co is a CNAME at Namecheap to a Pages project whose Function forwards each Docs Version's path through a Service binding to its own Worker, $0 recurring. Not chosen: whole-site Pages, Cloudflare for SaaS, moving the DNS (kept as the upgrade path to Worker routes), Plank's Dokploy, a new VPS. Accepted: 100k requests/day shared, no rate limiting, a router redeploy per Docs Version. ADR 0003.
• How do the landing page and version switcher learn which Packages and Docs Versions exist?: each Package lists its Major Lines in a Docs Config on main. A router run in plank/docs (at most daily, or by hand) reads it from every public, non-archived plank/* repo with no token, routes Docs Versions both listed and deployed (docs-<repo>-<major> Workers, one binding each, ADR 0003 kept), and writes /versions.json for the landing page and version switchers to read at runtime. It deletes Workers it stops routing; a broken Docs Config keeps that Package as it was; a failed scan stops the run. Paths are repo names; the newest Docs Version is the highest Major Line. Private repos never publish: three guards, carried to How does a change in a Package deploy its Docs Version? ADR 0004.
• What do the landing page and a doc page look like?: the User chose landing page B and doc page A. Landing B is a forest-green band that types composer require plank/<package> for each Package in turn, over tabs that show one Package's summary, code sample and docs link. Doc page A is Starlight restyled toward plank.co, with every Major Line as a segmented control in the header. The landing page is a developer-only showcase of the Docs Site's Packages, two at launch. The prototype is on prototype/landing-and-doc-page.
• What must a Package provide to the Docs Site?: Package Docs stay GitHub markdown, with Starlight frontmatter optional, and the Docs Tooling converts the rest. The Package Docs are docs/ if it exists (docs/README.md is the home page and sets the sidebar), otherwise the root README as one page, trimmed by heading name. Bold-label notes and GitHub alerts become asides. Mermaid renders, with the method left to the builder (the full bundle is ~953 KB gzipped). The Docs Config is .github/docs-config.yml on main: name, summary, optional status, sample (label, code), major-lines as numbers; the Composer name comes from composer.json. ADR 0005.
• How does a change in a Package deploy its Docs Version?: a published GitHub Release (released, so no prereleases) builds its Major Line's Docs Version from the tag, but only if it's that line's highest release; a docs-only fix waits for the next release. The Major Line is the tag's major. A manual run builds any or all listed Major Lines from their highest releases. Builds of one Docs Version queue; a failure leaves the old one live, with GitHub's own notice. Credentials: a minimum-permission Cloudflare token with no end date, and the account ID, as org secrets for selected repos, passed explicitly; the router run's token follows the same rules. Account-wide token scope carried to Which Cloudflare account hosts the Docs Site, and who owns it?. ADR 0006.
• How do already-deployed Docs Versions pick up Docs Tooling changes?: every Docs Tooling release rebuilds every routed Docs Version from its Major Line's highest release, so only the Docs Tooling changes. A workflow in plank/docs uses a GitHub App to start each Package's manual run on that highest release tag. The run builds with the Docs Tooling the tag calls, or with main's run if the tag has no docs workflow, and the Package deploys it in its usual queue. So v2 needs nothing extra. The workflow waits for the runs and fails, naming the rebuilds that failed, so GitHub notifies whoever made the release. Costs: redundant rebuilds of Major Lines on the other major, the 6-hour job limit, and not-yet-routed Docs Versions are skipped. The User also ruled out search across Packages. ADR 0007.
• What happens when the Docs Site nears or passes 100,000 requests a day?: the router fails open, a dashboard toggle set by hand. Past the limit, the landing page and /versions.json stay up, and every docs page gets the router's 404.html with a 404 until 00:00 UTC (inferred). The Cloudflare account's administrators are warned by Cloudflare's own daily-limit emails, and nothing is built. The emails are reported by users at 75%, 90% and 100%, but Cloudflare doesn't document them. Costs: crawlers see 404s that day, and the limit is shared by everything on the account. No ADR.
• Which Cloudflare account hosts the Docs Site, and who owns it?: a Cloudflare account of Plank's that holds only the Docs Site. It's created by a login on a shared Plank mailbox, which is its only member. A named few hold that login, with the password and TOTP in a password manager they share, and the mailbox forwards to them, so Cloudflare's daily-limit emails reach them. Both deploy tokens are account-owned, created and rolled through the shared login. Costs: everything is done as one login, deleting that user deletes the account, and the password manager entry is the boundary. ADR 0008.
• Can a change to Package Docs be seen before it's released?: only in GitHub's own rendering of the changed markdown on the pull request; nothing is built for previews. Costs: the Docs Tooling's conversion (titles, sidebar, README trimming, asides, links, Mermaid, theme) and any build failure are first seen at the Major Line's next release. Facts kept for a later change of mind: no pull request in either Package has come from a fork, Workers preview URLs need preview_urls = true, and Pages previews are unlimited and public by default. No ADR.
• Does the Docs Site have a dark mode, and what does it look like?: yes. The User chose Ink, a near-neutral black (#0f1312) that keeps the brand to the landing page's forest band and coral, over a forest green and a warm dark. Readers switch with a one-click toggle on the landing page and doc pages, in place of Starlight's Dark/Light/Auto select, to save space. Until a click the site follows the system theme; a click is stored under Starlight's key and holds site-wide, with no way back to following the system. The prototype is on prototype/dark-mode. No ADR.
• How does anyone notice when the router run stops working?: whoever GitHub notifies for a scheduled run, which is the user the cron line belongs to. That user is one of the named few: they commit the cron line at the attach step, and the next holder edits it to take it over. Each router run re-enables its own workflow through GitHub's API with the run's own token, so the 60-day switch-off never comes. GitHub doesn't document that, but it's seen working on Silverstripe's repos. A Docs Config that can't be read makes the run fail after it does everything else. Costs: the notice depends on one person's Actions notifications, a deleted account stops the schedule with no notice, and a dropped run sends nothing. ADRs 0004 and 0008 amended.
• What does a maintainer do to put a Package on the Docs Site?: an org owner grants access first, when a maintainer asks by any channel. The grant adds the repo to both org secrets and to the rebuild App, on selected repos only. The maintainer then merges the Docs Config and docs workflow on main, copied from a plank/docs README section, and starts one manual run. The Docs Versions go live with the next router run, or sooner by asking anyone with write on plank/docs. Nobody reviews the landing page text at org level. The manual run skips a Major Line with no release and fails early on empty secrets. The README also covers adding or dropping a Major Line and taking a Package off. No ADR.
• What moves on the Docs Site, and how does it respect reduced motion?: the User chose plank.co's motion in full. On the landing page the headline's words slide up and a coral line draws, the command types each Package in turn (pausing while the reader is on it), the shape turns as the page scrolls, and a "read the docs" circle trails the cursor over the code sample. Doc pages fade their content between pages (View Transitions) and scroll smoothly. Reduced motion stops all of it. The controls are plank.co's: its floating accessibility button on the landing page, and on doc pages one dropdown behind its accessibility icon, holding Theme (Light, Dark) and Motion. That dropdown replaces the one-click theme toggle from Does the Docs Site have a dark mode, and what does it look like? on doc pages. Costs: WCAG 2.2.2 on the cycling command, View Transitions and scroll-driven animation missing or partial in Firefox, and two clicks to change theme on doc pages. No ADR.
• How do readers get between Packages and Docs Versions, and what do they get at a missing page?: readers get between Packages only through the landing page. The version switcher goes to the same page in the other Docs Version, and a missing page gets that Docs Version's own 404 page, which links to its home. At an unrouted <number>.x of a Package on the site, the router serves a "docs expired" page at the original URL ("expired" below the lowest routed Major Line, neutral wording otherwise), linking to the newest Docs Version and the repo on GitHub. Everything else, including a renamed repo's old path, gets 404.html, which reads /versions.json to tell a day over the limit ("unavailable until 00:00 UTC") from not found. Links to other Packages stay as written, relative links outside the Package Docs go to GitHub at the release tag, and broken links are reported without failing the build. ADR 0005 amended.
• How do code blocks look, and which syntax theme do they use?: the User chose A · Sand card. Code blocks keep Starlight's Expressive Code frames (file tabs, terminal windows, copy on hover), on plank.co's sand in light and Ink's code colour in dark, with a coral line on the active file tab. Syntax colours are Plank light and dark themes drawn from plank.co's teal, coral, blue and yellow, also used for the landing page's samples, in place of vitesse. Not chosen: a forest slab, and an open ruled figure with GitHub's themes. Costs: a first-line file-name comment leaves the code and becomes the title (Blade's aren't moved), and Expressive Code raises token colours to 5.5:1. The prototype is on prototype/code-blocks. No ADR.
• How do search engines see the Docs Site's Docs Versions?: only each Package's newest Docs Version is indexed. The router adds noindex to older Docs Versions, and every page keeps Starlight's canonical to itself. /<package>/ stays a 302. The router run writes a root /sitemap-index.xml, named in robots.txt, that lists the landing page and each newest Docs Version's sitemap-0.xml. The site is registered with Google Search Console and Bing under the shared login, verified by a file the router ships, and the index is submitted once at the attach step. The router adds noindex on every hostname but packages.plank.co, covering the stand-ins and Plank's own pages.dev copy. Fail open's 404s stay. Costs: pages only in older Docs Versions can't be found by search, none of the sites checked works this way, and Google may drop pages it crawls on a day over the limit, since a static Pages file can't return a 503. ADR 0004 amended.
• How does the Docs Site move from the stand-ins to Plank's account, domain and Package repos?: there are no stand-ins. The Docs Site is built in the open on Plank's Cloudflare account and plank/docs from the start, seen at plank-packages.pages.dev with site already https://packages.plank.co, so going live rebuilds nothing. Two throwaway test Packages, plank/docs-test-readme and plank/docs-test-folder (1.x to 3.x), prove what can't be done to a real Package; snapshots and publisher are onboarded after them, by the README guide, with manual runs only. The spec carries a go-live checklist, including removing the lowest, a middle and the highest Major Line. When it has passed and the User says go, one of the named few takes over the cron line, the test Packages are deleted, and the domain is added in Pages, then the CNAME at Namecheap. The shared mailbox is docs@plank.co; Search Console and Bing use Plank's existing plank.co accounts. Costs: the work in progress is public (with noindex) at the pages.dev address, and everyone is needed from day one. ADRs 0004 and 0008 amended.

Not yet specified

Nothing: every patch graduated to a ticket on 2026-09-13.

Out of scope

• Writing or migrating Package Docs — this effort is the infrastructure only.
• plank/laravel-mediable and plank/laravel-metable (Sphinx .rst on Read the Docs), and .rst support — follow-up once the pipeline is proven on snapshots and publisher.
• Docs per release tag — the User chose one Docs Version per Major Line.
• Search across Packages — ruled out by the User on 2026-09-13 in How do already-deployed Docs Versions pick up Docs Tooling changes?: "It makes ZERO sense as a feature." Search across Docs Versions was already not needed (2026-09-11).
• Anything with a recurring cost or a third-party runtime service.
• Trying a Docs Tooling change before its release rebuilds every Docs Version, once the Docs Site is live — ruled out by the User on 2026-09-13 in How does the Docs Site move from the stand-ins to Plank's account, domain and Package repos?: "a future concern for when that situation arises."