Website Documentation
This page documents the current architecture of this website: how pages are authored, how Typst and LaTeX become web pages, how collaborative drafts work, how browser utilities are added, and how the site is rebuilt and published from the root of main.
Download the reusable website template for a sanitized starter copy. Open the isolated demo suite to see each site mode on synthetic content. For Typst itself, use the official documentation and the Typst Examples Book.
Architecture
The site is source-driven and statically deployed. The important layers are:
- Authoring. Most pages are Typst. Selected LaTeX files can also become webpages. JavaScript and CSS implement browser-only utilities.
- Compilation. GNU Make discovers pages, tracks dependencies, compiles HTML and selected PDFs, and builds generated indexes and feeds.
- Post-processing.
.site/build/postprocess-site.pyenriches normal HTML pages with stable heading anchors, canonical metadata, Open Graph/Twitter metadata, JSON-LD, the global Atom feed, sitemap, manifest, and service-worker registration. - Validation. Draft-isolation tests, syntax checks, and local-reference checks run before generated output is committed.
- Publication. The Build Site workflow commits generated HTML/PDF/feed/runtime output back to
main; GitHub Pages publishesmainfrom/ (root).
GitHub Pages remains a static host. The only server-side component used by the ordinary site is the Cloudflare route backing collaborative drafts.
The central Typst files
cv.typ has three roles:
- it is the printable CV source;
- it becomes the homepage;
- it configures the shared
templateimported by the rest of the Typst site.
The template implementation lives in .site/tufted.typ. It dispatches between ordinary HTML, ordinary PDFs, books, research papers, presentations, and draft shells while sharing navigation, math, references, theorem helpers, margin notes, and responsive styling.
A typical page is:
#import "../cv.typ": *
#show: template.with(title: "Example")
== A section
Content.Nested pages should import the nearest parent index.typ when that parent intentionally re-exports the site definitions. Relative paths are resolved from the file containing the import; an incorrect number of ../ components is one of the most common causes of reference-check failures.
Creating a Typst page
Create path/to/page/index.typ. The corresponding route is /path/to/page/.
The Makefile discovers Typst website sources by their import relationship with cv.typ; a normal new page does not need to be listed manually. Shared Typst files are conservative dependencies, so a change to the template rebuilds affected pages.
Useful template flags include:
pdf: true: also produce a printable PDF;article: true: long-form article styling;research: true: Arkheion research-paper output and automatic PDF generation;presentation: true: Touying/Metropolis PDF plus the browser presentation viewer;book: true: book-like paged typography;draft: true: publish an editable draft shell rather than the draft body.
Research example:
#show: template.with(
title: "A Research Result",
research: true,
abstract: [A short abstract.],
keywords: ("algorithms", "economics"),
)Presentation example:
#show: template.with(
title: "A Presentation",
presentation: true,
)The presentation route serves a PDF-backed viewer rather than Typst’s experimental HTML rendering. PDF.js renders one slide at a time and supports keyboard, click/tap, swipe, and fullscreen navigation.
Math, references, theorems, and margin content
Typst math is shared between HTML and paged output. Displayed equations can be labeled and referred to normally:
$
sum_(i=1)^n i = n(n+1)/2
$ <sum-formula>
See @sum-formula.Bibliographies use ordinary Typst/BibTeX support:
This is cited here @sample2026.
#bibliography("refs.bib")The shared template also provides theorem, lemma, proposition, fact, and margin-note. Paged output uses ordinary Typst footnotes. In HTML, a footnote is rendered as a numbered margin note with a two-way link: the superscript number in the sentence links to the note, and the number at the start of the margin note links back to that exact superscript. The return link is therefore the footnote number itself; there is no separate arrow or site-wide backlink section.
A sentence with a note#footnote[The footnote body.]The isolated feature demo exercises footnotes, margin notes, labeled equations, theorem environments, and links without reusing another site page.
The post-processing stage gives headings stable HTML IDs when Typst did not emit one, permitting direct links to mathematical sections.
LaTeX webpages
LaTeX is opt-in because the repository also contains standalone manuscripts that should never be published merely because they end in .tex.
A LaTeX file becomes a webpage when either:
- its filename ends in
.page.tex; or - its protected header contains
% website: trueor% draft: true.
Pandoc performs the web conversion. The result is wrapped in the same site shell rather than being served as an unrelated standalone HTML document. LaTeX source formatting follows the same general 100-column convention as Typst source.
Collaborative drafts
A Typst draft enables editing in its template call:
#show: template.with(
title: "Working Notes",
draft: true,
)
// BEGIN DOCUMENT
Editable material starts here.A LaTeX draft uses % draft: true in the protected header and % BEGIN DOCUMENT before the editable body:
% draft: true
\documentclass{article}
\begin{document}
% BEGIN DOCUMENT
Editable material starts here.
\end{document}Only content after the explicit marker is editable. If a marker is missing, the boundary logic can fall back to the first safe body position after the Typst template declaration or LaTeX \\begin{document}, but an explicit marker is preferable.
The protected prefix contains imports or the LaTeX preamble together with draft authorization. The browser never receives arbitrary repository files or exposes that prefix as editable text. Draft compilation also keeps the editable body out of the published shell, so malformed half-written source cannot break the public website build.
The production draft backend is a Cloudflare Worker using one SQLite-backed Durable Object per source file. Browsers exchange batched CodeMirror updates over hibernating WebSockets. Draft state is checkpointed to GitHub after a period of inactivity or immediately on Ctrl/Cmd-S. Checkpoint commits use [skip ci]; turning draft mode off in a normal commit returns the page to ordinary rendering.
Draft pages are excluded from automatic PDF generation, school indexes, feeds, presentation classification, and other feature scans. The build contains explicit test-draft-isolation and test-draft-pdf-exclusion checks to preserve this property.
For local draft work:
make draft-local SOURCE=path/to/index.typ
make draft-local SOURCE=path/to/index.page.texThe browser can compile Typst previews directly. LaTeX PDF preview is local-only and uses the local helper with Tectonic, latexmk, LuaLaTeX, or pdfLaTeX when available.
The Cloudflare Worker implementation and deployment notes live under .site/draft-worker/. Production editing requests are origin-restricted to this website and only operate on authorized relative Typst/LaTeX draft paths.
Isolated demo suite
All website demos live under documentation/demos/ and use synthetic content. They do not reuse blog posts, coursework, papers, presentations, research notes, or any other real webpage.
- Shared feature demo — footnotes/return links, margin notes, math references, theorem environments, and ordinary links.
- Article demo — standalone
article: truecontent. - Research demo — standalone
research: truecontent with generated PDF output. - Presentation demo — standalone
presentation: trueslide deck. - Typst draft editor demo — a disposable collaborative Typst draft.
- LaTeX draft editor demo — a disposable collaborative LaTeX draft.
The draft demos are intentionally real editable drafts, so changes made there can synchronize and be checkpointed like any other draft. Their contents are disposable by design.
Unlisted public routes
Several public routes are intentionally omitted from the primary Home/Blog/School/Piano/CV navigation. They are unlisted, not secret or access-controlled:
- Documentation — this page.
- Book reader — Standard Ebooks/Gutenberg lookup and in-browser PDF rendering.
- Brown noise — local Web Audio brown-noise generator.
- Radio — recommendation-driven YouTube recording player.
- Weekly digest — the generated digest page.
- Reusable website archive — sanitized copy of the site implementation.
- Global Atom feed, sitemap, and web-app manifest — machine-facing generated endpoints.
Because production currently publishes the root of main, omission from navigation provides no privacy boundary. Any tracked route intended to remain confidential must not be placed on the published branch.
Browser utilities
Book reader
/book/ searches Standard Ebooks first and Project Gutenberg second, cleans a readable edition, extracts chapter structure, previews it, converts the cleaned content to Typst, and can compile a PDF in the browser. External catalog/source availability and browser cross-origin restrictions can affect it.
Brown noise
/noise/ generates brown noise locally with Web Audio. No audio is uploaded or recorded. The page is intentionally minimal.
Radio
/radio/ is an artist/recording-oriented radio built on the official YouTube IFrame Player API. The site chooses the recording; YouTube supplies playback.
Stations currently include folk, Russian Romantic, Chopin/Liszt, Beethoven, Impressionist, Classical, Classic Rock, and Schubert/Schumann/Brahms. The visible site UI deliberately exposes only station selection and thumbs up/down—not play, pause, seek, previous, or skip controls.
Preferences are stored locally in the browser and learned separately within each station. Ratings update feature-level and recording-level preferences such as composer, performer, form, instrumentation, style, and other curated tags. The recommender also explores less-played material and avoids very recent repeats. A thumbs-down moves to another recording; a thumbs-up records the preference and lets the current recording continue.
The page requires both radio/index.html and the runtime .site/radio.js to be present on main. make check-references catches missing same-repository assets before generated output is committed.
Weekly digest
The digest workflow combines configured RSS/arXiv sources, newsletters, selected social/video sources, local/campus events, deadlines, election information, weather, and a maintenance report. The same cleaned input is rendered to the website and email. Configuration lives in digest/config.yml; implementation lives in .site/digest/.
Discovery, metadata, and offline support
After compilation, the site postprocessor adds or generates:
- canonical URLs;
- page descriptions and social metadata;
- JSON-LD article metadata;
- stable IDs for headings;
/sitemap.xml;- the global
/feed.xml; /manifest.webmanifest;- service-worker registration.
.site/sw.js supplies basic same-origin caching/offline behavior. PWA support is intentionally lightweight; the site remains a normal website first.
Dated feeds created explicitly with .site/rss.typ remain separate from the global feed. A page can use post-section, post-link, and feed for date-aware publishing. Future-dated posts remain in paged output but are omitted from HTML/RSS until their date arrives.
Repository map
cv.typ: homepage, CV, navigation, and configured shared template..site/tufted.typ: primary Typst template and HTML/PDF dispatcher..site/assets/: shared responsive CSS and Tufte-derived adjustments..site/fields.typ: CV/publication structured fields..site/layout.typ,.site/notes.typ,.site/figures.typ: Tufte-style layout helpers..site/math.typ,.site/refs.typ,.site/theorems.typ: mathematical-document helpers..site/rss.typ: dated post and feed helpers..site/latex.mk: LaTeX webpage discovery/build rules..site/draft-editor.js: browser draft editor..site/draft_boundary.py: protected-prefix/editable-body boundary logic..site/draft-local.py: local draft server/preview support..site/draft-worker/: Cloudflare collaborative-draft backend..site/presentation-viewer.js: PDF-backed presentation viewer..site/book.js,.site/noise.js,.site/radio.js: browser utility runtimes..site/build/postprocess-site.py: metadata, anchors, sitemap/feed/PWA generation..site/build/check-references.py: validates local links, imports, and assets..site/build/export-personalwebsite.sh: builds the sanitized reusable-site archive..site/Makefile: page discovery, dependency tracking, compilation, testing, feeds, and exports..github/workflows/build.yml: builds, validates, and commits generated site output..github/workflows/check-live-draft.yml: production smoke tests for the deployed draft editor..github/workflows/draft-worker.yml: checks and deploys the Cloudflare draft Worker..github/workflows/weekly-digest.yml: scheduled digest generation and email delivery.blog/,school/,papers/,projects/: primary content trees.book/,noise/,radio/,digest/: browser utilities and generated/published services.documentation/demos/: isolated synthetic examples of every major site mode..nojekyll: disables Jekyll processing and keeps dot-prefixed runtime assets available.CNAME: custom-domain declaration.
Do not hand-edit generated HTML or PDFs. Edit their Typst/LaTeX/JavaScript/CSS/Python/BibTeX source and rebuild.
The Makefile
Common targets are:
make # build normal site outputs and reusable archive
make publish # HTML, CV, selected PDFs, feeds
make html # discovered HTML/viewer pages
make pdf # selected PDFs
make check-references
make test-draft-isolation
make test-draft-pdf-exclusion
make personalwebsite # sanitized reusable template archive
make cleanSITE_URL controls canonical deployment URLs:
make SITE_URL=https://example.orgRun make format with the expected Typstyle version when changing Typst source. make should pass after a full build; it catches incorrect relative imports and local asset links before deployment.
check-references
GitHub Pages deployment
Production uses GitHub Pages Deploy from a branch with branch main and folder / (root).
On a normal push to main, the Build Site workflow:
- sparsely checks out source text and hydrates only binary inputs needed by actual site sources;
- restores Typst dependency/cache state and recent Git timestamps for incremental Make decisions;
- installs Typst and, only when needed, Pandoc and digest-test dependencies;
- runs browser/Python syntax checks and the relevant draft, digest, and LaTeX tests;
- runs
make -j4 publish; - conditionally rebuilds
projects/personalwebsite.zipwhen its inputs changed; - post-processes generated HTML and installs the root service worker;
- runs
make check-references; - commits changed generated output back to
mainaschore: rebuild site [skip ci].
The [skip ci] generated commit prevents the Build Site workflow from recursively rebuilding its own output. GitHub Pages sees that generated commit and republishes the root of main.
The scheduled Build Site run handles date-sensitive output even when source has not changed. A manual Build Site run performs all subsystem checks, rebuilds the reusable-site ZIP, and uploads that ZIP as a workflow artifact as well as committing it when changed.
For a custom domain, keep CNAME, the GitHub Pages custom-domain setting, DNS, and SITE_URL consistent.
Root-publishing rules
Root publishing deliberately favors simplicity over an allowlisted deployment artifact. There is no separate .build/pages package: Pages publishes the branch root after GitHub’s own Pages processing. Consequences:
- generated web output and source/build files coexist on
main; - any tracked file that GitHub Pages includes can potentially become web-addressable, so sensitive material should not be committed to the published branch;
.nojekyllis required because browser runtime assets intentionally live under.site/;- adding a browser asset usually requires only tracking it at the path referenced by the page and passing
make check-references—there is no separate Pages allowlist to update.
The useful distinction is now:
- build success means generated output passed local build/validation checks and was committed;
- Pages success means GitHub’s branch deployment for that commit completed and the root branch is live.
Troubleshooting
- A route is 404: verify the generated file exists on
main, then check the latest GitHub Pagespages build and deploymentrun for that commit. - A page loads but its controls do nothing: verify the referenced runtime
.js/CSS file is tracked onmain, is reachable at the expected path, and passedmake check-references. make check-referencesreports paths such as../../../cv.typ: count from the source directory, not from the route. An extra../can compile only because a stale generated file exists while still failing the reference checker.- A Typst page is not discovered: verify its import chain reaches
cv.typand that it is not an unpublished_file or an active draft excluded from that feature scan. - A LaTeX file is not a webpage: use
.page.texor add% website: trueto its protected header. - A draft exposes the wrong material: verify draft authorization is in the protected prefix and place an explicit
// BEGIN DOCUMENTor% BEGIN DOCUMENTboundary before editable content. - A draft breaks the public build: that should be treated as a regression; the draft body must not enter normal HTML/PDF feature scanning.
- A LaTeX draft has no browser PDF preview: production LaTeX preview is intentionally local-only; run
make draft-localwith a supported LaTeX engine installed. - HTML and PDF differ: inspect target-specific template branches. Typst HTML remains experimental and not every paged-layout primitive has a direct HTML equivalent.
- A presentation is blank: open the PDF directly first, then inspect PDF.js/runtime asset paths.
- The book utility fails: an external catalog/source endpoint or browser cross-origin policy may be unavailable.
- The radio page reports unavailable recordings: a curated YouTube video may have been removed, region-restricted, or disabled for embedding; the runtime will try another candidate.
- The digest fails: inspect the workflow log and configured credentials/sources rather than editing generated digest output.
Reusable template and licensing
make personalwebsite builds projects/personalwebsite.zip, replacing personal material with neutral examples and checking the archive for site-specific leakage. The exported copy retains the same build/template structure and can itself generate another sanitized archive. A manual Build Site workflow run also uploads the archive as a downloadable Actions artifact.
The reusable implementation is distributed under the Mozilla Public License 2.0. Personal content (CV data, posts, research, applications, images, and other authored material) is not licensed for reuse unless a file says otherwise.
The implementation builds on Tufted/Tufte CSS, Typst and its package ecosystem, PDF.js, CodeMirror, and the external services explicitly used by individual utilities. Third-party notices and the full MPL-2.0 text are included under .site/licenses/.