Blog#

Every Markdown file under docs/blog/ is a post. Sumi generates the blog index, keeps posts out of the sidebar, and writes an Atom feed. You don't need another plugin.

docs/
- blog/
  - .authors.ymloptional: author names and avatars
  - index.mdoptional: the blog's title and intro
  - posts/
    2026-11-01-introducing-sumi.md
    2026-11-15-search.md

See it on this site's blog.

Writing a post#

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

---
date: 2026-11-01
authors: [xianpeng]
tags: [release, design]
description: Sumi 0.1 is out.
---

# Introducing Sumi

The first paragraph is the excerpt shown on the index.

<!-- more -->

The rest of the post.

datedate

Publication date. Defaults to the date of the last Git commit, or the file's modification time.

updateddate

Shown as "Updated" on the post.

authorslist

Author ids from .authors.yml, or plain names.

tagslist

Shown on the post and as filters on the index. categories is accepted too.

descriptionstring

The excerpt on the index and the summary in the feed. Without it, the text before  is used.

imagestring

A cover image, as a path from docs/. Shown at the top of the post, on its card in the card view, and as the preview when the post is shared. Set hide_cover: true to keep it off the post itself.

draftboolean

Build the page but leave it out of the index and the feed.

Authors#

docs/blog/.authors.yml

authors:
  xianpeng:
    name: Xianpeng Shen
    description: Maintainer
    avatar: https://github.com/shenxianpeng.png
    url: https://github.com/shenxianpeng

The format is the same as the Material blog plugin's, so an existing file can be reused.

The index page#

Without docs/blog/index.md, Sumi creates one titled "Blog". To add an introduction, create the file; any Markdown in it is shown above the list of posts. Tag filters appear when posts have tags, and a filter can be linked to as blog/#tag=release.

List and card views#

The index shows posts as a list, or as a grid of cards with cover images. Readers can switch with the buttons next to the tag filters; their choice is remembered. Pick the default with blog.layout:

mkdocs.yml

plugins:
  - sumi:
      blog:
        layout: cards    # or list (the default)

A post without an image gets a cover drawn from the accent colour and its first tag.

Feed#

An Atom feed is written to blog/feed.xml and linked from every page's <head>, so feed readers find it from any URL. It needs site_url to produce absolute links.

Options#

mkdocs.yml

plugins:
  - sumi:
      blog:
        dir: blog        # folder under docs/ that contains posts
        feed: true
        feed_items: 20
        layout: list     # or cards