Building from source
Build Bloxwap Font from its skeleton source with Python and fontmake, and work on this website.
Repository layout
apps/docs/ this website (Fumadocs + Next.js, static export)
packages/font/ the type design: glyph skeleton code (tools/bwfont/), build tools (tools/),
generated sources/ and build/, and the distributable fonts/The repository is a Bun workspace. Everything runs from the root with bun run:
| Command | What it does |
|---|---|
bun install | Install the website's dependencies |
bun run fonts:setup | Create packages/font/.venv (Python 3.12, via uv) with the font toolchain |
bun run fonts:build | Build every family; bun run fonts:build sans mono builds selected ones |
bun run fonts:web | Re-package existing builds for the website (web fonts, zips, stylesheet, data) |
bun run fonts:check | Glyph checks: master compatibility and folded strokes |
bun run fonts:qa | OpenType Sanitizer on every file, glyph counts, Hyperglot languages |
bun run docs:dev | Website development server on localhost:3904 |
bun run docs:build | Static export to apps/docs/out |
bun run docs:preview | Serve the export the way GitHub Pages will |
bun run docs:data | Regenerate the website data from the built fonts |
bun run docs:check | Type-check the website |
Building the fonts
bun run fonts:setup
bun run fonts:build # every family in the catalog
bun run fonts:build sans # one family
bun run fonts:build sans-kr mono-kr
bun run fonts:build sans-hebrew mono-hebrew sans-armenian mono-armenian sans-georgian mono-georgianFamilies are defined in packages/font/tools/bwfont/families.py.
Pipeline
Generate sources. tools/generate.py runs the glyph skeleton code in tools/bwfont/ and writes UFO masters and designspaces to sources/<id>/ (paths relative to packages/font).
Compile. fontmake builds the variable fonts, then tools/make_instances.py and fontmake build the static instances (OTF and TTF) in parallel, into build/<id>/. tools/build_pool.py shares one pool across generation and compilation for every requested family. JOBS defaults to the CPU count (nproc on Linux, sysctl -n hw.ncpu on macOS); use JOBS=4 bun run fonts:build pixel to set a smaller limit for available memory. Work starts with SC, JP and KR, followed by other companions and then Sans, Mono and Pixel. The build reports max concurrency: N (JOBS=J).
Post-process. tools/postprocess.py hints the static TTFs, converts to WOFF2 and WOFF, and writes the distribution to fonts/<PS>/{variable,otf,ttf,woff2,woff}/. It then packages the website copies into apps/docs/public/: zips in downloads/ (one per family plus Bloxwap-Fonts.zip with the core Sans, Mono and Pixel families), variable WOFF2 web fonts in fonts/<PS>/variable/, OFL.txt, and the combined stylesheet bloxwap-font.css plus apps/docs/lib/font-version.ts (a content hash used for cache-busting), via tools/webfonts.py.
Pin static sources. Static WOFF2s stay in the dist and release zips and are not committed or hosted by Pages. Download lists serve variable WOFF2s directly and link to each family zip for static WOFF2 and WOFF. Before releasing rebuilt fonts, pin the upcoming release:
packages/font/.venv/bin/python packages/npm/scripts/static_sources.py lock --tag v0.1.3This reads all local family zips from apps/docs/public/downloads/ and writes packages/npm/static-sources.json with the release tag, zip SHA-256 and each static WOFF2 path and SHA-256. Commit the lock with rebuilt variable fonts and regenerated site data. The release script verifies that the local ZIPs reproduce the committed lock before uploading. Update apps/docs/lib/release-version.ts to the same release tag. Publish the pinned assets before npm builds that lack dist inputs; keep those assets immutable once the lock is committed.
Native packaging verifies local packages/font/fonts/<PS>/woff2/ inputs first, then downloads only missing families from the pinned public release. Hash mismatches fail with the affected path. static_sources.py fetch can prepare the sources ahead of a build. Verified zips live in ~/.cache/bloxwap-font/static-sources/<tag>/; BLOXWAP_STATIC_SOURCES_CACHE overrides the cache root. CI downloads into job-local storage without saving a GitHub cache. Native TTF bytes and source hashes are unchanged; manifest source records the zip path and release tag.
Site data regeneration preserves the previous dist format inventory and release zip metadata when local dist files or zips are absent, while rebuilding the hosted variable file list.
Release. The distribution (fonts/) and the zips (apps/docs/public/downloads/) are build output and are not committed. bun run fonts:release uploads the zips to a GitHub Release tagged with the font version (for example v1.000), and the website's Download buttons link to a pinned releases/download/<tag>/<name>.zip URL. The variable web fonts, stylesheet and site data in apps/docs/public/ are committed, because the website build uses them as they are.
Site data. tools/site_data.py reads the fonts and writes apps/docs/public/data/<id>.json (axes, instances, features, Hyperglot languages, script coverage) and <id>.glyphs.json, plus index.json and languages.json. Post-processing passes --only for each rebuilt family, preserving other families' summaries. Running bun run docs:data directly refreshes every available family. Families are analyzed in a process pool; SITE_DATA_JOBS overrides its CPU-count default. Successful Hyperglot results are cached in the ignored packages/font/.hyperglot-cache/ directory by font SHA-256 and Hyperglot version. Delete that directory to force fresh analysis. The website reads these files at build time, so every number on it comes from the fonts.
Design tools
Run these in packages/font:
.venv/bin/python tools/check_glyphs.py [module] # master compatibility; must report 0 problems
.venv/bin/python tools/check_cusps.py [module] # folded / flipping strokes; must report 0
.venv/bin/python tools/dev_preview.py out.png "Hamburg" --stems 22,84,180
.venv/bin/python tools/dev_preview.py out.png --outline A --stems 84 # big view with points
.venv/bin/python tools/han_check.py --sheet out.png --chars 明想林河 # Chinese components
.venv/bin/python tools/render.py "fonts/BloxwapSans/variable/BloxwapSans[wght].ttf" out.png "Text" --wghts 100,400,900Look at every preview and iterate until the shapes are right. See Design for the rules.
Working on this website
The website is a Fumadocs app (Next.js, static export) in apps/docs/. It needs the generated files above (they are produced by the font build).
The site is published at https://bloxwap.github.io/font/. Build and preview it under that base path with:
NEXT_PUBLIC_BASE_PATH=/font bun run docs:build
NEXT_PUBLIC_BASE_PATH=/font bun run docs:preview # http://localhost:3904/font/Docs pages are MDX in apps/docs/content/docs/. Tables of features, languages, axes and coverage are components that read apps/docs/public/data/ at build time; use them instead of typing numbers.
The home page projects server metadata into separate prop types for the type tester, glyph browser and language list. Keep coverage blocks, full feature tables, language rows and file inventories out of those props. Coverage highlights are computed on the server; feature tooltip details load on pointer or keyboard focus, and web-font inventories load when their download list is expanded. Both use the existing family JSON and the shared client cache. Glyph lists and language rows also load from public JSON at runtime, with the configured base path.
To verify the static export locally:
bun run docs:build
bun run docs:preview
# In another terminal:
DOCS_URL=http://localhost:3904/ bun run docs:smoke
DOCS_URL=http://localhost:3904/ bun run docs:accessibilityThe smoke suite checks that the home HTML stays below 250,000 bytes, feature details preserve active toggles, and expanded web-font lists load once. For a /font build, use DOCS_URL=http://localhost:3904/font/ and the same NEXT_PUBLIC_BASE_PATH when building and previewing.