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:

  1. Authoring. Most pages are Typst. Selected LaTeX files can also become webpages. JavaScript and CSS implement browser-only utilities.
  2. Compilation. GNU Make discovers pages, tracks dependencies, compiles HTML and selected PDFs, and builds generated indexes and feeds.
  3. Post-processing. .site/build/postprocess-site.py enriches 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.
  4. Validation. Draft-isolation tests, syntax checks, and local-reference checks run before generated output is committed.
  5. Publication. The Build Site workflow commits generated HTML/PDF/feed/runtime output back to main; GitHub Pages publishes main from / (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:

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:

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:

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.tex

The 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.

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:

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:

.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

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 clean

SITE_URL controls canonical deployment URLs:

make SITE_URL=https://example.org

Run make format with the expected Typstyle version when changing Typst source. make
check-references
should pass after a full build; it catches incorrect relative imports and local asset links before deployment.

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:

  1. sparsely checks out source text and hydrates only binary inputs needed by actual site sources;
  2. restores Typst dependency/cache state and recent Git timestamps for incremental Make decisions;
  3. installs Typst and, only when needed, Pandoc and digest-test dependencies;
  4. runs browser/Python syntax checks and the relevant draft, digest, and LaTeX tests;
  5. runs make -j4 publish;
  6. conditionally rebuilds projects/personalwebsite.zip when its inputs changed;
  7. post-processes generated HTML and installs the root service worker;
  8. runs make check-references;
  9. commits changed generated output back to main as chore: 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:

The useful distinction is now:

Troubleshooting

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/.