MkDocs Primer Theme

A MkDocs theme built on GitHub's Primer design system — documentation that looks like it belongs on GitHub.

Install

$ pip install mkdocs-primer

# mkdocs.yml
theme:
  name: primer

Features

• GitHub's .markdown-body rendering — the same typography, tables and code chrome as a README on github.com.
• Light and dark modes via Primer's color primitives, with an auto/light/dark toggle that remembers the visitor's choice. Defaults to following the OS.
• Syntax highlighting mapped onto Primer's prettylights variables, so code colors follow the color mode. Works with both pymdownx.highlight and codehilite.
• Copy buttons for Pygments code blocks and an accessible back-to-top control that respects reduced-motion preferences.
• Admonitions styled after GitHub's alerts. The admonition extension ships no CSS and @primer/css has no rule for it, so most themes render !!! note undecorated.
• Sidebar navigation with unlimited nesting, collapsed down to the section the reader is in, plus a breadcrumb trail, prev/next links, a search results page, and a 404 page.
• Optional Workbox-powered offline support for sites served over HTTPS.
• A footer bar under the whole layout: copyright and the "Improve this page" link from the Jekyll theme on one line, a "Made with" line under it, and a row of social links driven by a config list, drawn from a curated set of Simple Icons.
• A metadata byline under the page title with created/updated dates (from mkdocs-git-revision-date-localized), an estimated reading time computed from the page's word count, and authors (from mkdocs-git-authors) — no blog plugin required. The line and each of its fields are independently toggleable.
• Native support for the plugins that need it: mkdocs-section-index (section labels render as links) and mkdocs-static-i18n (translated pages get the right <html lang> and can use the header language selector). See Plugins.

Configuration

For GitHub's hover anchors next to headings, enable the toc extension with a leading permalink carrying Primer's anchor class:

markdown_extensions:
  - toc:
      permalink: ""
      permalink_class: anchor
      permalink_leading: true

(The empty permalink is deliberate — the theme supplies the octicon, and it keeps a stray ¶ out of your search results.)

See the documentation for the rest.

Development

For the package release procedure, see RELEASING.md.

The CSS under mkdocs_primer/css/vendor/ is copied from @primer/css and @primer/primitives and committed, so installing the theme needs no Node toolchain. To refresh it after bumping a version in package.json:

$ npm install
$ npm run vendor

CI fails if those committed files drift from the pinned versions.

To preview the demo site:

$ pip install -e . -r requirements-docs.txt
$ mkdocs serve --watch-theme

It is served at http://127.0.0.1:8000/mkdocs-primer/ — site_url gives the site that path, and the dev server mounts it there. --watch-theme is what makes the loop work while editing the theme: without it MkDocs watches docs/ and mkdocs.yml only, and a change under mkdocs_primer/ never reaches the browser.

VS Code users get this from .vscode/: Run Task → Serve the demo site, or F5 for the same thing with a browser attached, at full width or under the theme's 1012px breakpoint. Build every site CI builds runs the four strict builds below in order.

Offline build

The theme can register a service worker generated by Workbox. Enable offline: true under theme, build the site, then run workbox generateSW against the output directory. The included configuration is a complete example:

$ npm install
$ npm run build:offline

This precaches the generated site for offline use after the first visit. Service workers require HTTPS (or localhost), so this does not make a file:// distribution offline-capable.

The demo site doubles as the theme's plugin compatibility test: mkdocs.yml enables every plugin that needs something from a theme, and CI builds it with --strict. Those plugins need Python 3.10+, so CI checks the theme's own floor of 3.9 against a plugin-free site.

A few plugins cannot share that config — rss and gen-files both break under static-i18n, and Mermaid breaks under minify_html — so they get their own sites under examples/, published beside the main one and described on the Examples page. Build them after it, since mkdocs build cleans site/:

$ mkdocs build --strict
$ mkdocs build --strict -f examples/rss/mkdocs.yml
$ mkdocs build --strict -f examples/gen-files/mkdocs.yml
$ mkdocs build --strict -f examples/diagrams/mkdocs.yml

License

MIT. Vendored Primer CSS is MIT, Copyright (c) GitHub, Inc. — see mkdocs_primer/css/vendor/LICENSE.