A MkDocs theme built on GitHub's Primer design system — documentation that looks like it belongs on GitHub.
$ pip install mkdocs-primer# mkdocs.yml
theme:
name: primer- 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.
- 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 (frommkdocs-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) andmkdocs-static-i18n(translated pages get the right<html lang>and can use the header language selector). See Plugins.
| 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 footer bar. |
show_footer_generator |
true |
Show "Made with mkdocs-primer and MkDocs" in the footer. |
social |
[] |
Icon links shown in the footer. |
show_metadata |
true |
Render the metadata line under the page title. |
show_metadata_created |
true |
Show the created date. |
show_metadata_updated |
true |
Show the last-updated date. |
show_metadata_reading_time |
true |
Show the estimated reading time. |
show_metadata_authors |
true |
Show the authors. |
toc |
auto |
"Table of contents" 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.
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 vendorCI 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-themeIt 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.
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:offlineThis 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.ymlMIT. Vendored Primer CSS is MIT, Copyright (c) GitHub, Inc. — see mkdocs_primer/css/vendor/LICENSE.