# Sumi

> 一个现代、本地优先的 MkDocs 文档主题。写 Markdown，出好文档。

## Pages

- [首页](https://sumi.mkdocs-ng.org/zh/index.md): 一个现代、本地优先的 MkDocs 文档主题。
- [发布记录](https://sumi.mkdocs-ng.org/zh/releases.md): Sumi versions, release notes and downloads.
- [博客](https://sumi.mkdocs-ng.org/zh/blog/index.md): News and notes from the Sumi project.

## 文档

- [Sumi 文档](https://sumi.mkdocs-ng.org/zh/docs/index.md): Sumi 是什么、包含哪些功能，以及从哪里开始。
- [面向 AI 与智能体](https://sumi.mkdocs-ng.org/zh/docs/ai.md): Sumi 如何为 AI 智能体发布每个页面：Markdown 副本、llms.txt、发现链接和一键复制。
- [设计原则](https://sumi.mkdocs-ng.org/zh/docs/design.md): Sumi 背后的原则，以及由此带来的取舍。

## 文档 / 快速开始

- [安装](https://sumi.mkdocs-ng.org/zh/docs/start/install.md): 安装 Sumi，并在 MkDocs 项目中启用它。
- [第一个站点](https://sumi.mkdocs-ng.org/zh/docs/start/first-site.md): 用 Sumi 从空文件夹开始搭建并部署一个新站点。
- [从 Material 迁移](https://sumi.mkdocs-ng.org/zh/docs/start/migrate.md): 把现有站点从 Material for MkDocs 或其他主题迁移到 Sumi。

## 文档 / 写作

- [用 Sumi 写作](https://sumi.mkdocs-ng.org/zh/docs/write/index.md): Sumi 为 Markdown 增加的所有组件概览，以及它们共同遵循的一条规则。
- [提示框](https://sumi.mkdocs-ng.org/zh/docs/write/callouts.md): Notes, tips and warnings written as GitHub-style blockquotes.
- [代码块](https://sumi.mkdocs-ng.org/zh/docs/write/code.md): Syntax-highlighted code blocks with file names, line numbers and a copy button.
- [标签页](https://sumi.mkdocs-ng.org/zh/docs/write/tabs.md): Show alternatives — operating systems, languages, package managers — as tabs.
- [步骤](https://sumi.mkdocs-ng.org/zh/docs/write/steps.md): Turn a numbered list into a step-by-step procedure.
- [卡片](https://sumi.mkdocs-ng.org/zh/docs/write/cards.md): A grid of linked cards for section landing pages.
- [字段](https://sumi.mkdocs-ng.org/zh/docs/write/fields.md): Reference tables for options, parameters and API fields.
- [表格](https://sumi.mkdocs-ng.org/zh/docs/write/tables.md): Tables with captions, full width, compact and striped variants.
- [图片与插图](https://sumi.mkdocs-ng.org/zh/docs/write/images.md): Images, figures with captions, zoom, and images for light and dark mode.
- [图库](https://sumi.mkdocs-ng.org/zh/docs/write/gallery.md): A responsive grid of images with captions, from a plain list of images.
- [文件树](https://sumi.mkdocs-ng.org/zh/docs/write/filetree.md): Draw a project layout from the output of tree, with icons and comments.
- [图表](https://sumi.mkdocs-ng.org/zh/docs/write/diagrams.md): Flowcharts, sequence diagrams and more with Mermaid, loaded only where used.
- [数据图与思维导图](https://sumi.mkdocs-ng.org/zh/docs/write/charts.md): Charts from YAML with Apache ECharts, and mind maps from a Markdown outline.
- [数学公式](https://sumi.mkdocs-ng.org/zh/docs/write/math.md): Inline and display formulas typeset by a bundled copy of KaTeX.
- [按键与图标](https://sumi.mkdocs-ng.org/zh/docs/write/keys-icons.md): Keyboard shortcuts and 2 000 inline icons.
- [徽章](https://sumi.mkdocs-ng.org/zh/docs/write/badges.md): Small status labels next to a feature name, a version or a table cell.

## 文档 / 页面类型

- [首页](https://sumi.mkdocs-ng.org/zh/docs/pages/landing.md): Build a product home page from front matter — hero, features, code, stats, steps, FAQ and call to action.
- [博客](https://sumi.mkdocs-ng.org/zh/docs/pages/blog.md): A blog with authors, tags, reading time and an Atom feed — from a folder of Markdown files.
- [发布与下载](https://sumi.mkdocs-ng.org/zh/docs/pages/releases.md): A downloads and release notes page with checksums, generated from YAML.
- [打印版](https://sumi.mkdocs-ng.org/zh/docs/pages/print.md): The whole site as one printable page, and clean printing of any single page.

## 文档 / 自定义

- [主题选项](https://sumi.mkdocs-ng.org/zh/docs/customize/theme.md): Every theme option — colours, logo, header, announcement bar, page chrome and footer.
- [插件选项](https://sumi.mkdocs-ng.org/zh/docs/customize/plugin.md): Options of the sumi plugin — components, blog, print edition, Git dates and AI links.
- [导航](https://sumi.mkdocs-ng.org/zh/docs/customize/navigation.md): How tabs, the sidebar, section index pages, breadcrumbs, versions and languages are built.
- [搜索与命令](https://sumi.mkdocs-ng.org/zh/docs/customize/search.md): Local full-text search, CJK support, and the command palette.
- [语言与中文排版](https://sumi.mkdocs-ng.org/zh/docs/customize/i18n.md): 界面语言、中文排版，以及如何发布中英文双语站点。
- [覆盖模板](https://sumi.mkdocs-ng.org/zh/docs/customize/overrides.md): Override templates and blocks with MkDocs' custom_dir.
- [面向插件作者](https://sumi.mkdocs-ng.org/zh/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/zh/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/zh/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.