mkdocs-sumi 0.1.0__tar.gz

mkdocs_sumi-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.egg-info/
+/site/
+/dist/
+/build/
+.pytest_cache/
+.venv/

mkdocs_sumi-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mkdocs_sumi-0.1.0/NOTICE

@@ -0,0 +1,23 @@
+Sumi
+Copyright 2026 The MkDocs-ng contributors
+
+This product includes software and assets developed by third parties,
+distributed under their own licenses. The license texts are included next
+to each component in the package.
+
+- Inter (src/mkdocs_sumi/theme/assets/fonts) — SIL Open Font License 1.1,
+  Copyright 2016 The Inter Project Authors.
+- JetBrains Mono (src/mkdocs_sumi/theme/assets/fonts) — SIL Open Font
+  License 1.1, Copyright 2020 The JetBrains Mono Project Authors.
+- Lucide icons (src/mkdocs_sumi/vendor/icons/lucide.json) — ISC License,
+  Copyright Lucide Contributors; portions MIT, Copyright Cole Bemis (Feather).
+- Simple Icons (src/mkdocs_sumi/vendor/icons/brands.json) — CC0 1.0.
+  Brand icons are trademarks of their respective owners.
+- Mermaid (src/mkdocs_sumi/vendor/mermaid) — MIT License,
+  Copyright Knut Sveidqvist.
+- KaTeX (src/mkdocs_sumi/vendor/katex) — MIT License,
+  Copyright Khan Academy and other contributors.
+
+Sumi's design principles were inspired by Oink (https://github.com/pgsty/oink),
+a documentation distribution for Hugo by Feng Ruohang. No code from Oink is
+included.

