On this page

Theme options#

Theme options are set under theme: in mkdocs.yml. All of them are optional.

mkdocs.yml

theme:
  name: sumi
  palette: auto
  accent: indigo
  logo: assets/logo.svg
  announcement: 'Sumi 0.1 is out — <a href="blog/">read the post</a>'

Options#

palettestringDefault auto

light, dark or auto (follow the operating system). Readers can switch at any time; their choice is remembered.

accentstringDefault vermilion

The colour of links, highlights and the active tab: vermilion, indigo, moss, plum, ochre, teal, ink, or any CSS colour.

localestringDefault en

The interface language: en, zh, zh_TW. See Languages.

logostring

An image in docs/ for the header. The Sumi mark is used if unset.

logo_darkstring

A second header image for the dark palette. logo is used in both if unset.

faviconstring

An image in docs/ for the browser tab.

social_imagestring

The preview image shown when a page is shared on X, Slack, Mastodon and the like: an image in docs/ (about 1200×630, needs site_url) or a full URL. A page can use its own with image: in its front matter.

brandstringDefault site_name

HTML for the header brand, e.g. "MkDocs<b>ng</b>".

announcementstring

HTML for a dismissible bar above the header. A new message reappears for readers who dismissed an older one.

navigation_tabsbooleanDefault true

Show top-level sections as tabs in the header. When false, the whole navigation is in the sidebar.

toc_depthintegerDefault 3

The deepest heading level in the page table of contents.

hidelistDefault []

Parts to hide on every page: toc, sidebar, breadcrumbs, actions, pager, footer.

version_providerstring

mike to show a version menu. See Navigation.

repo_iconstring

Override the repository icon, e.g. brand-gitlab. Detected from repo_url by default.

keyboardbooleanDefault true

Enable single-key shortcuts. ⌘ K always works.

creditbooleanDefault true

Show "Built with MkDocs and Sumi" in the footer.

Accent colours#

Name	Light	Dark
`vermilion`	`#c4432b`	`#ef7258`
`indigo`	`#2f5d93`	`#86b4ea`
`moss`	`#4b6b2f`	`#9ccc6e`
`plum`	`#7a3b74`	`#dc93d4`
`ochre`	`#9a6512`	`#e7b45a`
`teal`	`#1f6f6a`	`#6fd0c6`
`ink`	`#2a2926`	`#e8e4dc`

A named accent has a tuned variant for dark mode. A custom CSS colour is used in both modes.

Per-page options#

Front matter on a page can change its layout:

hide

Like the theme option, for one page: hide: [toc, pager]. navigation is accepted as an alias for sidebar.

layout

wide removes both sidebars for a full-width page.

template

landing.html, blog.html or releases.html. See Pages.

description

Used for the <meta name="description">, link previews, cards and the blog index.

mkdocs.yml

copyright: © 2026 The MkDocs NG project
extra:
  social:
    - icon: brand-github
      link: https://github.com/mkdocs-ng
      name: GitHub
    - icon: fontawesome/brands/x-twitter   # Material names work too
      link: https://x.com/mkdocs

Custom CSS#

Every colour, font and size is a CSS variable. Add a stylesheet with extra_css:

docs/assets/extra.css

:root {
  --sumi-font: "IBM Plex Sans", system-ui, sans-serif;
  --sumi-content-w: 820px;
}
[data-theme="dark"] {
  --sumi-bg: #0f1115;
}

mkdocs.yml

extra_css:
  - assets/extra.css

Theme options#

Options#

Accent colours#

Per-page options#

Footer and social links#

Custom CSS#