# shiroa builds a browsable online book out of Typst sources

> shiroa is a Rust CLI and TypeScript front end that compiles Typst documents into modern online books with search, themes and a static HTML mode. The repository is Apache-2.0 licensed, actively pushed, and its documented Rust and toolchain requirements do not agree with each other.

**Myriad-Dreamin/shiroa** — shiroa is a simple tool for creating modern online books in pure typst.

- Repository: https://github.com/Myriad-Dreamin/shiroa
- Website: https://myriad-dreamin.github.io/shiroa/
- Stars: 671 · Forks: 32
- Language: Typst
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/myriad-dreamin-shiroa

## The book is a directory of Typst files, not a document format of its own

shiroa is described as a simple tool for creating modern online books in pure Typst. That last phrase carries the design: there is no separate authoring format, no intermediate representation, no proprietary project file. You write Typst, and shiroa compiles it into a website. The name has two readings given in the README, Shiro A and The White. The intended users are people who already prefer Typst for typesetting and want the output side of a book, meaning chapters that can be navigated, themed, and read in a browser, rather than a long PDF. The project is Apache-2.0 licensed and published by the maintainers of Typst tooling such as Tinymist, which shows up in the dependency list. The scope is deliberately narrow: one tool to turn Typst content into a modern online book, with the front end and themes assembled from parts the README credits explicitly.

## A Rust CLI, a TypeScript front end and a Typst evaluation engine

The workspace layout explains the architecture. The Cargo manifest declares two workspace members, cli and tools/build-from-source, and the tree adds a frontend directory, a packages directory, a themes directory and a scripts directory, with pnpm-workspace.yaml and pnpm-lock.yaml covering the JavaScript side. The Rust dependencies name the pieces that matter. typst, typst-eval and typst-assets sit at version 0.15.0, so the tool compiles documents against a recent Typst. reflexo-typst with the html feature and reflexo-vec2svg with an experimental ligature feature do the evaluation and vector work, tinymist-task brings the editor task infrastructure, and warp serves the site with compression enabled. Search is handled by elasticlunr-rs at version 3.0.2, which is a browser oriented full text index. The front end is built with esbuild, the only package listed under pnpm onlyBuiltDependencies, and the result is a search index, a server and a static bundle assembled from the same pipeline.

## Installing the CLI takes cargo, and the source route also needs pnpm

Executable binaries for Windows, macOS and Linux are published on the GitHub Releases page, and the archive contains an shiroa executable you add to your PATH. If you would rather build it, the README points at the pnpm and Rust installation pages and states that shiroa currently requires at least Rust version 1.75. With precompiled artifacts in the Cargo registry, the install is one command.

```sh
cargo install --git https://github.com/Myriad-Dreamin/shiroa --locked shiroa
```

Building from source clones the repository, initialises the submodules and runs the build binary directly.

```sh
git clone https://github.com/Myriad-Dreamin/shiroa.git
git submodule update --recursive --init
cargo run --bin shiroa-build
# optional: install it globally
cargo install --path ./cli
```

A global install is removed with cargo uninstall shiroa, and the README reminds you to put the Cargo bin directory on your PATH. The presence of a shiroa-build binary alongside the shiroa binary itself is worth noting: the CLI is packaged with a helper that can rebuild the front end artifacts, which is how a project with a TypeScript front end and a Rust binary ships as a single command.

## There is no watch command, and that is a deliberate choice

The README states plainly that shiroa does not provide a watch command, and that it is designated to embrace all approaches to writing Typst documents. The reasoning is practical. Instead of owning the preview loop, shiroa points at tools that already do it well. The first option is the official Typst web app at typst.app. The second is the editor route, where VSCodium users can install the Tinymist extension and the Typst Preview extension from the marketplace, and Neovim users are pointed at the typst.vim plugin and a Typst Preview variant that works outside VS Code. The third is the plain command line option, typst-cli watch, run against the same sources. The consequence for a reader is that previewing and building are two different worlds: your editor or the Typst CLI gives you fast feedback on a single document, and shiroa produces the book. That separation is a reasonable boundary, but it means the tight feedback loop of a dedicated book editor is not part of what you get.

## A static HTML mode sits next to the served mode

The package scripts show two ways to produce output. The docs script runs the CLI in serve mode with a font path pointing into the assets/fonts directory, watching the github-pages/docs directory, and the html variant appends a static-html mode flag. That single flag is the difference between a live local site and a bundle you can upload somewhere. The build pipeline around it is a modern JavaScript toolchain: pnpm with a frozen lockfile, an esbuild based front end build, and a dist step that generates release artifacts. A separate script drafts releases. The project also ships a Dockerfile, which is the fastest way to see how the two halves fit together.

