Biluo

Biluo (碧落) is an open-source blog theme built with Astro 7 that outputs a static site for deployment to Cloudflare Workers Static Assets, using Markdown/MDX content collections, Pagefind search, Giscus comments, and a tree-structured series system.

What is Biluo?

Biluo is a blog theme for Astro 7 that compiles Markdown and MDX content collections into a fully static website. It generates RSS with a styled XSL view, sitemap, robots.txt, llms.txt, a custom 404 page, and includes features like dark mode, Pagefind search, and Giscus comments. The theme is designed to be deployed via the Cloudflare Workers Static Assets integration using wrangler, and its code is MIT licensed.

Key Features

• Full-text search — Pagefind builds a client-side search index during pnpm build, so no external search service is needed.
• Comments via Giscus — GitHub-discussion-powered comments are implemented in src/data/comments.ts, where the provider can be swapped; comments are off by default.
• Dark and light themes — A water-blue light palette and night-sky-blue dark palette are toggled by a circular reveal animation.
• Series and taxonomy — A tree-structured series system lives in src/data/series.ts with logic in src/lib/series.ts, and tags support nested groups via src/data/taxonomy.ts.
• SEO and crawlability — The site outputs RSS, sitemap, robots.txt, llms.txt, and has a hero image fallback plus an og:image fallback to the post header.
• Reading experience — GitHub-alert callouts, localized footnote labels, heading anchors, code-block copy buttons, click-to-zoom images, reading-time estimates, table of contents, and related posts.

Who is it for?

Biluo is for developers who want a self-contained, fast blog without a CMS. It suits Astro users comfortable editing TypeScript data files and the astro.config.mjs pipeline. It is also well matched for Cloudflare Workers users who prefer Workers Static Assets over Pages, since wrangler.jsonc ships preconfigured.

What can you do with Biluo?

• Publish a personal blog — Write posts as Markdown or MDX files in src/content/blog and run pnpm build to generate the static site.
• Deploy to Cloudflare Workers — Run pnpm deploy to build and publish with wrangler; the repository includes a wrangler.jsonc configuration for static assets.
• Organize long-form content — Use the series data model to arrange posts into tree-structured sequences and grouped tag pages.
• Localize a site — Change siteLocale and defaultLang in src/i18n/ui.ts to switch from the default Traditional Chinese to English, with all UI strings centralized.

How does Biluo work?

The README's quick-start table lists five commands: pnpm install, pnpm dev (local server on localhost:4321), pnpm build (outputs to dist and runs Pagefind), pnpm preview (serves dist with wrangler dev on localhost:8787), and pnpm deploy. Configuration is file-based: site settings in src/consts.ts, post contents in src/content/blog, series in src/data/series.ts, tags in src/data/taxonomy.ts, blogroll in src/data/blogroll.ts, comments in src/data/comments.ts, and UI strings in src/i18n/ui.ts.

FAQ

Is Biluo free?

The theme source code is released under the MIT license, so it is free to use and modify. Bundled fonts are under the SIL Open Font License 1.1, and any content you add to the theme is yours.

What are Biluo's system requirements?

Biluo requires Node.js 22 or later and uses pnpm as the package manager. In non-interactive environments such as CI, you should run CI=true pnpm build because pnpm 11 otherwise blocks on an interactive prompt.

Does Biluo support multiple languages?

Biluo is i18n-ready but single-locale by design. All UI strings are collected in src/i18n/ui.ts, and the shipped default is Traditional Chinese. You can change defaultLang and siteLocale to run an English-first site, but there is no per-post language switcher.

Can I use a different comment provider?

Yes. The Giscus integration is defined in src/data/comments.ts, and the file documents how to swap in another provider. Comments are disabled by default.

Why is search empty when I run pnpm dev?

Pagefind builds its index during pnpm build, so in development mode with pnpm dev there is no search index. The documentation in docs/en/search.md explains the indexing behavior in detail.