Our anti-scam yellow paper is typeset in LaTeX, bilingual from a single source, and reproducibly versioned — while everything else we ship is a web page. Why: a security document that readers must verify and cite needs deterministic builds, not a CMS.
We just shipped the Onchain Anti-Scam Yellow Paper — a fraud-prevention manual that condenses Onchain Diary’s 76-article research series into 14–15 pages. The build tool is LaTeX, compiled with tectonic. In a portfolio where everything else is Astro-on-Cloudflare, that choice deserves an explanation.
Why a PDF at all
Web pages optimize for discovery. PDFs optimize for authority and portability. A yellow paper is a citable artifact — the format itself signals “systematic reference document” rather than “SEO content.” It gets attached, forwarded, printed, pinned in Discords, and cited in ways blog posts are not. For a content asset meant to anchor a site’s expertise, that’s the right shape.
The genre convention matters too. “Yellow paper” promises a certain austerity: numbered sections, a taxonomy, definitions, checklists, a version number, a changelog. That promise is easier to keep when the document is built like a spec rather than styled like a landing page.
Why LaTeX specifically
Three properties, all of them about trust:
Reproducibility. The repository builds the document. Anyone can clone it, run tectonic main-zh.tex, and get the same PDF — or fork it and produce an annotated edition. A document about verifying things should itself be verifiable. The build is two commands and has no moving parts beyond a ~30MB static binary.
Typographic ceiling. CJK and Latin text share a page without the compromises you get from HTML-to-PDF converters: proper punctuation handling, disciplined spacing, real small caps and oldstyle figures where they matter. The paper is 40% checklists and tables — structures that LaTeX has had 40 years to get right.
Longevity. LaTeX source from 1995 compiles today. The source is plain text, diffable, and dependency-light. Content assets we intend to maintain for years should age like source code, not like CMS exports.
The cost is real: no instant preview, a compile loop, and TikZ figures that take longer than they should. For a document revised quarterly, that cost amortizes to nothing.
The bilingual single-source tree
Both editions — English and 中文 — live in one repository:
main-zh.tex / main-en.tex # two entry points, one preamble each
sections/00-abstract-zh.tex # chapter files, language-suffixed
sections/00-abstract-en.tex
dist/…-zh.pdf / dist/…-en.pdf # release artifacts, committedThe non-obvious decision: the editions are written in parallel, not translated. The English edition is not a rendering of the Chinese; each is written for its reader, in the register that reader expects — the Chinese edition speaks in the idiom of Chinese crypto communities, the English edition in plain technical English. Structure, figures, and facts stay identical; sentence-level expression diverges freely.
Machine translation would have been faster and visibly worse. Bilingual credibility dies at the first calque, and in security content a slightly-off sentence is a comprehension hazard, not a style problem.
The publishing loop
- Write in
sections/, compile with tectonic, iterate. - Copy release PDFs into
dist/and the Onchain Diary site’spublic/yellowpaper/. - Landing pages on the site (English and Chinese) carry the downloads, a schema.org
Bookblock, and the table of contents. - Commit, push, deploy. The site’s llms.txt indexes the paper alongside the research series, so AI engines discover it with the rest of the corpus.
The whole loop is a few minutes, and every artifact — PDFs, landing pages, source — ships from one commit.
What we’d do differently
The TikZ diagrams (the taxonomy tree, the defense-stack figure) took disproportionate effort for their visual payoff. Next revision we’ll likely move to generated figures where a chart library does the layout math. And we’d front-load the checklist appendix: in user feedback it’s the part people actually print, and it deserves to be a standalone one-pager as well as an appendix.
The paper itself is here, the LaTeX source is on GitHub under CC BY-NC-SA 4.0, and the companion insight post — what the compression revealed about onchain fraud — is here.