```dockerfile
ARG NODE_VERSION=22
ARG RUST_VERSION=1.89.0
FROM node:${NODE_VERSION}-alpine AS build-pnpm
RUN apk add --no-cache cpio findutils git
ADD . /app
WORKDIR /app
RUN corepack enable && pnpm install --frozen-lockfile && pnpm --dir frontend run build
```

The Node Alpine stage installs the front end dependencies and builds the front end. A second stage based on rust bullseye copies that built front end in and compiles the Rust binary with cargo build in release mode, and the final image copies only the resulting shiroa executable into a Debian base. The result is a single binary image with no runtime dependency on Node.

## The theme comes from mdBook, and the tests run through Tinymist

The themes directory contains an mdBook theme that the README says is borrowed from the mdBook project, with a link pinned to a specific mdBook commit. Reusing a Rust book toolchain theme keeps the visual result familiar for anyone who has read mdBook output, and pinning the commit means the theme does not drift under you. Typography itself is handled by Typst, which the README credits as the tool used to compile the document. Testing is done at the Typst level rather than only at the Rust level: the test script runs tinymist test against packages/shiroa-tests/main.typ, with the html feature enabled, system fonts ignored, the same assets font path, and coverage printed in full. That is a meaningful choice, since it means the assertions run against the rendered output rather than against internal function returns, and the html feature flag confirms the web specific path is covered.

## Rust version requirements and release tags disagree with each other

Two inconsistencies are worth raising before you commit to a version. The README tells you that shiroa currently requires at least Rust version 1.75, while the workspace manifest in the repository asks for a Rust version of 1.92, and the container build pins 1.89.0 as its Rust version. The manifest also carries a comment reminding maintainers to change the toolchain file and CI when the version moves, which suggests the number is intentionally current and the README text is the part that lags. On releases, the published tags are candidates rather than finals: v0.4.0-rc2 from 2026-06-29, v0.4.0-rc1 from 2026-06-22 and v0.3.1-rc4 from 2025-12-06. The workspace manifest version field reads 0.4.0-rc2, matching the newest tag, while the JavaScript package version field reads 0.0.0 and is marked private. The licence is Apache-2.0 with the terms in the LICENSE file, which is a permissive grant with the usual obligations around notices and patent terms, though the specifics belong with your own reviewers.

## Conclusion

shiroa is the right choice for a team that already writes Typst and wants a published, searchable web book instead of a PDF, and for people willing to run the preview loop through the Typst web app or an editor plugin rather than a built in watch command. It is the wrong choice if you need a stable release today, since the newest published tag is the release candidate v0.4.0-rc2, or if you want a one tool install, since the CLI needs Rust and Cargo, the front end needs pnpm, and the container build stitches a Node Alpine stage to a Rust Bullseye stage to a Debian image. Verify three things before you commit: which Rust version actually builds, because the README says at least 1.75 while the workspace manifest asks for 1.92, whether the static HTML mode produces the output your hosting expects, and that the Apache-2.0 grant in the LICENSE file covers the way you plan to publish the result. The last push was on 2026-10-08, so the code is moving, but the versioning is still in the candidate stage.

## FAQ

### How do I install the shiroa CLI?

Prebuilt binaries for Windows, macOS and Linux are on the GitHub Releases page, and you add the shiroa executable to your PATH. From source, the README gives a cargo install command using the Git repository with the locked flag, or a clone followed by submodule update and cargo run with the shiroa-build binary.

### Does shiroa have a watch or preview command?

No. The README states that no watch command is provided and that shiroa is designed to embrace existing ways of writing Typst, pointing to the official Typst web app, editor plugins such as Tinymist and Typst Preview, and typst-cli watch for previewing.

### Can shiroa output a static site instead of running a server?

Yes. The docs script runs the CLI in serve mode, and a second script appends a static-html mode flag to produce static output for hosting. The build scripts also include a dist generate step for release artifacts.

### What licence is shiroa released under?

The project is released under Apache-2.0, with the terms in the LICENSE file in the repository. The Cargo workspace manifest and the JavaScript package manifest both list Apache-2.0.

## Sources

- [License: Apache-2.0](https://github.com/Myriad-Dreamin/shiroa/blob/main/LICENSE)
- [Myriad-Dreamin/shiroa on GitHub](https://github.com/Myriad-Dreamin/shiroa)
- [Project website](https://myriad-dreamin.github.io/shiroa/)
- [README](https://github.com/Myriad-Dreamin/shiroa/blob/main/README.md)
- [Releases](https://github.com/Myriad-Dreamin/shiroa/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/myriad-dreamin-shiroa