Blog

The epresso_blog plugin turns a folder of Markdown posts into a blog: a paginated index, an archive per year, a page per category and an RSS feed. It reads Material for MkDocs blog posts as they are and builds the same URLs, so a migrated blog keeps its links. The docs theme enables it.

  

    
        
    
    
    
        
            
                text
            
        
        
            


        
        
            


            


        
    






  
docs/└── blog/    ├── index.md          ← text above the post list (optional)    ├── .authors.yml      ← author names / avatars (optional)    └── posts/        ├── hello.md        └── hello/            └── chart.png ← relative images work

A post:

  

    
        
    
    
    
        
            
                markdown
            
        
        
            


        
        
            


            


        
    






  
---date: 2026-10-03          # a date, a datetime, or {created: …}authors: [jo]categories: [Release]tags: [launch]draft: falseslug: hello-world         # optional; default: from the title---# Hello worldThe excerpt shown on the index.<!-- more -->The rest of the post.

.authors.yml:

  

    
        
    
    
    
        
            
                yaml
            
        
        
            


        
        
            


            


        
    






  
authors:  jo:    name: Jo Doe    avatar: https://example.com/jo.png    url: https://example.com

#Options

The option names and defaults are MkDocs' blog plugin's:

  

    
        
    
    
    
        
            
                toml
            
        
        
            


        
        
            


            


        
    






  
[plugin.epresso_blog]blog_dir = "blog"                  # under the docs dir (content/ without epresso_docs)post_url_format = "{date}/{slug}"  # /blog/2026/10/03/hello-world/; also {file}, {categories}post_slugify = "title"             # or "file"pagination_per_page = 10archive = true                     # /blog/archive/2026/categories = true                  # /blog/category/release/authors_file = "{blog_dir}/.authors.yml"draft = false                      # true: publish drafts in production toorss = true                         # /blog/rss.xmllayout = "DocsPage"                # page layout (default DocsPage with epresso_docs, else Base)

In docs.toml the same keys go under [blog]; epresso import mkdocs fills them in from the MkDocs blog plugin.

#Look

Pages render with the BlogIndex, BlogPost, BlogMeta and BlogArchive components inside the layout. Ship a component with the same name in your site's components/ to replace one. In the docs theme the blog also gets a "Blog" sidebar section: all posts and the ten newest.