Metadata-Version: 2.5
Name: mkdocs-sumi
Version: 0.1.1
Summary: Sumi: a modern, local-first documentation theme for MkDocs.
Project-URL: Documentation, https://mkdocs-ng.github.io/mkdocs-sumi/
Project-URL: Source, https://github.com/mkdocs-ng/mkdocs-sumi
Project-URL: Issues, https://github.com/mkdocs-ng/mkdocs-sumi/issues
Project-URL: Changelog, https://mkdocs-ng.github.io/mkdocs-sumi/releases/
Author-email: Xianpeng Shen <xianpeng.shen@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: MkDocs
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: markdown>=3.6
Requires-Dist: mkdocs-ng>=1.9
Requires-Dist: pygments>=2.16
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://mkdocs-ng.github.io/mkdocs-sumi/">
    <img src="https://raw.githubusercontent.com/mkdocs-ng/mkdocs-sumi/main/docs/assets/sumi-mark.svg" width="72" alt="Sumi">
  </a>
</p>

<h1 align="center">Sumi</h1>

<p align="center">
  <strong>Markdown in. Beautiful docs out.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/mkdocs-sumi/"><img src="https://img.shields.io/pypi/v/mkdocs-sumi.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/mkdocs-sumi/"><img src="https://img.shields.io/pypi/pyversions/mkdocs-sumi.svg" alt="Python versions"></a>
  <a href="https://github.com/mkdocs-ng/mkdocs-sumi/actions/workflows/ci.yml"><img src="https://github.com/mkdocs-ng/mkdocs-sumi/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/mkdocs-ng/mkdocs-sumi/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/mkdocs-sumi.svg" alt="License"></a>
</p>

<p align="center">
  <a href="https://mkdocs-ng.github.io/mkdocs-sumi/">Documentation</a> ·
  <a href="https://mkdocs-ng.github.io/mkdocs-sumi/docs/write/">Components</a> ·
  <a href="https://mkdocs-ng.github.io/mkdocs-sumi/releases/">Releases</a>
</p>

Sumi is a documentation theme for [MkDocs NG](https://github.com/mkdocs-ng/mkdocs). 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

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

```yaml
# mkdocs.yml
theme:
  name: sumi

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

```sh
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.** <kbd>⌘</kbd> <kbd>K</kbd> 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

```sh
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](https://github.com/mkdocs-ng) project.

Apache 2.0. See [NOTICE](https://github.com/mkdocs-ng/mkdocs-sumi/blob/main/NOTICE) for the licenses of bundled fonts, icons and libraries.
