demo-astro-r2

GraphQL-Markdown + Cloudflare R2 demo

Live demo: https://demo-astro-r2.edno.workers.dev/

A demo of GraphQL-Markdown’s outputAdapter setting: generated documentation is written straight into a Cloudflare R2 bucket instead of the local filesystem, and an Astro/Starlight site reads it back out of the bucket through a custom content loader.

No generated file ever touches the filesystem — not on the way in, not on the way out.

   npm run doc                        R2 bucket                    npm run build
┌────────────────┐  outputAdapter  ┌──────────────┐ content loader ┌───────────┐
│ GraphQL schema │ ──────────────▶ │ **/*.mdx     │ ─────────────▶ │ Starlight │
└────────────────┘                 └──────────────┘                └───────────┘

Both ends run under Node: generation through Wrangler’s getPlatformProxy(), the build through the same binding. Locally that is Wrangler’s R2 emulation, so the whole demo runs with no Cloudflare account.

🚀 Project structure

.
├── assets/
│   └── index.mdx                  # homepage template → index.mdx
├── src/
│   ├── content.config.ts          # points Starlight's docs collection at R2
│   ├── lib/
│   │   ├── docs-layout.ts         # names shared by generation and verification
│   │   ├── r2-output-adapter.ts   # ← the output adapter (generation)
│   │   ├── r2-docs-loader.ts      # ← the content loader (build)
│   │   └── formatter.ts           # the Starlight preset, with overrides
│   ├── assets/                    # the project mark, light and dark variants
│   ├── components/
│   │   ├── Footer.astro           # Starlight's footer, crediting GraphQL-Markdown
│   │   └── PageTitle.astro        # adds breadcrumbs above the title
│   └── styles/custom.css          # theme tweaks (Starlight `customCss`)
├── public/favicon.svg             # the project mark
├── astro.config.ts
├── graphql.config.ts              # wires the adapter into GraphQL-Markdown
├── scripts/
│   ├── generate-docs.ts           # runs the generator, then releases the binding
│   └── verify-docs.ts             # asserts the bucket actually holds the pages
├── package.json
└── wrangler.jsonc                 # the DOCS R2 binding

How the pieces fit

Generation (npm run doc) runs under Node. graphql.config.ts gets the R2 binding through Wrangler’s getPlatformProxy() and hands it to r2OutputAdapter(), which implements the three methods the renderer expects:

Method What it does here
writeFile bucket.put() the page
readFile bucket.get(), returning undefined when the object is absent
ensureDir on --force, deletes every object under the prefix so pages for types dropped from the schema do not linger

Object keys are the paths the filesystem writer would have used, relative to rootPath: docs/types/objects/user.mdx becomes the key types/objects/user.mdx.

npm run doc goes through scripts/generate-docs.ts rather than calling gqlmd graphql-to-doc directly. The two generate identical output, but the binding keeps a workerd process alive and nothing inside a config file can tell when generation has finished — so the script runs the generator and then releases it. Calling gqlmd directly works, it just will not exit on its own.

Rendering is Starlight’s. src/content.config.ts replaces Starlight’s docsLoader() — which reads src/content/docs off disk — with r2DocsLoader(), which lists the bucket and stages each page for Astro to compile. Entry ids are the keys minus .mdx, so types/objects/user.mdx becomes the route /types/objects/user, which is exactly what the links inside the generated pages point at.

This is a build-time read. Starlight prerenders every page, so regenerating the documentation reaches the site through a rebuild and deploy — the docs.yml workflow does both.

MDX. The demo uses the Starlight formatter, so pages arrive as MDX importing <Badge> and <Aside> from @astrojs/starlight/components. MDX needs a compiler, and Astro reaches it through a Vite import of a real file, so the loader stages each page under src/content/docs/ and marks the entry deferredRender rather than calling renderMarkdown(). It has to be that directory specifically: Starlight derives the sidebar and autogenerate matching from entry.filePath relative to its own collection path, so staging anywhere else builds fine but leaves the sidebar empty. The directory is a build artefact — gitignored, and rewritten from the bucket on every load.

Extending a preset. formatter is a module path, so a preset can be extended by re-exporting it and replacing the parts you want.

The Starlight preset already renders badges and admonitions as Starlight’s own <Badge> and <Aside> components. What it inherits from the shared defaults is generic HTML carrying gqlmd-mdx-* classes, which only looks right if the site ships CSS for those classes. src/lib/formatter.ts overrides those to emit elements Starlight already styles, so the markup needs no CSS to compensate — what the generated content looks like is decided by the formatter, not patched afterwards. (src/styles/custom.css is for theme tweaks that belong to the site, such as the heading scale, not to the content.)

export * from "@graphql-markdown/formatters/starlight";

/** ` · ` instead of the default ` ● `, as text rather than a styled span. */
export const formatMDXBullet = (text = "") => `&nbsp;·&nbsp;${text}`;

/** `Parent.field` as inline code, which Starlight styles. */
export const formatMDXNameEntity = (name, parentType) =>
  `<code>${parentType ? `${parentType}.` : ""}${name}</code>`;

// `createMDXFormatter` takes precedence over individual exports, so the
// overrides have to go through it too.
export const createMDXFormatter = (meta) => ({
  ...createStarlightFormatter(meta),
  formatMDXBullet,
  formatMDXNameEntity,
  formatMDXDetails,
});

astro-breadcrumbs builds the trail from Astro.url.pathname, which is the object key minus .mdx, so it needs nothing threaded through from the loader. It is rendered from a PageTitle override.

