« Blogs for MkDocs » (MkDocs-Blog-Plugin)

This plugin allows you to host a tiny blog section in your MkDocs site.

Move away, WordPress… well, not really.

https://raw.githubusercontent.com/fmaida/mkdocs-blog-plugin/master/screenshot.png

How does it work ?

It’s quite simple. 90% of the work is already done by MkDocs itself.

Each time you will build your MkDocs site or serve it, this plugin will try to find a specific directory in your documentation folder. If it finds it, every document and every subdirectory nested in it will be listed in reverse on the navbar. Plus, if you will have too many documents to be listed at once, the plugin will try to organize your remaining documents in subfolders.

How can I install it ?

You can install it through pip with this command:

pip install mkdocs-blog-plugin

Then, open your mkdocs.yml configuration file and add these lines:

plugins:
    - blog

Last but not least, enter you docs folder and create a new subfolder and name it blog. This plugin will try to find blog articles inside this directory.

Then you are ready to begin.

How can I add new articles to my blog section ?

Inside docs/blog create a folder for each year you are planning to add new articles. Then, inside each year folder create twelve folders, numbered from 01 to 12 for each month. Finally, in each month folder for each day create a corresponding folder but remember to add a leading zero (for example: 08, 09, 10, …) Now, for every article you will go inside the corresponding `year/month/day folder and you will create a new file there. While it is not necessary that you keep this strict naming convention, this will help the plugin to understand when your article was made.

For example, this is how I manage my blog folder:

docs
├── blog
│   ├── 2019
│   └── 2020
│       ├── 01
│       │   ├── 20
│       │   │   └── first-article.md
│       │   └── 26
│       │       └── second-article.md
│       ├── 02
│       │   ├── 01
│       │   │   └── third_article.md
│       │   └── 09
│       │       └── fourth-article.md
│       └── 03
│           └── 16
│               └── fifth-article.md
└── index.md

Customizing the plugins

You can customize this plugin by adding some parameters in the mkdocs.yml file, like this:

- plugin:
      - blog:
          format: "(%m/%d/%y)"
          text-align: "right"

Here is a brief list of every parameters supported by the current version of the plugin:

folder

This is the section / folder in which we’ll try to build our blog

Default value: “blog”

articles

How many articles do we have to display on our blog at once? More articles will be displayed in the corresponding subsection

Default value: 6 articles

more-articles

Let’s allow our user to slightly customize the “previous articles” section. How do we have to name this section if it will contains more articles? Remember to put a percentage character wherever you want this plugin to insert the number of available articles.

Default value: “More articles (%)”

pagination

Which name do we have to give to each subsection inside our “more articles” section? Remember to put two percentage characters wherever you want this plugin to insert the actual number page and the total amount of pages made.

Default value: Page % of %”

display-more-articles

Can we display the previous articles section, or is it better if we hide it?

Default: True

display-article-date

Can we display the article date in the navbar, or is it better if we hide it?

Default: True

format

How we have to display an article publication date on our navbar?

You can use these placeholders inside your string:

%d = Day
%m = Month
%y = Year (2-digits)
%Y = Year (4-digits)

Default value: “[%d/%m]”

text-align

Do we have to display an article publication date on the left side ("left") or on the right side ("right")?

Default value: “left”

Metadata

Release files for mkdocs-blog-plugin 0.25

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mkdocs-blog-plugin 0.25
File	Size	Uploaded	Provenance	Actions
mkdocs-blog-plugin-0.25.tar.gz	6.1 kB	Apr 13, 2020	Without provenance	Details for mkdocs-blog-plugin-0.25.tar.gz

Release files / mkdocs-blog-plugin-0.25.tar.gz

Download URL	mkdocs-blog-plugin-0.25.tar.gz
Size	6.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`36dcd804f6ab1314d19c32e46bf21076d5f4425e1bca22f2e735b9b4baaec836`
BLAKE2b-256 checksum How to use checksums	`a4decd98844ffa535f3d56d78437ecdf0c351d486f91933683f926dfac15b149`
Upload date	Apr 13, 2020
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.1.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.7`

Security for mkdocs-blog-plugin 0.25

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.25 This release

Apr 13, 2020 1 release file No provenance

mkdocs-blog-plugin 0.25