Deployment

Deploy static docs to any host, or switch to server rendering with an adapter.

Deploy anywhere (static)

blume build compiles your docs to plain HTML, CSS, and a local search index in dist/. There’s no server to run — point any static host at the folder.

These settings work on Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon S3 + CloudFront, or any bucket or CDN. Make sure blume is a dependency so the host can run the build.

A static build includes:

• every docs and custom page as static HTML
• a local search index (Orama by default, Pagefind opt-in)
• a sitemap.xml and robots.txt when deployment.site is set
• llms.txt and llms-full.txt for AI tools
• redirect pages
• prerendered Open Graph images when seo.og.enabled is on

Set your site URL

Sitemaps, canonical tags, RSS, and Open Graph images need an absolute origin. On Vercel, Netlify, and Cloudflare Pages, Blume detects it from the platform’s environment at build time — no config required.

Set deployment.site to override the detected value, or to provide one on hosts that don’t expose it (GitHub Pages, S3, a custom CDN):

deployment: {
  site: "https://docs.example.com",
}

When detecting automatically, Blume prefers your stable production domain over per-deploy preview URLs, so the canonical origin stays put across deploys.

During blume dev, the site URL falls back to your local dev server (e.g. http://localhost:4321) when none is set, so site-gated features — Open Graph images, canonicals, the sitemap — work out of the box. Builds never use this fallback, so production output is never pointed at localhost.

Preview locally

Before you ship, preview the production build exactly as a static host would serve it:

blume build
blume preview

Subpath deploys

Serving docs under a path like example.com/docs? Set deployment.base — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it.

deployment: {
  base: "/docs",
}

Mount the docs under a path

basePath mounts every generated route under a segment (/docs/getting-started) while leaving the sidebar untouched — the top level is your sections, not a wrapper group. Use it when the docs live at /docs/* but the site root stays yours (like Docusaurus routeBasePath or Fumadocs baseUrl).

basePath: "/docs",

Write links as if mounted at root (/getting-started); Blume rewrites them, along with redirects, the sitemap, canonical URLs, Open Graph images, llms.txt, and the search index. Public assets (images, files under public/) stay at the site root.

This is a distinct concept from the two paths above:

• A per-source prefix namespaces one source and does add a sidebar group.
• deployment.base is the host subdirectory the whole app is served from. The two compose — with both set, a page lands at {deployment.base}/{basePath}/page.

Server rendering

Static output covers most docs. Switch to server output when you need request-time features — most notably the Ask AI endpoint:

deployment: {
  output: "server",
  adapter: "vercel",
}

Choosing an adapter pulls in the matching Astro adapter automatically:

On Vercel, Netlify, and Cloudflare Pages, Blume picks the matching adapter automatically for server output — set output: "server" and deploy. Set adapter explicitly to override the detected value, or when self-hosting with node.

A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The node adapter produces a standalone server you can run directly.

Redirects

Map old URLs to new ones in blume.config.ts:

redirects: [{ from: "/old", to: "/new", status: 301 }];

status accepts 301, 302, 307, or 308 (default 301). Server builds handle redirects at request time. Static builds emit redirect pages and platform files so your host issues a real HTTP redirect: _redirects (Netlify, Cloudflare Pages), vercel.json (Vercel), and blume-redirects.json — a structured manifest for anything else (nginx/Apache rules, an edge worker). A _redirects or vercel.json you ship in public/ is left untouched.

Environment variables

When a feature needs a runtime secret, Blume warns at blume dev/build if it’s missing — so the problem surfaces early instead of at the first request:

Set them in .env.local for local dev and in your host’s environment for production. Build-time secrets for search-index sync (Algolia, Orama Cloud, Typesense) are warned about separately during the sync step.

Build summary

Every build prints a summary — output mode, adapter, resolved site URL, search provider, redirect count, sitemap and llms.txt status, and any enabled server features — so you can confirm what shipped (including anything auto-detected) before you deploy.