Blogging in mkdocs

andyoakley, updated 🕥 2022-01-21 04:42:09


Allows mkdocs to be used as a simple blog.


  • Provides timestamps based on folder structure
  • Enables jinja2 templating
  • Generates a simple RSS feed for recent content

Content layout

Assumes blog content is laid out in a standardized format with numeric years and months as follows:


Within a month, file modification time is used to provide chronological ordering.



[Security] jinja2 template feature leads to code injection vulnerability

opened on 2023-01-09 14:18:30 by G3G4X5X6 None

Add a license

opened on 2022-04-17 16:01:06 by pawamoy

Hi, could you add a LICENSE file to your repository? It would help to improve contents :slightly_smiling_face: If this project is unmaintained, just let me know :+1:

Can this be used to create a specific overview page?

opened on 2021-12-14 16:42:37 by Andre601

Looking at this plugin, I was wondering if it can be used to create a overview page of current blog posts in a similar fashion to what Squidfunk has for his "blog" shown here:

Unfortunately is that page there a manual thing, so if there is a way to use this plugin to make an automated generation of such a page, or a similar one, would I appreciate any help with doing this.

The source of the above page, if needed, is here:

fix example links

opened on 2021-12-14 16:29:16 by Andre601 None

Titles are "None"

opened on 2020-07-23 17:20:45 by np-8

When following the example ""

```jinja This is a list of posts, first grouped by year, then month, then sorted by age.

{% set chronological = config['chronological'] %}

{% for year in chronological|sort(reverse=True) %}

{{ year | strftime("%Y") }}

{% for month in chronological[year] %}

{{ month | strftime("%B") }}

{% for mtime in chronological[year][month]|sort(reverse=True) %} {% set page = chronological[year][month][mtime] %} {{ page.title }}
{% endfor %} {% endfor %}

{% endfor %} ```

the page titles are shown as None. image

I debugged it a little and printed page.meta which was an empty dictionary when printed to the jinja template, although I have set it using YAML syntax (also tried without setting the metadata title since I guess it should be set from the filename). I checked using a breakpoint() inside the mkdocs source code that the page.meta (and also page.title) is read correctly (inside the Page class code), so something happens between that point of code and passing the page to the jinja template.


At time being, seems that replacing {{ page.title }} with {{ page.file.url[:-5].split('/')[-1] }} or {{ page.file.url[:-5] }} gives a desired output.


  • Python 3.8.5 64-bit on Windows with mkdocs 1.1.2 mkdocs-blog 0.1.0 mkdocs-bootstrap4 0.1.4 mkdocs-git-committers-plugin 0.1.10 (tried also while disabling the mkdocs-bootstrap4 theme).

more documentation

opened on 2019-05-17 16:14:45 by cs01

This concept seems really useful and I want to give it a try, but documentation is sparse. Can you add more details on how to install and run mkdocs-blog? Maybe provide an example project?