mkdocs-primer
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-bodyrendering — 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
prettylightsvariables, so code colors follow the color mode. Works with bothpymdownx.highlightandcodehilite. - 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
admonitionextension ships no CSS and@primer/csshas no rule for it, so most themes render!!! noteundecorated. - 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.
- "Improve this page" footer, as in the Jekyll theme, with a "Last updated" line when
mkdocs-git-revision-date-localizedis enabled. - Native support for the plugins that need it:
mkdocs-section-index(section labels render as links) andmkdocs-static-i18n(translated pages get the right<html lang>and can use the header language selector). See Plugins.
Configuration
| Option | Default | Description |
|---|---|---|
logo |
null |
Image shown beside the site name, relative to docs_dir. |
favicon |
img/favicon.svg |
Site icon. |
locale |
en |
Language of the theme's own text. Catalogs ship for en, es, fr, hi, pt, ru and zh. |
include_sidebar |
true |
Render the navigation sidebar. |
show_footer |
true |
Render the "Improve this page" footer. |
toc |
auto |
"On this page" outline: auto, expanded, collapsed or hidden. |
color_mode |
auto |
Initial color mode: auto, light or dark. |
light_theme |
light |
Primer theme used in light mode. |
dark_theme |
dark |
Primer theme used in dark mode. |
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.
1 maintainer
Release files for mkdocs-primer 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mkdocs_primer-0.3.1.tar.gz | 132.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mkdocs_primer-0.3.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 295.1 kB
Release files / mkdocs_primer-0.3.1.tar.gz
| Download URL | mkdocs_primer-0.3.1.tar.gz |
|---|---|
| Size | 132.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d33cc458df8f806e7d0bb2afddf613a725cde0ade9b42bbdce3574cd545f624e
|
|
BLAKE2b-256 checksum How to use checksums |
08c51531d3d7d9217eec709ec6b6a4c83a7573bc773e4e772264785b082b86e1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / mkdocs_primer-0.3.1-py3-none-any.whl
| Download URL | mkdocs_primer-0.3.1-py3-none-any.whl |
|---|---|
| Size | 162.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a1906d868718eca8099d2f319a1aa53917505220d95880d5be45264d98b99b5e
|
|
BLAKE2b-256 checksum How to use checksums |
ddb73d427761a8550635d5f624b8ce7896ef201a158369ab98acb0eed07f3f37
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency log
