# Sumi

> A modern, local-first documentation theme for MkDocs. Markdown in, beautiful docs out.

## Pages

- [Home](https://sumi.mkdocs-ng.org/index.md): A modern, local-first documentation theme for MkDocs.
- [Releases](https://sumi.mkdocs-ng.org/releases.md): Sumi versions, release notes and downloads.
- [Blog](https://sumi.mkdocs-ng.org/blog/index.md): News and notes from the Sumi project.

## Docs

- [Sumi documentation](https://sumi.mkdocs-ng.org/docs/index.md): What Sumi is, what it includes, and where to start.
- [AI and agents](https://sumi.mkdocs-ng.org/docs/ai.md): How Sumi publishes every page for AI agents — Markdown copies, llms.txt, discovery links and one-click copying.
- [Design principles](https://sumi.mkdocs-ng.org/docs/design.md): The principles behind Sumi, and the trade-offs they lead to.

## Docs / Getting started

- [Install](https://sumi.mkdocs-ng.org/docs/start/install.md): Install Sumi and enable it in an MkDocs project.
- [Your first site](https://sumi.mkdocs-ng.org/docs/start/first-site.md): Create a new site with Sumi, from an empty folder to a deployed build.
- [Migrate from Material](https://sumi.mkdocs-ng.org/docs/start/migrate.md): Move an existing site from Material for MkDocs or another theme to Sumi.

## Docs / Writing

- [Writing with Sumi](https://sumi.mkdocs-ng.org/docs/write/index.md): An overview of every component Sumi adds to Markdown, and the one rule they all follow.
- [Callouts](https://sumi.mkdocs-ng.org/docs/write/callouts.md): Notes, tips and warnings written as GitHub-style blockquotes.
- [Code blocks](https://sumi.mkdocs-ng.org/docs/write/code.md): Syntax-highlighted code blocks with file names, line numbers and a copy button.
- [Tabs](https://sumi.mkdocs-ng.org/docs/write/tabs.md): Show alternatives — operating systems, languages, package managers — as tabs.
- [Steps](https://sumi.mkdocs-ng.org/docs/write/steps.md): Turn a numbered list into a step-by-step procedure.
- [Cards](https://sumi.mkdocs-ng.org/docs/write/cards.md): A grid of linked cards for section landing pages.
- [Fields](https://sumi.mkdocs-ng.org/docs/write/fields.md): Reference tables for options, parameters and API fields.
- [Tables](https://sumi.mkdocs-ng.org/docs/write/tables.md): Tables with captions, full width, compact and striped variants.
- [Images and figures](https://sumi.mkdocs-ng.org/docs/write/images.md): Images, figures with captions, zoom, and images for light and dark mode.
- [Galleries](https://sumi.mkdocs-ng.org/docs/write/gallery.md): A responsive grid of images with captions, from a plain list of images.
- [File trees](https://sumi.mkdocs-ng.org/docs/write/filetree.md): Draw a project layout from the output of tree, with icons and comments.
- [Diagrams](https://sumi.mkdocs-ng.org/docs/write/diagrams.md): Flowcharts, sequence diagrams and more with Mermaid, loaded only where used.
- [Charts and mind maps](https://sumi.mkdocs-ng.org/docs/write/charts.md): Charts from YAML with Apache ECharts, and mind maps from a Markdown outline.
- [Math](https://sumi.mkdocs-ng.org/docs/write/math.md): Inline and display formulas typeset by a bundled copy of KaTeX.
- [Keys and icons](https://sumi.mkdocs-ng.org/docs/write/keys-icons.md): Keyboard shortcuts and 2 000 inline icons.
- [Badges](https://sumi.mkdocs-ng.org/docs/write/badges.md): Small status labels next to a feature name, a version or a table cell.

## Docs / Pages

- [Landing pages](https://sumi.mkdocs-ng.org/docs/pages/landing.md): Build a product home page from front matter — hero, features, code, stats, steps, FAQ and call to action.
- [Blog](https://sumi.mkdocs-ng.org/docs/pages/blog.md): A blog with authors, tags, reading time and an Atom feed — from a folder of Markdown files.
- [Releases and downloads](https://sumi.mkdocs-ng.org/docs/pages/releases.md): A downloads and release notes page with checksums, generated from YAML.
- [Print edition](https://sumi.mkdocs-ng.org/docs/pages/print.md): The whole site as one printable page, and clean printing of any single page.

## Docs / Customize

- [Theme options](https://sumi.mkdocs-ng.org/docs/customize/theme.md): Every theme option — colours, logo, header, announcement bar, page chrome and footer.
- [Plugin options](https://sumi.mkdocs-ng.org/docs/customize/plugin.md): Options of the sumi plugin — components, blog, print edition, Git dates and AI links.
- [Navigation](https://sumi.mkdocs-ng.org/docs/customize/navigation.md): How tabs, the sidebar, section index pages, breadcrumbs, versions and languages are built.
- [Search and commands](https://sumi.mkdocs-ng.org/docs/customize/search.md): Local full-text search, CJK support, and the command palette.
- [Languages and versions](https://sumi.mkdocs-ng.org/docs/customize/i18n.md): Interface languages, CJK typography and translating a site.
- [Overriding templates](https://sumi.mkdocs-ng.org/docs/customize/overrides.md): Override templates and blocks with MkDocs' custom_dir.
- [For plugin authors](https://sumi.mkdocs-ng.org/docs/customize/plugin-authors.md): How to make an MkDocs plugin, or CSS and templates written for Material for MkDocs, work well with Sumi.

## Other pages

- [Introducing Sumi](https://sumi.mkdocs-ng.org/blog/posts/2026-11-01-introducing-sumi.md): Sumi 0.1 is a local-first documentation theme for MkDocs that keeps your content in plain Markdown and publishes it for people and agents alike.
- [Keeping diagrams off the critical path](https://sumi.mkdocs-ng.org/blog/posts/2026-11-02-diagrams-off-the-critical-path.md): A page with one Mermaid diagram used to make readers wait ten seconds on a phone. Here is what we changed, and the numbers before and after.