Two settings are worth noting. The intermediate segments are groupings rather than pages — /types/objects/user exists, /types/objects does not — so their href is dropped and they render as plain text. The BreadcrumbList JSON-LD goes with them (schemaJsonScript={false}): it builds absolute URLs from every crumb, so it both breaks on a crumb without one and would otherwise publish structured data pointing at pages that do not exist.

🧞 Commands

All commands are run from the root of the project, from a terminal:

Command Action
npm install Installs dependencies
npm run doc Generates documentation from the schema into R2
npm run doc:force Same, emptying the bucket first (--force)
npm run doc:verify Checks that the bucket actually holds a complete set of pages
npm run check Regenerates binding types and type-checks the project
npm run dev Starts the Astro dev server at localhost:4321
npm run build Builds the Worker to ./dist/
npm run preview Serves the built Worker locally with Wrangler
npm run deploy Builds and deploys to Cloudflare Workers

🏎️ Running the demo locally

Everything runs offline against Wrangler’s local R2 emulation — no Cloudflare account, no bucket, no credentials.

# 1. install this demo
npm install

# 2. generate the documentation into the local bucket (.wrangler/state)
npm run doc

# 3. serve it
npm run dev          # http://localhost:4321

Step 1 is a one-off. After that:

To… Run
Regenerate after a schema or config change npm run doc
Regenerate from scratch, dropping stale pages npm run doc:force
Confirm the bucket holds a full set of pages npm run doc:verify
Serve with hot reload npm run dev
Serve the built Worker, as deployed npm run build && npm run preview
Type-check npm run check

npm run dev and npm run build both read the same local bucket that npm run doc wrote to. Because the pages are prerendered, regenerating means rebuilding: restart npm run dev, or run npm run build again.

🧑‍🚀 Edit graphql.config.ts to try with your own GraphQL schema.

Troubleshooting

The build produces only a 404 page. The bucket is empty — run npm run doc first. Check with npm run doc:verify, which should report 35 objects.

The sidebar is empty. The staged pages are not under src/content/docs/. Starlight matches autogenerate directories against entry.filePath relative to its collection path.

No such module "chunks/..." when prerendering. The staging directory name must not start with a dot — it breaks the emitted chunk name.

format is not a function during generation. @graphql-markdown/formatters is missing. It supplies the default renderers even when no formatter is set.

gqlmd graphql-to-doc never exits. Expected — use npm run doc, which releases the R2 binding once generation is done. See above.

The bucket looks stale. npm run doc and wrangler dev share .wrangler/state; stop the dev server, regenerate, then start it again.

Using a real bucket

To generate into R2 proper rather than the local emulation:

npx wrangler login
npx wrangler r2 bucket create graphql-markdown-demo-docs

wrangler.jsonc already declares a remote environment whose DOCS binding is marked "remote": true. Select it with WRANGLER_ENV to generate into the real bucket:

WRANGLER_ENV=remote npm run doc
WRANGLER_ENV=remote npm run doc:verify

Leave WRANGLER_ENV unset and everything stays local.

☁️ Deploying

npx wrangler login
WRANGLER_ENV=remote npm run doc   # populate the bucket
WRANGLER_ENV=remote npm run deploy

🤖 CI/CD

Three workflows:

Workflow Trigger What it does
ci.yml pull requests, and called by deploy.yml Generates against Wrangler’s local R2 emulation, verifies it, then type-checks and builds — no bucket, no account, no secrets
deploy.yml push to main, manual Runs ci.yml as a gate, then verifies the bucket, builds from it and deploys
docs.yml manual Regenerates into the real bucket with WRANGLER_ENV=remote, verifies, then builds and deploys

deploy.yml calls ci.yml rather than letting it trigger on the same push: run as two workflows they go in parallel, and nothing stops a commit that fails the checks from shipping — the deploy’s own npm run build catches a broken build, but astro build only strips types, so astro check has to be a gate in front of it rather than a race beside it.

Two things docs.yml has to be careful about:

deploy.yml verifies the bucket for the second of those reasons: the shared r2-bucket concurrency group keeps the two workflows from overlapping, but a docs run that has already failed leaves the bucket partial, and a later push to main would otherwise build from it, succeed with pages missing, and publish that. Only the deploy job holds the group, so the checks in front of it do not keep docs.yml queued.

Token permissions

Both tokens need Workers Scripts: Edit, which is less obvious than it sounds. Writing through a remote: true binding does not talk to R2 directly: getPlatformProxy() opens a Workers edge-preview session and proxies the binding through it, so the call that authenticates is /accounts/<id>/workers/subdomain/edge-preview, not an R2 endpoint. A token holding only Workers R2 Storage fails there with RemoteSessionAuthenticationError before it ever reaches the bucket.

Secret Used by Permissions
CLOUDFLARE_API_TOKEN deploy.yml (verify, build, deploy) and the deploy step of docs.yml Workers Scripts: Edit + Workers R2 Storage: Read
CLOUDFLARE_R2_API_TOKEN docs.yml (generate, verify, build) Workers Scripts: Edit + Workers R2 Storage: Edit
CLOUDFLARE_ACCOUNT_ID both not a credential — it appears in every dashboard URL

So the second token is only narrower in its R2 scope, which you can still limit to this one bucket. It is not a lower-privilege token overall: Workers Scripts: Edit lets it deploy Workers too. Keep the split if you want the bucket restriction, but do not rely on it as a privilege boundary.

Because the loader reads R2 at build time, every workflow that builds needs read access to the bucket, and a regeneration only reaches the site once docs.yml has redeployed.

👀 Want to learn more?