mkdocs_sumi-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: mkdocs-sumi
+Version: 0.1.0
+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
+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: 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
+
+# Sumi
+
+**Markdown in. Beautiful docs out.**
+
+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.
+
+[Documentation](https://mkdocs-ng.github.io/mkdocs-sumi/) · [Components](https://mkdocs-ng.github.io/mkdocs-sumi/docs/write/) · [Releases](https://mkdocs-ng.github.io/mkdocs-sumi/releases/)
+
+## 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
+
+Apache 2.0. See [NOTICE](NOTICE) for the licenses of bundled fonts, icons and libraries.

mkdocs_sumi-0.1.0/README.md

@@ -0,0 +1,51 @@
+# Sumi
+
+**Markdown in. Beautiful docs out.**
+
+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.
+
+[Documentation](https://mkdocs-ng.github.io/mkdocs-sumi/) · [Components](https://mkdocs-ng.github.io/mkdocs-sumi/docs/write/) · [Releases](https://mkdocs-ng.github.io/mkdocs-sumi/releases/)
+
+## 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
+
+Apache 2.0. See [NOTICE](NOTICE) for the licenses of bundled fonts, icons and libraries.

mkdocs_sumi-0.1.0/docs/assets/sumi-mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect x="1" y="1" width="30" height="30" rx="8" fill="#c4432b"/><path d="M22.6 10.2a9 9 0 1 0 1.9 7.6" fill="none" stroke="#fff" stroke-width="3.1" stroke-linecap="round"/><circle cx="23.7" cy="13.2" r="1.7" fill="#fff"/></svg>

mkdocs_sumi-0.1.0/docs/blog/.authors.yml

@@ -0,0 +1,6 @@
+authors:
+  xianpeng:
+    name: Xianpeng Shen
+    description: MkDocs-ng maintainer
+    avatar: https://github.com/shenxianpeng.png
+    url: https://github.com/shenxianpeng

mkdocs_sumi-0.1.0/docs/blog/index.md

@@ -0,0 +1,7 @@
+---
+description: News and notes from the Sumi project.
+---
+
+# Blog
+
+Releases, design notes and guides from the Sumi project.

mkdocs_sumi-0.1.0/docs/blog/posts/2026-11-01-introducing-sumi.md

@@ -0,0 +1,46 @@
+---
+date: 2026-11-01
+authors: [xianpeng]
+tags: [release, design]
+description: 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.
+---
+
+# Introducing Sumi
+
+Today we are releasing Sumi 0.1, a documentation theme for MkDocs-ng. It is the first theme built by the MkDocs-ng project, and it is meant to be a complete answer to "how should our docs look?" for engineering teams.
+
+<!-- more -->
+
+## Why another theme
+
+MkDocs made documentation easy: write Markdown, run one command, get a site. Over the years, good-looking MkDocs sites came to depend on a long list of extensions, each with its own syntax. Content written for one theme stopped making sense anywhere else.
+
+Sumi goes back to the original promise. It adds twelve components, each written in plain Markdown — a callout is a blockquote, steps are a numbered list, tabs are labelled code fences. Your source still reads well on GitHub and in a terminal.
+
+## What is in 0.1
+
+- :lucide-book-open: **A full docs layout** with tabs, a sidebar, an on-page table of contents and previous / next links.
+- :lucide-command: **Search as a command palette**, local and CJK-aware, opened with ++Cmd+K++.
+- :lucide-layout-template: **Landing, blog, releases and print** page types sharing one design.
+- :lucide-sparkles: **A Markdown copy of every page** and `llms.txt` links for AI agents.
+- :lucide-hard-drive: **No CDN**: fonts, icons, Mermaid and KaTeX ship with the theme.
+
+## Try it
+
+```sh
+pip install mkdocs-sumi
+```
+
+```yaml title="mkdocs.yml"
+theme:
+  name: sumi
+plugins:
+  - search
+  - sumi
+```
+
+Then read [the documentation](../../docs/index.md) — this site is built with Sumi, and every page doubles as an example. Feedback and bug reports are welcome on [GitHub](https://github.com/mkdocs-ng/mkdocs-sumi/issues).
+
+## Thanks
+
+Sumi's principles owe a lot to [Oink](https://github.com/pgsty/oink) by Feng Ruohang, which showed how much a documentation distribution can do with plain Markdown and no external services.

mkdocs_sumi-0.1.0/docs/docs/ai.md

@@ -0,0 +1,63 @@
+---
+description: How Sumi publishes every page for AI agents — Markdown copies, llms.txt, discovery links and one-click copying.
+---
+
+# Docs for people and agents
+
+More and more readers of documentation are not people. Coding agents, assistants and search tools read your pages to answer questions about your project, and they read HTML badly: navigation, scripts and styling are noise to them. Sumi publishes every page twice — as a page for people and as plain Markdown for programs.
+
+## What Sumi publishes
+
+| Output | Where | For |
+| --- | --- | --- |
+| HTML page | `guide/install/` | People |
+| Markdown copy | `guide/install.md` | Agents reading one page |
+| `llms.txt` | site root | Agents discovering the site |
+| `llms-full.txt` | site root | Agents loading everything at once (opt-in) |
+| Atom feed | `blog/feed.xml` | Feed readers |
+| Print edition | `print/` | Paper, PDF, offline reading |
+{caption="Every output is a static file. None requires a server."}
+
+The Markdown copy and `llms.txt` come from the `llms_txt` plugin that ships with [MkDocs-ng](https://github.com/mkdocs-ng/mkdocs). Enable it next to `sumi`:
+
+```yaml title="mkdocs.yml"
+site_url: https://example.com/docs/   # needed for absolute links in llms.txt
+
+plugins:
+  - search
+  - llms_txt:
+      full_output: true   # also write llms-full.txt
+  - sumi
+```
+
+Try it on this site: open [llms.txt](https://mkdocs-ng.github.io/mkdocs-sumi/llms.txt), or choose **View as Markdown** in the menu at the top of this page.
+
+## Discovery
+
+Each HTML page announces its Markdown copy in `<head>`:
+
+```html
+<link rel="alternate" type="text/markdown" href="ai.md" title="Markdown">
+<link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt">
+```
+
+An agent that lands on any page can find the clean version without guessing URLs.
+
+## Copy as Markdown
+
+The **Copy as Markdown** button at the top of each page copies the page source — the same text an agent reads — so you can paste it into a chat. The menu next to it can also open the Markdown copy, print the page and, if you enable it, open the page in an assistant:
+
+```yaml title="mkdocs.yml"
+plugins:
+  - sumi:
+      assistant_links: [claude, chatgpt]
+```
+
+> [!NOTE]
+> Assistant links are off by default: they send the page address to a third-party service when clicked.
+
+## Why native Markdown matters here
+
+Components written in a private syntax — MDX, shortcodes, HTML widgets — reach an agent either as raw markup it has to interpret or not at all. Sumi's components are ordinary Markdown with an attribute line, so the Markdown copy reads naturally: a callout is a quote, steps are a numbered list, tabs are consecutive code blocks with labels.
+
+Landing pages are the one place where content lives in front matter. For those pages, Sumi writes a Markdown copy that lists the hero, features, steps and questions as headings and lists.

mkdocs_sumi-0.1.0/docs/docs/customize/i18n.md

@@ -0,0 +1,29 @@
+---
+description: Interface languages, CJK typography and translating a site.
+---
+
+# Languages
+
+Sumi's interface — buttons, labels, the search palette, dates and default callout titles — is available in English, Simplified Chinese and Traditional Chinese.
+
+```yaml title="mkdocs.yml"
+theme:
+  name: sumi
+  locale: zh        # en, zh (zh_CN), zh_TW
+```
+
+## CJK typography
+
+When the page language is Chinese, Japanese or Korean, Sumi uses a system font stack suited to the script, a slightly larger line height and no letter-spacing on headings. Search matches CJK text by substring (see [Search](search.md#chinese-japanese-and-korean)).
+
+## Callout titles
+
+Default callout titles follow the language: `> [!TIP]` is titled *Tip* in English and *提示* in Chinese. A custom title is always used as written.
+
+## Multilingual sites
+
+Build one MkDocs site per language and link them with `extra.alternate` — see [Navigation](navigation.md#languages). Each site has its own `locale`.
+
+## Adding a language
+
+Interface strings live in one Python file, `mkdocs_sumi/i18n.py`. A missing string falls back to English. Pull requests for new languages are welcome.

mkdocs_sumi-0.1.0/docs/docs/customize/navigation.md

@@ -0,0 +1,78 @@
+---
+description: How tabs, the sidebar, section index pages, breadcrumbs, versions and languages are built.
+---
+
+# Navigation
+
+Sumi builds its navigation from MkDocs' `nav`, or from your folders when there is no `nav`.
+
+```yaml title="mkdocs.yml"
+nav:
+  - Home: index.md
+  - Guide:
+      - guide/index.md          # section landing page
+      - Install: guide/install.md
+      - Configure: guide/configure.md
+  - Reference:
+      - reference/index.md
+      - CLI: reference/cli.md
+  - Blog: blog/index.md
+```
+
+## Tabs and sidebar
+
+- Each **top-level section** is a tab in the header. The sidebar shows the pages of the active tab only.
+- **Top-level pages**, such as *Home* and *Blog* above, are tabs as well.
+- A section whose first entry is an `index.md` without a title uses that page as its landing: the tab, the sidebar heading and the section name all link to it.
+- Nested sections are collapsible. The section containing the current page is open.
+
+On small screens, the tabs and the sidebar move into a drawer opened from the menu button.
+
+With `navigation_tabs: false`, the whole navigation is shown in the sidebar.
+
+## Table of contents
+
+Headings up to `toc_depth` (level 3 by default) are listed on the right, with the current section highlighted as you scroll. On narrow screens the list is folded at the top of the page.
+
+## Previous and next
+
+Links to the previous and next page follow the navigation order. <kbd>[</kbd> and <kbd>]</kbd> move between pages; <kbd>j</kbd> and <kbd>k</kbd> move between headings.
+
+## Versions
+
+Sumi reads the `versions.json` file that [mike](https://github.com/jimporter/mike) writes, shows a version menu in the header and a notice on old versions.
+
+```yaml title="mkdocs.yml"
+theme:
+  name: sumi
+  version_provider: mike
+```
+
+```sh
+mike deploy --push --update-aliases 0.2 latest
+mike set-default --push latest
+```
+
+## Languages
+
+For a site published in several languages, list them under `extra.alternate`. A language menu appears in the header and in the command palette.
+
+```yaml title="mkdocs.yml"
+extra:
+  alternate:
+    - name: English
+      link: /en/
+      lang: en
+    - name: 简体中文
+      link: /zh/
+      lang: zh
+```
+
+## Edit links
+
+With `repo_url` and `edit_uri`, each page shows **Edit this page** at the bottom and in the page menu.
+
+```yaml title="mkdocs.yml"
+repo_url: https://github.com/me/project
+edit_uri: edit/main/docs/
+```