Contributing Code
Working on the Bifrost theme, build pipelines, CI, and deploy chain for the Wheel of Heaven sites.
For people writing or modifying the code that turns the content repos into deployed sites. The reading site, the JSON API, the asset CDN, and this docs site are all Zola-built; the reading site is themed by Bifrost; image and video pipelines are Python.
Most contributors only touch one or two of these#
| If you’re working on… | Start here |
|---|---|
| Setting up the multi-repo dev environment | Local Setup |
| Templates, SCSS, shortcodes (Bifrost) | Bifrost Theme |
| Image processing, build pipeline, content validation | Pipelines |
| Per-page Open Graph cards (social unfurls) | OG Image Pipeline |
| Auto-posting new content to Telegram, Bluesky, etc. | Social Broadcast Pipeline |
| Splitting long library-book paragraphs across languages | Paragraph Split Tooling |
| Generating ElevenLabs audio plays for library books | Audio Play Pipeline |
| Scaffolding scenes / SFX / pauses for a full-featured audio play | Audio Play Cue Sheets |
| Rendering cinematic-audiobook videos (web view + YouTube MP4) | Cinematic Audiobook |
| Publishing videos to YouTube / video platforms + channel branding | Video Channels & Publishing |
| Cloudflare Pages, DNS, headers, redirects | CI & Deploy |
If you’re starting cold, Local Setup is the dependable entry point — it covers cloning each repo with the right submodule flags, installing tools via mise, and running the dev server.
Bigger picture#
Before touching code, the Architecture Overview is worth ten minutes — it explains the submodule relationships, why the API and www share content, and where things sit in the build chain.
A few cross-cutting conventions#
These apply across all the per-page guides below.
- Submodules use SSH except when CI needs them.
.gitmodulesentries that Cloudflare Pages must clone (bifrost) use HTTPS; the rest use SSH. See Conventions. - Zola version is pinned in
mise.toml. Each site repo also pins Zola in its Cloudflare Pages build command. When bumping, update both. - The build environment is Zola-only. CF Pages downloads the Zola binary at build time via curl; no Rust toolchain on the runner. Build commands all follow the same shape — see CI & Deploy.
- Local Setup Full local dev environment — Zola, mise, submodules, the data repos, and validation scripts.
- Bifrost Theme The multilingual reading theme — templates, shortcodes, SCSS architecture, and how to extend it.
- Pipelines The build, content, and image pipelines — how raw inputs become deployable sites.
- Open Graph Image Pipeline How per-page social-card JPEGs are rendered, synced, and served — inputs, outputs, scripts, guardrails, and the operational loop.
- Dataset Distribution How the CC0 datasets are packaged and mirrored to HuggingFace and Kaggle — the build_distribution.py packager, the upload flow, and how to update a mirror.
- CI & Deploy Cloudflare Pages projects, custom domains, headers, redirects, and the build webhook chain.
- Paragraph Split Tooling How to split long source-text paragraphs into smaller pieces across all 9 languages — the SPLITS dict, the FR-anchor heuristic, and the operational loop.
- Social Broadcast Pipeline How newly published Wheel of Heaven content auto-posts to Telegram, Twitter/X, Bluesky, and (eventually) Mastodon, Discord — frontmatter contract, state model, CI trigger, guardrails.
- Audio Play Pipeline ElevenLabs-driven audio play generation: from TTS sidecars + lexicon + voice config to per-chapter MP3s on the assets CDN.
- Audio Play Cue Sheets How audio production directives (scenes, SFX, pauses, voice tweaks) are scaffolded outside the source-text chapter JSONs so audio plays can iterate without polluting the library content.
- Cinematic Audiobook The cinematic view + YouTube video export: one timeline model, two renderers (web + ffmpeg), built on top of the audio-play pipeline.
- Video Channels & Publishing How rendered cinematic-audiobook videos get published: the video-channels catalog repo, per-language platform accounts, channel branding (avatars + banners), and the metadata/description conventions.