liang2kl/mkdocs-blogging-plugin

Add blogging feature to your MkDocs site.

mkdocs-blogging-plugin

A mkdocs plugin that generates a blog page listing selected pages, sorted by time. It supports:

• Automatic blog page generation
• Tags
• Category-level customization
• Template-based customization

Demo site: https://liang2kl.github.io/mkdocs-blogging-plugin-example

Prerequisites

• Only material theme is adapted by far
• navigation.instant feature cannot be enabled if blog paging is on

Pull requests are welcome to break these constraints.

Installation

# macOS or Linux
pip3 install mkdocs-blogging-plugin

# Windows
pip install mkdocs-blogging-plugin

Usage

A complete guide is available at https://liang2kl.github.io/mkdocs-blogging-plugin.

The easiest way to setup everything from scratch is generating your project from the template repository.

Credits

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

mkdocs-blogging-plugin's Issues

[BUG] babel TypeError: Unexpected value for identifier: None

Plugin version

latest version

Python version

3.10

Additional environment information (optional)

No response

What happened?

File "/Users/jackiexiao/miniconda3/lib/python3.10/site-packages/mkdocs_blogging_plugin/util.py", line 150, in get_localized_date
return format_datetime(time, format="short", locale=_locale)
File "/Users/jackiexiao/miniconda3/lib/python3.10/site-packages/babel/dates.py", line 719, in format_datetime
locale = Locale.parse(locale)
File "/Users/jackiexiao/miniconda3/lib/python3.10/site-packages/babel/core.py", line 317, in parse
raise TypeError(f"Unexpected value for identifier: {identifier!r}")
TypeError: Unexpected value for identifier: None

What should have happened? (optional)

No response

How to reproduce the bug?

in macos

