# Home

**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.

```sh
pip install mkdocs-sumi
```

```yaml title="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
```

- [Get started](docs/start/install/)
- [See the components](docs/write/)

## 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**](docs/write/): 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**](docs/design/): Fonts, icons, search, Mermaid and KaTeX ship with the theme. Build offline, host anywhere, keep working behind a firewall.
- [**Written for agents too**](docs/ai/): Every page has a clean `.md` twin, announced in its ``. The site has an `llms.txt`. One click copies a page as Markdown.
- [**Search that is also a command palette**](docs/customize/search/): Press ⌘K to search every heading — including Chinese and Japanese — or type `>` to switch theme, copy, print and more.
- [**Docs, blog, landing, releases**](docs/pages/landing/): 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**](docs/start/migrate/): Admonitions, `pymdownx` tabs and details, `mike` versions and Material's `extra` keys all keep working.

## 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.

````markdown title="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
```
````

- **0** runtime services or CDNs
- **16** native-Markdown components
- **11 KB** core script, gzipped. No framework.
- **2** interface languages: English, 中文

## 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](docs/)
- [Star on GitHub](https://github.com/mkdocs-ng/mkdocs-sumi)