Local-first · for MkDocs NG

Markdown in.
Beautiful docs out.

Sumi is a documentation theme for MkDocs that keeps your content plain Markdown, ships every asset with your site, and writes pages that people and AI agents can read.

Get started See the components

$pip install mkdocs-sumi

mkdocs.yml

site_name: My Project

theme:
  name: sumi          # paper, ink and a vermilion seal

plugins:
  - search            # ⌘K search, CJK-aware
  - llms_txt          # a Markdown copy of every page
  - sumi              # components, blog, print edition

Why Sumi

Everything engineering docs need. Nothing they don't.

Built in, kept local, and loaded only on the pages that use it.

Components in plain Markdown

Callouts are > [!NOTE], steps are a list with {.steps}, tabs are fences with {tab=…}. Your source still reads well on GitHub.

Local-first, no CDN

Fonts, icons, search, Mermaid and KaTeX ship with the theme. Build offline, host anywhere, keep working behind a firewall.

Written for agents too

Every page has a clean .md twin, announced in its <head>. The site has an llms.txt. One click copies a page as Markdown.

Search that is also a command palette

Press ⌘K to search every heading — including Chinese and Japanese — or type > to switch theme, copy, print and more.

Docs, blog, landing, releases

One design language for the whole project site, from a data-driven home page to an RSS-ready blog and a download page.

Keeps your MkDocs content

Admonitions, pymdownx tabs and details, mike versions and Material's extra keys all keep working.

Native Markdown

Write it once. Read it anywhere.

Sumi never asks you to write a private dialect. Each component is a blockquote, a list, a table or a fence with one attribute line — so the same file renders in Sumi, on GitHub, and in the Markdown copy an agent reads.

• No MDX, no shortcodes, no imports in your pages.
• Every component degrades to readable Markdown and prints fully expanded.
• Mermaid and KaTeX load only on pages that contain a diagram or a formula.

docs/install.md

> [!TIP]
> Use a virtual environment.

1. Install the theme
2. Enable the plugin
3. Run `mkdocs serve`
{.steps}

```sh {tab="Linux"}
pip install mkdocs-sumi
```

```powershell {tab="Windows"}
py -m pip install mkdocs-sumi
```

runtime services or CDNs

0

native-Markdown components

16

core script, gzipped. No framework.

11 KB

interface languages: English, 中文

2

Three minutes

From empty folder to a published site.

1. Install

   pip install mkdocs-sumi — it brings MkDocs with it.

2. Configure

   Set theme: sumi and add the sumi plugin to mkdocs.yml.

3. Write

   Run mkdocs serve and write Markdown. Sumi takes care of the rest.

4. Publish

   mkdocs build produces plain static files for any host.

Your docs deserve good paper.

Sumi is free and open source under the Apache 2.0 license.

Read the docs Star on GitHub