zeitschrift

Named for Zeitschrift für Physik, where Heisenberg published matrix mechanics and Schrödinger published wave mechanics. 1920s Berlin. The journal of record.

In memory of Eelco Visser (1966–2022), whose scope graph theory makes principled cross-referencing possible.

---

Zeitschrift is a documentation toolchain that combines:

• Scope graph-based cross-referencing — Every identifier resolves. Broken links are build errors.
• OpenAPI/AsyncAPI code generation — Rust, C++23, Python, TypeScript. Idiomatic output.
• Static site generation — Company sites, blogs, docs, API references. One tool.
• Plugin architecture — LaTeX, legal docs, markdown, interchange formats.

Installation

Nix (recommended)

# Run directly
nix run github:weyl-ai/zeitschrift -- build site/

# Install to profile
nix profile install github:weyl-ai/zeitschrift

# Development shell
nix develop github:weyl-ai/zeitschrift

From source

git clone https://github.com/weyl-ai/zeitschrift
cd zeitschrift
cabal build
cabal install

Quick Start

Build a documentation site

# Build site
zeitschrift build site/

# Development server with hot reload
zeitschrift serve site/

# Check links without building
zeitschrift check site/

Generate API client code

# Rust client with reqwest
zeitschrift codegen openapi.yaml --lang rust --client

# Python server with FastAPI
zeitschrift codegen openapi.yaml --lang python --server

# TypeScript client with fetch + Zod
zeitschrift codegen openapi.yaml --lang typescript --client

# C++23 server with libhv
zeitschrift codegen openapi.yaml --lang cpp --server

Generate event-driven code from AsyncAPI

# Python with aiokafka
zeitschrift codegen asyncapi.yaml --lang python --events --broker kafka

# TypeScript with nats.js
zeitschrift codegen asyncapi.yaml --lang typescript --events --broker nats

Features

Scope Graphs

Every reference in your documentation resolves to a definition. Cross-language, cross-file, cross-repository.

See [`Config.timeout`](../api/config.md#timeout) for connection settings.

If Config.timeout doesn't exist, the build fails. Not a warning. An error.

Based on Visser et al.'s scope graph theory:

"A scope graph is a data structure that represents the binding structure of a program... Name resolution is path finding in the scope graph."

Code Generation

Generated code looks like a human wrote it:

Rust:

let client = PetStoreClient::builder()
    .base_url("https://api.petstore.com")
    .bearer_token("secret")
    .build()?;

let pet = client.pets().get(pet_id).await?;

Python:

async with PetStoreClient(ClientConfig(
    base_url="https://api.petstore.com",
    bearer_token="secret",
)) as client:
    pet = await client.get_pet(pet_id=123)

TypeScript:

const client = new PetStoreClient({
  baseUrl: 'https://api.petstore.com',
  bearerToken: 'secret',
});

const pet = await client.getPet({ petId: 123 });

C++23:

Client client{{
    .base_url = "https://api.petstore.com",
    .bearer_token = "secret",
}};

auto result = co_await client.pets().get_pet(pet_id);

Static Site Generation

One tool for your entire web presence:

site/
├── index.md              # Landing page
├── blog/
│   └── 2025-*.md         # Blog posts
├── docs/
│   └── **/*.md           # Documentation
├── api/
│   └── openapi.yaml      # Auto-generates reference
└── legal/
    └── privacy.md        # Legal pages

Features:

• Broken link = build error
• Auto-generated sitemap with git lastmod
• RSS/Atom feeds
• Schema.org JSON-LD
• Dark mode
• Print styles

Plugin Architecture

markdownPlugin :: Plugin
markdownPlugin = Plugin
  { pluginName = "markdown"
  , pluginExtensions = [".md", ".markdown"]
  , pluginParse = parseMarkdown
  , pluginExtract = extractDefinitions
  , pluginGenerate = generateHtml
  }

Built-in plugins:

• Markdown — CommonMark + GFM + admonitions
• LaTeX — Academic papers with BibTeX
• Legal — Privacy policies, terms of service
• Protobuf/GraphQL/FlatBuffers/JSON Schema — Schema cross-referencing

Code Generation Languages

Language	HTTP Client	HTTP Server	Events	Notes
Rust	reqwest	axum	—	Type-state builders, thiserror
C++23	libhv	libhv	Kafka, NATS, RabbitMQ, Redis	Coroutines, std::expected
Python	httpx	FastAPI	aiokafka, nats-py, aio-pika, redis	Pydantic v2, async/await
TypeScript	fetch	Hono	kafkajs, nats, amqplib, redis	Zod validation, native fetch

Project Structure

zeitschrift/
├── src/Zeitschrift/
│   ├── Codegen/           # Code generation backends
│   │   ├── Types.hs       # Codegen IR
│   │   ├── Rust.hs        # Rust backend
│   │   ├── Cpp.hs         # C++23 backend
│   │   ├── Python.hs      # Python backend
│   │   └── TypeScript.hs  # TypeScript backend
│   ├── Plugin/            # Document plugins
│   │   ├── Markdown.hs
│   │   ├── LaTeX.hs
│   │   └── Legal.hs
│   ├── Resolve/           # Scope graph resolution
│   │   └── ScopeGraph.hs
│   └── Site.hs            # Static site generation
├── themes/
│   └── visser/            # Default theme (dedicated to Eelco Visser)
├── docs/
│   ├── AUTHORING.md       # Site authoring guide
│   └── CODEGEN.md         # Code generation architecture
└── app/Main.hs            # CLI

Comparison

Feature	zeitschrift	Hugo	Docusaurus	Fern	Speakeasy
Broken link = error	✓	✗	✗	✗	✗
Scope graphs	✓	✗	✗	✗	✗
OpenAPI codegen	✓	✗	plugin	✓	✓
AsyncAPI codegen	✓	✗	✗	✗	✗
Static site	✓	✓	✓	✓	✗
Blog	✓	✓	✓	✗	✗
Nix native	✓	✓	✗	✗	✗
No JS runtime	✓	✓	✗	✗	✗
Open source	✓	✓	✓	partial	✗

Development

# Enter dev shell
nix develop

# Build
cabal build

# Test
cabal test

# Format
fourmolu -i src/

# Run
cabal run zeitschrift -- build site/

Full dev shell (with all codegen targets)

nix develop .#full

This includes Rust, C++, Python, and TypeScript toolchains for testing generated code.

Contributing

1. Fork the repository
2. Create a feature branch
3. Run fourmolu -i src/ before committing
4. Submit a pull request

License

BSD-3-Clause

Acknowledgments

• Eelco Visser and the Spoofax team for scope graph theory
• Zeitschrift für Physik for the name and spirit of rigorous publication
• The Haskell, Rust, Python, and TypeScript communities

---

"Parse everything, emit hyperlinked HTML, no forgiveness."