mkdocs-blogging-plugin 0.2.0

Mkdocs plugin that generates a blog index page sorted by creation date.

mkdocs-blogging-plugin

A mkdocs plugin that generates a blog page listing selected pages by time.

Installation

pip3 install mkdocs-blogging-plugin

Prerequisites

• Only material theme is adapted by far.

• navigation.instant feature cannot be enabled if blog paging is on.

Usage

Add blogging in plugins and specify the directories to be included:

plugins:
  - blogging:
      dirs: # The directories to be included
        - blog

In the page you want to insert the blog content, just add a line {{ blog_content }} into your desired position:

# Blogs

{{ blog_content }}

In articles, add meta tags providing article title and description, which will appear on the post list:

---
title: Lorem ipsum dolor sit amet
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
---

To exclude certain pages from the blog collection, add a meta tag exculde_from_blog in the meta section of the markdown file:

---
exculde_from_blog: true
---

And it's done! You can open the page where you insert {{ blog_content }} and see how it is working.

Customization

Options

Optionally, you can customize some behaviours of the plugin:

size: 5            # Number of articles in one page, default: 10
locale: en         # The locale for time localizations, default: system's locale
sort: 
  from: new        # Sort from new to old, default
  # or old         # Sort from old to new
  by: creation     # Sort by the first commit time, default
  # or revision    # Sort by the latest commit time
paging: false      # Disable paging
show_total: false  # Remove 'total pages' label
template: blog-override.html # Path to customized template, see below

Overriding Template

The template entry in the configuration provides you a way to override the blog content to be rendered.

To customize the blog content, create an HTML template with name other than blog.html, then provide the path relative to the parent directory of mkdocs.yml to the plugin's configuration.

For example:

.
├─ overrides/
│  └─ template.html
└─ mkdocs.yml

then the configuration should be template: overrides/template.html.

Partial Customization

You can override how the plugin render a single blog through this method.

In your template, define a macro that renders a single blog with the provided parameters title, description and time. Then add a line {% extends "blog.html" %} below the macro.

Please note that {{ caller() }} must be present somewhere inside the macro.

{% macro render_blog(title, description, time) -%}
    <h3>{{ title }}</h3>
    <div>{{ description }}</div>
    <div>{{ time }}</div>
    <hr/>
    {{ caller() }}
{%- endmacro %}

{% extends "blog.html" %}

The plugin now use your macro render_blog to generate the HTML.

Further more, if you want to customize the css, extend the block style below {% extends "blog.html" %}. Call {{ super() }} at the top if you want to preserve the original style.

{% block style %}
  {{ super() }}
  {# your style goes here #}
{% endblock %}

Check the original template for available customization points. Here are some common ones:

• .md-typeset .blog-post-title: post title
• .md-typeset .blog-post-description: post description
• .md-typeset .blog-post-extra: extra section for creation / revision time

For more about HTML templates, refer to jinja2's documentation.

Global Override

Alternatively, you can provide a template that works completely independent from the original template.

These variables are available inside your template:

• pages: sorted blog pages, see mkdocs's documentation for available attributes
• page_size: page count in each page
• is_revision: True if sorted by revision time, False if by creation time
• show_total: whether to show the total number of the blog

You can refer to the original template for help.

Publishing on Github Pages

A few more steps needs to be taken for hosting on Github Pages:

• Set fetch-depth to 0 when checking out with actions/checkout:

  - uses: actions/checkout@v2
    with:
      fetch-depth: 0
  

  Creation and revision time for articles rely on git log, so a complete respository is required.

• Configure your locale in the plugin's configuration:

  locale: zh-CN
  

  Otherwise, the plugin will use locale of the server, which is en by default.

Credits

Inspired by mkdocs-git-revision-date-localized-plugin and mkdocs-material-blog.