Introducing Sumi#

Today we are releasing Sumi 0.1, a documentation theme for MkDocs NG. It is the first theme built by the MkDocs NG project, and it is meant to be a complete answer to "how should our docs look?" for engineering teams.

Why another theme#

MkDocs made documentation easy: write Markdown, run one command, get a site. Over the years, good-looking MkDocs sites came to depend on a long list of extensions, each with its own syntax. Content written for one theme stopped making sense anywhere else.

Sumi goes back to the original promise. It adds twelve components, each written in plain Markdown — a callout is a blockquote, steps are a numbered list, tabs are labelled code fences. Your source still reads well on GitHub and in a terminal.

What is in 0.1#

A full docs layout with tabs, a sidebar, an on-page table of contents and previous / next links.
Search as a command palette, local and CJK-aware, opened with Cmd+K.
Landing, blog, releases and print page types sharing one design.
A Markdown copy of every page and llms.txt links for AI agents.
No CDN: fonts, icons, Mermaid and KaTeX ship with the theme.

Try it#

pip install mkdocs-sumi

mkdocs.yml

theme:
  name: sumi
plugins:
  - search
  - sumi

Then read the documentation — this site is built with Sumi, and every page doubles as an example. Feedback and bug reports are welcome on GitHub.

Thanks#

Sumi's principles owe a lot to Oink by Feng Ruohang, which showed how much a documentation distribution can do with plain Markdown and no external services.

Xianpeng Shen

MkDocs NG maintainer