Website themes

Website themes#

QuantEcon maintains its own themes so the lecture sites share one look and one set of reading affordances (launch buttons, downloads, dark mode, “on this page” navigation). There are three theme repositories, and they are at very different stages — one is in production, one is being built for the migration to Jupyter Book 2, and one is an early experiment.

Theme

Renders

Status

Distribution

quantecon-book-theme

Sphinx / Jupyter Book 1

Production — every published lecture site

PyPI

quantecon-theme.mystmd

MyST (mystmd) / Jupyter Book ≥ 2

In development — feature parity ahead of the migration

zip on each GitHub Release

quantecon-sphinx-theme

Sphinx (general documentation)

In development — experimental, awaiting a go / no-go

unreleased

Important

Only the first two are load-bearing. quantecon-sphinx-theme has no releases, is not on PyPI, and has no downstream users — do not reach for it when starting a new project.

quantecon-book-theme#

The theme behind every published QuantEcon lecture series — lecture-python.myst, lecture-python-intro, lecture-python-programming, lecture-python-advanced.myst, lecture-jax, lecture-julia.myst, lecture-datascience.myst, lecture-dp, the Chinese translations, and others.

It is a Sphinx theme (html_theme = quantecon_book_theme) that inherits from pydata-sphinx-theme and is compiled with sphinx-theme-builder. Because it runs at build time inside the lecture repo, it can read the git history — which is where the last-modified dates and the per-lecture changelog dropdown come from.

To install:

pip install quantecon-book-theme

and in _config.yml:

sphinx:
  config:
    html_theme: quantecon_book_theme

Note

The shared quantecon environment pins a specific version of quantecon-book-theme so html output stays consistent across projects — take the version from there rather than installing unpinned.

Notable features: git-derived last-modified date and changelog, launch buttons (BinderHub / Colab / JupyterHub), collapsible stderr output in notebook cells, configurable code highlighting (qetheme_code_style), colour schemes, multilingual support with a language switcher, and RTL layout.

quantecon-theme.mystmd#

The theme for the next generation of lecture sites. Jupyter Book 2 replaces Sphinx with the MyST engine, so the Sphinx theme above cannot come with it — quantecon-theme.mystmd is its replacement, and it is being brought to feature parity ahead of the migration.

It is a MyST site template built with Remix + Tailwind CSS, tracking the upstream jupyter-book/myst-theme book theme. It is not published to npm: each release attaches a quantecon-theme.zip, and projects pin that URL in myst.yml:

site:
  # Pinned theme release; bump the vX.Y.Z to take a new version
  template: https://github.com/QuantEcon/quantecon-theme.mystmd/releases/download/v2.2.0/quantecon-theme.zip

The current release is v2.2.0. lecture-wasm is the first lecture repo consuming it.

Note

The architectural constraint worth knowing. The Sphinx theme runs at build time inside the lecture repo and can shell out to git; the MyST theme runs as a runtime server over pre-built content JSON and never sees the repository. Anything derived from the source repo — git history, last-modified dates, computed launch paths — therefore cannot be computed by the theme, and must be injected upstream into each page’s frontmatter (by a MyST plugin, by mystmd itself, or by a CI step). The theme’s job is only to render it.

Launch buttons target Google Colab and a private JupyterHub, using the .notebooks repo-suffix convention by default and configurable under site.options in myst.yml. BinderHub is deliberately not offered — it proved unreliable in practice.

The remaining parity gaps are tracked in the repo’s PLAN.md — git-history headers, Thebe/live compute, configurable code highlighting and colour schemes, the language switcher, and RTL support.

See also

This repository was renamed from quantecon-theme-src, and supersedes the archived quantecon-theme (which bundled the built theme). Old links redirect, but use the current name in new writing.

quantecon-sphinx-theme#

Warning

In development — not ready for use. This theme has no tagged release and is not on PyPI, so there is nothing stable to depend on yet. If you are choosing a theme today, use quantecon-book-theme for a Jupyter Book 1 site, or quantecon-theme.mystmd if you are building on Jupyter Book 2 / mystmd.

A clean, content-focused Sphinx theme for scientific documentation — conceived as a brand-neutral alternative to quantecon-book-theme for smaller or non-core documentation sites.

Development has not resumed since the initial push. The whole repository was written in a single session on 24 February 2026: 15 commits, one author, no tags, no releases, and no PyPI package despite the pip install line in its README. The one downstream evaluation (lecture-python-programming#475) was closed unmerged, so it has no users.

Issue #6 asks for a go / no-go, and the strategic question gates everything else: the project has two conflicting purposes on record (a brand-neutral upstream base, versus a second QuantEcon theme for non-core series), its name depends on which one wins, and it targets Sphinx / Jupyter Book 1 just as the lecture repos move to Jupyter Book 2. Known defects — inline math, the RHS table of contents, a broken border, author/translator attribution — are tracked in issues #1–#4.

Working on a theme#

  • Both production themes are covered by Playwright visual-regression tests — see Visual regression testing for how to run them, read a failure, and regenerate baselines.

  • The linters, formatters, and build tooling used in each repo are indexed on Development tooling.

  • Changing a theme changes every site that consumes it. Pin-and-bump is deliberate: lecture repos take a new quantecon-book-theme version through the shared environment, and a new quantecon-theme.mystmd version by bumping the release URL in myst.yml.