Sumi

Markdown in. Beautiful docs out.

Documentation · 中文文档 · Components · Releases

Sumi is a documentation theme for MkDocs NG. It turns a folder of plain Markdown into a complete project site — docs, landing page, blog, release downloads and a print edition — without Node.js, a CDN or a hosted service.

Quick start

pip install mkdocs-sumi

# mkdocs.yml
theme:
  name: sumi

plugins:
  - search
  - llms_txt   # optional: llms.txt and a Markdown copy of every page
  - sumi

mkdocs serve

Highlights

• Components in native Markdown. Callouts are > [!NOTE], steps are a numbered list with {.steps}, tabs are fences with {tab="…"}. Your source still reads well on GitHub.
• Local-first. Fonts, 2 000 icons, search, Mermaid and KaTeX ship with the theme. Mermaid and KaTeX load only on pages that use them.
• Search as a command palette. ⌘ K searches every heading, including Chinese and Japanese, and runs commands.
• Written for agents too. Every page has a Markdown twin announced in <head>, plus llms.txt and Copy as Markdown.
• One design for the whole project site. Data-driven landing pages, a blog with tags and an Atom feed, a releases page with checksums, and a whole-site print edition.
• Keeps your MkDocs content. Admonitions, pymdownx tabs and details, mike versions and Material's extra keys keep working.

Development

pip install -e ".[test]"
pytest                       # unit and build tests
pip install playwright && playwright install chromium
pytest tests/test_browser.py # browser tests against the docs site
mkdocs serve                 # the docs site is the visual regression suite

License

Sumi is part of the MkDocs NG project.

Apache 2.0. See NOTICE for the licenses of bundled fonts, icons and libraries.