Python 3.10.10 (main, Mar 21 2023, 13:41:05) [Clang 14.0.6 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import locale
>>> locale.getdefaultlocale()
(None, 'UTF-8')
>>>

so _locale get None which is wrong in mkdocs_blogging_plugin/util.py

    @staticmethod
    def get_localized_date(timestamp: float, day_only: bool, format: str=None, _locale: str=None) -> str:
        time = datetime.fromtimestamp(timestamp)
        if format:
            return datetime.strftime(time, format)
        else:
            if not _locale:
                _locale = locale.getdefaultlocale()[0]

Additional context (optional)

No response

Relevant log output (optional)

No response

[BUG] Button theme options not applied

Plugin version

2.2.11

Python version

3.12.1

Additional environment information (optional)

Windows, generating blog with mkdocs serve.

What happened?

Using the "button" theme I get the default rectangular "Continue reading" buttons:

Neither the "plain button" nor the "label" option has any effect.

What should have happened? (optional)

plain_button should alter the button appearance, and label should apply custom label instead of "continue reading".

How to reproduce the bug?

I use the following config in mkdocs.yml:

plugins:
  - blogging:
        dirs: # The directories to be included
            - blog
        locale: en
        time_format: '%Y-%m-%d' # The format used to display the time
        meta_time_format: '%Y-%m-%d' # The format used to parse the time from meta (defined in posts)
        theme:
            name: button
            options: # Optional
            # `true` if display the button as plain text
            # `false` or not present if display as rectangle button
            plain_button: true
            # Replacement for 'Continue Reading'
            label: Read

Additional context (optional)

Python does not throw warnings when running mkdocs serve.

Relevant log output (optional)

No response

[QUESTION] Is it possible to provide multiple templates

is it possible to provide multiple templates?
I want to translate the blog into another language, but there's no way to customize it, I'm looking for a way to customize all the templates

[Bug] Duplicate "hidden" class name

When clicking on an active pagination control, class name of hidden pages will add multiple "hidden"s, whose number is equivalent to 1 + number of clicks on the active control:

mkdocs-blogging-plugin/mkdocs_blogging_plugin/templates/pagination.js

Lines 32 to 38 in d1b564f

	if (pageId != destPage) {
	// This is not the destination page
	pages[j].className += " hidden"
	} else {
	// This is the destination page
	pages[j].className = pages[j].className.replace(" hidden", "")
	}

[BUG] Problem with windows locales

Plugin version

2.2.11

Python version

3.12

Additional environment information (optional)

Windows 11, tried both english US and english UK locales

What happened?

trying to build/serve my docs results in UnknownLocaleError:

File "C:\Users\mszakacs\AppData\Roaming\Python\Python312\site-packages\mkdocs\commands\build.py", line 322, in build
    _populate_page(file.page, config, files, dirty)
  File "C:\Users\mszakacs\AppData\Roaming\Python\Python312\site-packages\mkdocs\commands\build.py", line 179, in _populate_page
    page.content = config.plugins.on_page_content(
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\mszakacs\AppData\Roaming\Python\Python312\site-packages\mkdocs\plugins.py", line 578, in on_page_content
    return self.run_event('page_content', html, page=page, config=config, files=files)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\mszakacs\AppData\Roaming\Python\Python312\site-packages\mkdocs\plugins.py", line 507, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\mszakacs\AppData\Roaming\Python\Python312\site-packages\mkdocs_blogging_plugin\plugin.py", line 275, in on_page_content
    self.with_timestamp(page, config.sort["by"] == "revision"))
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\mszakacs\AppData\Roaming\Python\Python312\site-packages\mkdocs_blogging_plugin\plugin.py", line 346, in with_timestamp
    page.meta["localized-time"] = self.util.get_localized_date(
                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\mszakacs\AppData\Roaming\Python\Python312\site-packages\mkdocs_blogging_plugin\util.py", line 156, in get_localized_date
    return format_datetime(time, format="short", locale=_locale)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\mszakacs\AppData\Roaming\Python\Python312\site-packages\babel\dates.py", line 719, in format_datetime
    locale = Locale.parse(locale)
             ^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\mszakacs\AppData\Roaming\Python\Python312\site-packages\babel\core.py", line 402, in parse
    raise UnknownLocaleError(input_id)
babel.core.UnknownLocaleError: unknown locale 'english_UNITED KINGDOM'

What should have happened? (optional)

No response

How to reproduce the bug?

Set windows to the following date format:

Additional context (optional)

No response

Relevant log output (optional)

No response

ERROR - Config value 'plugins': The "multirepo" plugin is not installed

When i installed multirepo plugin using this command "pip install mkdocs-multirepo-plugin" in Window and i configure plugins in .yaml file
eg:
plugins:

• search
• multirepo:
  # (optional) tells multirepo to cleanup the temporary directory after site is built.
  cleanup: true
  # if set the docs directory will not be removed when importing docs. When using this with a nav section in an imported repo
  # you must keep the docs directory in the path (e.g., docs/path/to/file.md).
  keep_docs_dir: true

-When i am using "plugins" keyword in yaml then it getting error as below :

ERROR - Config value 'plugins': The "multirepo" plugin is not installed
Aborted with 1 Configuration Errors!

-But when i using "plugin" in yaml then project running but multirepo features not working

SO please help me how we can use in window as steps

[FEATURE] Support vanilla mkdocs

Plugin version

v2.2.5

Is your feature request related to a problem? (optional)

I'm not using mkdocs-material because it doesn't fulfill my requirements, so I did my own theme.
Your plugin seems to work, except for the size setting.
If I leave the default paging, it show all posts (say 12) in one page with 3 clickable pages, which does nothing else than add a blog-pN on the url address.
Disabling the paging it shows the correct number of posts, but without paging can't see the others, like it is working on the opposite way.

What is your suggestion?

IDK if this is a bug or just because it's not running with mkdocs-material, I would like it could work as expected also on mkdocs.

Any other idea?

No response

Additional context (optional)

No response

[BUG] Blog and Tags hyperlinks are set to repo_url instead of site_url when deploying on Gitlab Pages

Plugin version

v2.2.11

Python version

3.12.3

Additional environment information (optional)

Platform - GitLab Pages

What happened?

All the hyperlinks of blogs/tags redirects to the file in the repo_url (which is not public). Even when i remove the repo_url and repo_name from the mkdocs.yml file it doesn't work.

What should have happened? (optional)

No response

How to reproduce the bug?

Try deploying a mkdocs page with blogging plugin on gitlab.io pages from the repo

Additional context (optional)

I can't share much information about my use case here because of my company internal policy, but i am willing to help solve this problem. Feel free to contact me

Relevant log output (optional)

No response

Default configurations does not seem to be included

Describe the bug
Not really a bug, but I get immediately warnings as
WARNING - Config value: 'features'. Warning: Unrecognised configuration name: features

To Reproduce
If one clones the repository, and runs mkdocs serve the warning will pop up.

Here my mkdocs.yml

site_name: Mkdocs Blogging Plugin
site_url: https://liang2kl.github.io/mkdocs-blogging-plugin/
repo_url: https://github.com/liang2kl/mkdocs-blogging-plugin/
repo_name: liang2kl/mkdocs-blogging-plugin
edit_uri: ""

theme:
  name: "material"

markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences
  - toc:
      permalink: true

features:
  tags:
    {}
    #insert: top

nav:
  - index.md
  #- Features: features.md
  #- Theme: theme.md
  #- Template: template.md
  #- Migration Guide: migration.md

time_format: "%Y-%m-%d %H:%M:%S" # The format used to display the time
locale: en
plugins:
  - awesome-pages
  - search
  - blogging:
      dirs:
        - blog
      theme:
        name: button
        options: # Optional
          # `true` if display the button as plain text
          # `false` or not present if display as rectangle button
          plain_button: true
          # Replacement for 'Continue Reading'
          label: Read

copyright: Copyright © 2021 Matteo Ghetti

Expected behavior
To not have any warning on default configurations.

Screenshots

Environment (please complete the following information):

• Ubuntu 20, 64x arch
• Python 3.9
• mkdocs 1.3.1

Additional context
I just wanna run the default example with features, time_stamp and locale enabled.

Customizable time format

Another small question:
Can I alter the format in which time and date is displayed? Or is that dependant on things like the set language?

I write my posts in English, but for the date and time would I like to use german formatting which is dd.MM.yyyy compared to MM/dd/yyyy. Is there a way to do this without changing the language?

Originally posted by @Andre601 in #7 (comment)

[FEATURE] Per-directory settings.

Idea

It would be cool if the blogging plugin would allow defining certain settings on a per-directory level such as a category (More on that in a bit).

It would allow a much higher amount of customization that the plugin is already offering.

Categories

I mentioned categories. By that I mean a way to "group" certain blog directories together to then display.

Some bloggers may have different categories/blogs for different purposes.
As an example could I have a posts category for casual blog posts and a reviews category where I only have reviews.

Example configuration:

plugins:
  - blogging:
      dirs:
        # Combines all posts from "blog/posts/" into a category called "posts"
        - category: posts
          dirs:
            - blog/posts
        # Combines all posts from "blog/reviews/" into a category called "reviews"
        - category: reviews
          dirs:
            - blog/reviews

You would then be able to use the category name in the {{ blog_content }} placeholder to only list pages from the dirs of that group.
Example: {{ blog_content reviews }}

Other options

If this setup would be implemented would it be cool if the options of it could be included for those directories too.

Example:

plugins:
  - blogging:
      dirs:
        # Uses the default settings listed below
        - category: posts
          dirs:
            - blog/posts
        # Would override size and template but otherwise uses global settings
        - category: reviews
          size: 5
          template: overrides/blog/review-template.html
          dirs:
            - blog/reviews
      size: 10
      template: overrides/blog/blog-template.html
      features:
        tags:
          index_page: blog/tags.md

How is that useful

It would allow us to have high control of how and where we would serve specific content (blog posts) without the trouble of having to stick with one single blog section.

I'm aware that this is a huge task, if not even impossible with how the plugin may be structured right now and I feel sorry that I can't contribute any code to it to help with. But I hope it's doable and that it is considered.

[BUG] 关于 use_directory_urls 配置的问题

Bug 情况

当我在配置中输入了 use_directory_urls: false 之后，所有的链接都是以 .html 结尾。

但插件中设置了 tags 主页，仍然会给出指向不带 .html 的链接，这会导致部分服务器无法跳转。（GitHub 的服务器似乎有做一些处理，所以带不带 .html 后缀都可以访问，不过本地服务器测试就不行了）

以下是部分配置文件：

use_directory_urls: false

plugins:
- blogging:
    features:
      tags:
        index_page: tags.md

非常感谢此插件，有了它我就可以做一个最近更新的页面了。

---

题外话：我的 MkDocs 页面很多，如果从 git 拉取时间，大概需要花费 250 多秒，所以我全部从元数据提取时间，这样 30 多秒就能完成了。

Need mkdocs.yml sample for blog setup

This part in the setup is a little confusing to me -

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

# Blogs

{{ blog_content }}

I created blog/index.md and put the above into it. I also added - Blog: blog/index.md to the nav. When I click that in the nav, I see the index page as part of the blog listing. How do I get rid of it there.

[FEATURE]: Follow git history for moved/renamed files

Is your feature request related to a problem? Please describe.
I recently re-arranged my mkdocs blog files to a new folder (which was not really voluntary). I am using the plugin's git-version feature to sort by the date that the file was committed. Unfortunately this information is not preserved by Git in the moved files, and it must be accessed using the '--follow' flag on the log command.

Describe the solution you'd like
Add the '--follow' command option to the git.log command that is used to get the commit times.

Describe alternatives you've considered
I would have to work out how to reconstruct the history for a file, or create a custom script to do some kind of text replacement during build time. But since it appears to be a simple code change, and other people may have the same issue, then I think it is worth asking for this feature.

[FEATURE] Option to include full page content instead of description

Describe the solution you'd like
It would be nice to use the full text (with formatting) of the individual posts instead of the description.

Describe alternatives you've considered
I realize I can copy the body of the post into the description but this feels clunky and redundant and the description field doesn't allow any formatted text.

Comparison of blogging plugins

Not a feature or a bug report, — just wanted to share that I had compared this plugin with a number of others by a few arbitrary criteria, and found it supreme. https://github.com/liang2kl/mkdocs-blogging-plugin

Thank you for the excellent tool.

[BUG] latest release breaks build(?)

Describe the bug
The latest release (2.2.3) results in a failed build for me.

I'm using a GitHub Action setup to build and publish the page and it fails with the following errors: https://pastes.dev/XgfLt3mAAI

To Reproduce
Steps to reproduce the behavior:

1. Use 2.2.3
2. Execute mkdocs build

Expected behavior
Build should be successful

Screenshots

Environment (please complete the following information):

• OS: ubuntu
• Python version 3.7
• Plugin version 2.2.3

Additional context
The full workflow file used can be found here: https://github.com/Andre601/blog/blob/master/.github/workflows/deploy-preview.yml

Run fails at "Build Docs" which is just mkdocs build

Wrong generation of A HREF on blog-content in build mode

I have another strange issue:

My index file has the following to generate the list of blog posts on the front page

{{ blog_content }}

When I use mkdocs serve to host it locally, I see the link is generated as

<a href="http://127.0.0.1:8000/blog/my-first-post/">
    <div class="blog-override-post">
   ...
</a>

However, when I use mkdocs build and also mkdocs deploy in a GitHub Action, the a tag is generated with an invalid href None:

<a href="None">
    <div class="blog-override-post">
     ...
</a>

I'm using the card theme on the blogging plugin

[FEATURE] Blog image preview support

Is your feature request related to a problem? Please describe.
Hi, can you add an image preview to the blog preview and let users to manipulate it directly from the blog markdown file?

Describe the solution you'd like
For example, if users specify the following in the markdown file:

img: /assets/img/12.jpg

Then in the blog post preview, you should see the 12.jpg as image preview.

[Evolution] No link on title

Hello,

Thank you for this great plugin that meets almost all my expectations. Would it be possible to add an option to not put a link on title of the articles?

Thank you for your work.

Sort by meta

Hello 👋

I tried to sort by a meta parameter, date, which i have in the 2021-12-16 format. I do that since I moved from another system and the creation/revision sort order doesn't make much sense since they all came in at the same time. Looking at the code it wasn't immediatly visible to me if it should work or if only the two sort-parameters creation and revision work at this moment.

[FEATURE] Support MkDocs Jinja templates if not already

Is your feature request related to a problem? Please describe.
It seems like the plugin doesn't support and/or include global Template variables such as {{ base_url }} which is bad, since this causes issues when using blog template overrides.

Describe the solution you'd like
The plugin should in one way or another allow the usage of Template variables provided by MkDocs.

Describe alternatives you've considered
For example manually writing out the URL, which may change at any point in the future.

Additional context
I wanted to use {{ base_url }} in a blog_override.html file to actually fix an issue where Avatars would not show in PR deploy previews, due to having a different URL that conflicts with the used absolute URL.

As an example does /assets/images/logo.png not work in the deploy preview, due to it having a sub-page added and the above would assume example.com/assets/images/logo.png rather than example.com/preview/assets/images/logo.png

[Question] Manual date for sorting

I was wondering, if I can use this plugin in such a way, that it would sort the pages based on a date that I define through meta.

The reason why is, that with cases where you f.e. transfer pages to another directory, the creation and last update dates will unavoidably be all the same, which messes up the pages. This is a prime case in my personal blog where some of the pages share the same date due to them being updated simultaneously at one point in the past.

I saw that there is a meta_time_format setting, but from what I can see is that only to format time from provided meta data (Frontmatter)? And if so, would this influence the ordering, or would I need a different solution?

[FEATURE] Can I only display some recent posts without paging?

When the paging is false, size becomes useless and all posts reveal. But some bloggers may only want to display some recent posts without pagination > <

size: 5
paging: false

Many thanks! :D

[BUG] TypeError: strptime() argument 1 must be str, not datetime.date

Describe the bug

The YAML parser already converts time formats in the frontmatter into datetime objects. If reading from frontmatter is enabled, building the page fails with:

TypeError: strptime() argument 1 must be str, not datetime.datetime

To Reproduce
Steps to reproduce the behavior:

1. Configure mkdocs.yml:

   plugins:
     - blogging:
         meta_time_format: '%Y-%m-%d'
   

2. Create an article with one of the following metadata values:

   ---
   date: 2023-04-12
   ---
   

   ---
   date: 2023-04-12 12:12
   ---
   

Expected behavior

Building the page should not fail.

Otherwise, it would be nice if an available date and datetime would be taken without configuring meta_time_format, if it already is a valid date by YAML. This would make the blogging plugin compatible with mkdocs-rss-plugin.

Maybe something like this:

    def with_timestamp(self, page, by_revision):
        timestamp = self.get_datetime_from_meta(page)
        if "time" in page.meta:
            timestamp = self._parse_time(page.meta["time"])
        if "date" in page.meta and timestamp is None:
            timestamp = self._parse_time(page.meta["date"])
        # ...

    def _parse_time(self, value):
        if isinstance(value, date):
            return datetime.combine(value, datetime.min.time()).timestamp()
        if self.meta_time_format:
            return datetime.strptime(value, self.meta_time_format).timestamp()

Environment (please complete the following information):

• OS: Ubuntu 22.04
• Python version 3.10.6
• Plugin version 2.2.4

Additional context
Add any other context about the problem here.

[FEATURE] Set a path for the template

Plugin version

v2.2.9

Is your feature request related to a problem? (optional)

Not a problem, just a small limitation:
currently I have a blogging-template.html in the root directory of the site project.
It's possible to move it in another one only if the docs directory is inside another, e.g. mkdocs/docs, then it goes in mkdocs:

template: "mkdocs/blogging-template.html"

which is how I use it in a project of mine.

What is your suggestion?

It would be nice to set it in any arbitrary directory:

template: "layout/blogging-template.html"

Any other idea?

No response

Additional context (optional)

No response

Errors during 'mkdocs serve'

I receive the following lines when trying to use mkdocs serve with this plugin set up:

INFO     -  Building documentation...
WARNING  -  [blogging-plugin] Custom template has higher priority than predefined themes
INFO     -  Cleaning site directory
ERROR    -  Error building page 'index.md': .icons/octicons/stopwatch-24.svg
.icons/octicons/stopwatch-24.svg

My goal is to include the stopwatch-24.svg icon from GitHub Octicons in the blog override I want to use.
I use the Material for MkDocs theme which should bundle those with it and I successfully used it in previous theme overrides.

My personal guess is a wrong formatting in the HTML file, which I share below:
https://paste.helpch.at/nirasufuvu.cs

The file is called blog-override.html and is located under theme/blog/. The theme folder is actually used as a theme-extension folder, if that is of any need.

Currently used versions:

• MkDocs version: 1.2.3
• Python: 3.7
• Material for MkDocs: 8.1.0
• Blogging plugin: 1.1.0

Any help is highly appreciated!

[FEATURE] Shut down with an error message when `site_url` is not provided

Is your feature request related to a problem? Please describe.
In the docs, it is clearly stated that site_url configuration parameter must be present for the plugin to properly function. I was still a bit confused because I misread the docs and thought about site_name instead.

Describe the solution you'd like
I would suggest that the plugin shuts down and explicitly requests the user to provide site_url in the configuration file.

[BUG] Searching page with blog content

Describe the bug
A clear and concise description of what the bug is.

To Reproduce

1. Creates index.md:

---
title: Home
hide:
  - navigation
search:
  exclude: true
---

# See my posts

{{ blog_content }}

2. Creates a blog post:

---
title: How to do this
description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
# Additional metadata can be used in the template
author: Adm
tags:
  - test

---

# How to do this
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

3. Edits mkdocs.yml:

plugins:
  - awesome-pages
  - search:
      lang: pt

  - blogging:
      dirs:
        - blog
      locale: pt
      time_format: '%d/%m/%y'
      meta_time_format: '%Y-%m-%d %H:%M:%S'
      theme:
        name: button
        options:
          label: 'Read more'
      features:
        tags:
          index_page: tags.md
          insert: top

Expected behavior
That the content of the page appears or that it is not listed

Screenshots

Environment (please complete the following information):

• OS: Linux
• Python version 3.7
• Plugin version 2.0.1

[BUG] Misspelling

exculde_from_blog -> exclude_from_blog

[BUG] DeprecationWarning: Use setlocale(), getencoding() and getlocale() instead

Plugin version

v2.2.5

Python version

3.11.0

Additional environment information (optional)

No response

What happened?

Not clearly a bug, but just to advise about a deprecation warning:

INFO     -  DeprecationWarning: Use setlocale(), getencoding() and getlocale() instead
              File "/usr/local/lib/python3.11/site-packages/mkdocs_blogging_plugin/util.py", line 145, in get_localized_date
                _locale = locale.getdefaultlocale()[0]
              File "/usr/local/lib/python3.11/locale.py", line 559, in getdefaultlocale
                warnings.warn(

What should have happened? (optional)

No response

How to reproduce the bug?

1. Install the plugin
2. Run mkdocs serve
3. Check the logs

Additional context (optional)

No response

Relevant log output (optional)

No response

[BUG] Behaviour of timestamp generation does not match with documentation

Describe the bug
The 'creation' and 'revision' flag behaviour seems to be backwards (to the docs) when generating timestamps in the blog list.

To Reproduce
Steps to reproduce the behavior:

1. Ensure you have articles with github timestamps
2. With no "sort" behaviour specified in mkdocs.yml, build the site
3. The {{ blog_content }} list shows publish dates of the latest revision
4. Repeat with config {'sort': { 'from': 'new', 'by': 'creation' }}
5. The {{ blog_content }} list show publish dates of the latest revision
6. Repeat with config {'sort': { 'from': 'new', 'by': 'revision' }}
7. The {{ blog_content }} list show publish dates of the latest creation

Expected behavior
I expect that providing sorting config specifying the creation date will display the creation date, and providing sorting config specifying the revision date will show the revision date, so that I can select which date is shown and I can verify that the sorting is correct.

Screenshots
No screenshot, but I did put some debugging code in to verify what I was seeing, and I noticed that while the function to generate the timestamps is defined to take a by_revision flag:

    def with_timestamp(self, page, by_revision):
        ...

It is called using the logic: with_timestamp(page, config.sort["by"] != "revision") which would seem to negate the flag.

Environment (please complete the following information):

• OS: Docker (alpine-linux)
• Python version 3.9
• Plugin version 2.1.1

QUESTION: Blog in `nav:` and pagination problem

Hi. First of all, excellent plugin!
I want to include it in my documentation as part of the navigation. However, when I add any element to the nav: automatically, the plugin stops paginating both blogs and reviews in the navigation sidebar. At first, I thought it was due to some compatibility problem with mkdocs material, but after testing the example, it behaves the same. Is there any way to fix this?
Another point that is perhaps worth mentioning. Since mkdocs material implements tags as well, the way it is defined mixes both, having both tags in different index files and all tags appearing in both. Maybe changing the keyword tag to blog_tag or something like that should solve this problem.
Thank you in advance

[FEATURE] Option to only list tags of a particular category in an index page

From my testing are index pages for tags always listing all used tags across all posts. This includes index pages that have been defined for specific categories.

While this may be useful and/or desireable by people is it also a bit frustrating when a tags page set in /reviews/tags lists tags used from the /posts/ directory.

When possible should there be an option to tell the plugin to only list tags from posts within a certain category.
The best way is probably to have an aproach similar to the {{ blog_content }} placeholder where you can define a category. This means you could set {{ tag_content reviews }} and it would only list tags used in posts for the category reviews.

The question I have right now is: What to do with global pages?
My current setup has the main posts page as the default/global setting and reviews as a category. It would be optimal for me to have the tags page for posts only include those of that category, but since it's global would it probs be displaying all, including those of other categories...

Perhaps a system could be worked out where you can define multiple categories to be included or excluded?
Like {{ tag_content !reviews }} to include tags not used in the reviews category or like {{ tag_content reviews | other }} to include tags from the categories reviews and other.

For now a way to define a category would be ideal for my case here.

[FEATURE] Running the macro from templates

Describe the solution you'd like
A clear and concise description of what you want to happen.

Hi, is it possible to run {{ blog_content }} macro from .html instead of .md?

Imagine instead of doing:

home.md

---
template: home.html <-- my custom
title: Blog
---

Hello folks!

{{ blog_content }}

with

home.html

{% extends "main.html" %}
<!-- Content -->
{% block content %}
  {{ page.content }} 
   here will be my custom logic
{% endblock content %}

I would like to move {{ blog_content }} outside of home.md:

home.md

---
template: home.html <-- my custom
title: Blog
---

Hello folks!

with

home.html

{% extends "main.html" %}
<!-- Content -->
{% block content %}
  {{ page.content }} 
   here will be my custom logic
   {{ blog_content }}
{% endblock content %}

I couldn't manage to include the plugin templates (not found):

{% extends "blog.html" %}
{% include "plugins/mkdocs-blogging-plugin/templates/blog.html" %}

problem with posts sorting

Hello and thank you for this plugin.
I found a problem with the posts : they are all marked as "published at" the same time (the time I built the site) and can therefore not be sorted well.
Did I miss something ?
Thanks

[FEATURE] Support multiple categories in the same page

Idea

Add the possibility to render two categories in the same page.

Example

Defining multiple categories in the mkdocs.yaml:

# mkdocs.yaml
  - blogging:
      categories:
        - name: announcements
          dirs:
            - news/announcements
          size: 5
          theme:
            name: card
        - name: partner
          dirs:
            - tutorials/partner
          size: 5
          theme:
            name: card
        - name: cicd
          dirs:
            - tutorials/cicd
          size: 5
          theme:
            name: card

and them, adding two or more categories in the same page:

# Tutorials

## CICD

{{ blog_content cicd }}

## Partner

{{ blog_content partner }}

Currently behavior is rendering only the first content for both sections.

Card theme: cursor shows as arrow, and not as hand.

With the "card" theme enabled, when hovering over a card, the mouse cursor shows up as an arrow and not a hand, as would be expected for a link.

I needed to manually add the following to make the hand show up:

.blog-override-post{
    cursor: pointer !important; /*pointer == hand in css - and doesn't work without the ! bang*/
}

it seems that setting cursor: default in the style on blog-card-theme.html is not sufficient somehow.

My Syntax Error?

I'm trying to add categories. Before I do that here is what is working - mkdocs.yml

plugins:
  - blogging:
      dirs: # The directories to be included
        - blog
      paging: false      # Disable paging
      features:
        tags: 
          index_page: blog/tags/tags.md
          insert: top

When I add the Category addition I get errors -

plugins:
  - blogging:
      dirs: # this is line 37
        - blog
      paging: false      # Disable paging
      features:
        tags: 
          index_page: blog/tags/tags.md
          insert: top
      # {{ blog_content Newsletters }}
      categories:
      paging: false      
        - name: newsletters  # this is line 47
          dirs:
            - newsletters

Here is the error when the Categories is added -

Error: MkDocs encountered an error parsing the configuration file: while parsing a block mapping
  in "g:\mkdocs.yml", line 37, column 7
expected <block end>, but found '<block sequence start>'
  in "g:\mkdocs.yml", line 47, column 9

If I don't add paging: false I also get that error about navigaton instant.

[FEATURE] Improve git commit time lookup performance with memoization

Is your feature request related to a problem? Please describe.
Based on my mkdocs configuration, the publish date for my blog articles are generated multiple times. As the list of articles grows, the build time becomes longer and longer, and git.log is already a bit slow...

Describe the solution you'd like
This can be sped up with memoisation - using the functools.cache decorator (from python 3.9) or similar on the git_get_commit_timestamp function means that the subsequent 2 calls on the same file return instantaneously. A brief test has already cut my build time by over 50%.

Describe alternatives you've considered
I've looked into speeding up git.log but can't find anything useful.

[BUG] Custom button label

Describe the bug
Not uses my button label

To Reproduce
Steps to reproduce the behavior:

1. Edit mkdocs.yml with:

plugins:
  - awesome-pages
  - search
  - blogging:
      dirs:
        - blog
   
      locale: pt
      time_format: '%d/%m/%y %H:%M:%S'
      meta_time_format: '%Y-%m-%d %H:%M:%S'
      theme:
        name: button
        options:
          - plain_button: true
          - label: 'Test'
      features:
        tags:
          index_page: tags.md
          insert: top

3. Creates a blog post blog/test.md:

---
title: Loren
description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
# Additional metadata can be used in the template
author: User
tags:
  - test
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

4. Creates index.md

---
title: Home
hide:
  - navigation
---

# My posts

{{ blog_content }}

6. See error

Expected behavior
Button with label Test

Screenshots

Environment (please complete the following information):

• OS: Linux
• Python version 3.7
• Plugin version 2.0.1