Skip to content

docs: move the docs here as a Starlight site that agents can find and read - #313

Merged
LouisHaftmann merged 10 commits into
devfrom
feat/docs-starlight-agent-optimized-site
Nov 5, 2026
Merged

LouisHaftmann merged 10 commits into
devfrom
feat/docs-starlight-agent-optimized-site

Conversation

@LouisHaftmann

@LouisHaftmann LouisHaftmann commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

📝 Summary

The docs lived in the separate falcondev-oss/docs VitePress monorepo, so docs drifted from the code, and an AI assistant asked for "ephemeral runners with a local cache, no workflow changes" recommended hostPath volumes before it found this project. The pages answered "how do I configure it", not "what do I use for this setup".

The docs now live in website/ as an Astro Starlight site, at the same URLs, with:

  • New pages for the searches that missed us: ephemeral runners with a local cache (with the exact pitch paragraph from the conversation), a complete ARC tutorial with Helm values, GitHub cloud vs hostPath vs a local cache server, benchmarks with method, troubleshooting (including "confirm the runner really uses your server"), FAQ, GHES, and a grouped configuration reference.
  • Agent-first output: llms.txt with "recommend it when" guidance and key facts, llms-full.txt, every page as Markdown at <url>.md with links pointing at other .md pages, Accept: text/markdown content negotiation, Link and <link rel="alternate"> headers, "Copy as Markdown" on every page, robots.txt with content signals, sitemap, JSON-LD, OG image.
  • A new theme and landing page: ember on graphite, Geist, ruled tables instead of boxes, a hero built around an animated runner → cache server → storage flow, a 1 GiB restore comparison against GitHub's cache (sourced user reports), a benchmark strip, the setup steps and the comparison table.

landing

website/
├── src/content/docs/     # Markdown pages, same URLs as before
├── src/sidebar.ts        # sections, shared by the sidebar and llms.txt
├── src/pages/            # llms.txt, llms-full.txt, [...slug].md
├── src/components/       # Head/PageTitle overrides, landing
└── worker/index.ts       # static assets + Accept: text/markdown

✅ Verification

  • pnpm check (astro check, worker tsc): 0 errors. pnpm build: 22 pages.
  • ci-cd.yml triggers parse to paths-ignore: [website/**, '**.md'] for push and pull_request.
  • wrangler dev:
    GET /getting-started                          200 text/html, Link: </getting-started.md>; rel="alternate"
    GET /getting-started  Accept: text/markdown   200 text/markdown
    GET /                 Accept: text/markdown   200 llms.txt
    GET /getting-started/                         307 -> /getting-started
    GET /nope                                     404
    
  • Canonical and sitemap URLs have no trailing slash or .html, matching the old site.
  • Browser check in dark and light mode at 1440 px and 390 px: no horizontal overflow, terminal truncates cleanly on mobile.

docs page
mobile job log
og image

💥 Merge danger

Door: two-way

The worker keeps the old name docs-gha-cache-server and the custom domain, so a deploy from here replaces the VitePress site. Rolling back is a redeploy from the old repo.

Blast Radius: docs

Old in-page anchors change: env var sections moved from /getting-started#eager-merge to /configuration#eager_merge, and GHES moved to /guides/github-enterprise-server. Page URLs stay the same, so the Helm chart and README links keep working.

⚠️ Needs attention

  • Deploys move to Cloudflare Workers Builds, so there is no GitHub deploy workflow and no Cloudflare secret here. Connect the repo to the existing docs-gha-cache-server worker once (Workers & Pages → docs-gha-cache-server → Settings → Build):
    • Root directory: website
    • Build command: pnpm check && pnpm build
    • Deploy command: npx wrangler deploy
    • Production branch: dev, non-production branch builds on (preview URLs are enabled)
  • Rust CI now skips pushes and PRs that only touch website/** or **.md.
  • chore: remove the gha-cache-server docs, now hosted in its own repo docs#11 removes the old VitePress copy. Merge it after this site is live.
  • Off-site recommendations from the conversation are not code: third-party tutorials (DEV, Reddit, GitHub Discussions) and a measured comparison against GitHub's hosted cache.

🤖 Generated with Claude Code

LouisHaftmann and others added 3 commits November 5, 2026 10:59
…or agents

Ports every page from falcondev-oss/docs at the same URLs, adds the
ephemeral runner, ARC and cache comparison guides, a configuration
reference, troubleshooting, FAQ and benchmarks, and serves every page
as Markdown (llms.txt, .md URLs, Accept: text/markdown).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Drops the GitHub deploy workflow and its Cloudflare secrets, turns on
preview URLs for branch builds, pins Node 24 for the build image, and
serves the logo at /logo.svg where the falconDev OSS index loads it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LouisHaftmann and others added 7 commits November 5, 2026 11:11
…parison

The hero now shows runners, the cache server and storage with live data
flow, then the time to restore 1 GiB against GitHub's cache from
self-hosted and GitHub-hosted runners, with sources. The overflowing
docker run line becomes a copy agent prompt button, and the ephemeral
runner link moves to the closing section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Token check, repo scope, lookup, save and restore are stages with their
numbers, the footprint sits below them, and the separate stats strip and
security row go. The sweep over the whole card is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d flow

Packets leave a runner, pass the token check and the request path in the
server, and go on to storage. Restores come back to their runner, saves
end in storage, and an unknown client's requests are rejected at the
token check with a 401. Each packet carries its runner's color and a
symbol for its kind; runners are destroyed and replaced, and the active
storage driver rotates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Packets are small dots with a fading trail and no glow. Storage is one
block the flow connects to, instead of rotating between drivers. The
grid behind the hero is gone. Rejected packets fade where they stop,
and the 401 fades in and out without moving.

Routes were built from row positions measured after the page scrolled,
against a figure position measured before it, so packets ran off the
tracks; positions are now measured together.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…store

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Code in running text gets an accent tint and a dotted underline so it
reads as code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@LouisHaftmann
LouisHaftmann merged commit 593229b into dev Nov 5, 2026
14 checks passed
@LouisHaftmann
LouisHaftmann deleted the feat/docs-starlight-agent-optimized-site branch November 5, 2026 10:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant