ordering the blog

[Pageboy]

Is it possible to order the blog by updated date?

[mocdaniel]

In theory, yes - this line in the blog plugin determines the sorting order of the blog listing, and it is currently hard-coded to the creation date.

        self.blog = self._resolve(files, config)
        self.blog.posts = sorted(
            self._resolve_posts(files, config),
            key = lambda post: post.config.date.created, # blogs are sorted by creation date
            reverse = True
        )

This could probably be adjusted, but it's not trivial, and I can't do the code-digging needed right now.

Maybe this might make for a good feature proposal, @squidfunk? Allowing to specify a custom sorting of blog posts based on passed/available metadata in the plugin's config, and falling back to creation date as default?

[kamilkrzyskow]

I believe there is still a feature freeze, so no changes to the API will be accepted due to the foundational work.

This can be achieved with a hook, the posts are attached inside on_page_context for the index pages.

• mkdocs-material/material/plugins/blog/plugin.py

  Lines 363 to 364 in 646c7ab

  	context["posts"] = posts
  	context["pagination"] = pager if pagination else None

The event priority is the lowest -100 so the blog plugin doesn't expect any plugin/hook to change the value afterwards, but it's just a convention. You can set -105 in the hook to make sure it does have access to the assigned posts.

Afterwards re-sort the posts.

[mocdaniel]

Thanks a ton for elaborating on this! I haven't extended mkdocs that way yet, so this outline helps a lot.

[kamilkrzyskow]

Hi @Pageboy,
I've written the comment above about the possibility of using a hook for this, but my suggestion was incomplete, because it lacked the mention about templates and I didn't mention the possible impact of re-sorting in each on_page_context event.

So I made a small example, hopefully with "best practices" ✌️

• 8108-material.zip

The partials/post.html template always uses the created date, so after re-sorting, the rendered dates on the page didn't match the order. Also in case of hundreds/thousands of blog posts sorting on multiple pages (even if only for the index pages) might visibly impact the performance, so I added a global StateHandler, which tracks the sorted state.

Hook code

import logging

from mkdocs.config.defaults import MkDocsConfig
from mkdocs.plugins import PrefixedLogger, event_priority
from mkdocs.structure.nav import Navigation
from mkdocs.structure.pages import Page
from mkdocs.utils.templates import TemplateContext


def on_config(config: MkDocsConfig):

    # Reset state for mkdocs serve changes
    StateHandler.is_sorted = False


# Run after the Blog plugin
@event_priority(-105)
def on_page_context(
    context: TemplateContext, *, page: Page, config: MkDocsConfig, nav: Navigation
):

    # Quit early if already sorted
    if StateHandler.is_sorted:
        return

    posts = context.get("posts")

    # Ignore pages without posts
    if not posts:
        return

    # Sort in-place, this affects the posts globally for all pages that use them
    # Most recently updated at the top
    posts.sort(key=lambda post: post.config.date.updated, reverse=True)

    StateHandler.is_sorted = True
    LOG.info("Blog posts sorted by updated")


class StateHandler:
    is_sorted: bool = False


HOOK_NAME: str = "sort_blog_updated"
"""Name of this hook. Used in logging."""

LOG: PrefixedLogger = PrefixedLogger(
    HOOK_NAME, logging.getLogger(f"mkdocs.hooks.{HOOK_NAME}")
)
"""Logger instance for this hook."""

[kamilkrzyskow]

Actually, for some reason I had a blind spot, as the final suggestion can also be applied to templates:

{#- Post update date -#}
<li class="md-meta__item">
  <time datetime="{{ post.config.date.updated or post.config.date.created }}">
    {{- (post.config.date.updated or post.config.date.created) | date -}}
  </time>
  {#- Collapse whitespace -#}
</li>

So this would give priority to update date and fallback to created date, sorry about the code churn.

[kamilkrzyskow]

I've cloned your repo, turned off all other plugins, and got the same error as you mentioned.
I've added the assertion check and got this error:

AssertionError: photos/Bread Wheat.md this file doesn't have date.updated

date: 2025-03-23
updated: 2025-03-23

This is incorrect, https://squidfunk.github.io/mkdocs-material/plugins/blog/#meta.date
There is either a flat date: <date> syntax or a mapping

date:
  created: <date>
  updated: <date>

[kamilkrzyskow]

If you want to keep your current setup, I've checked that the Blog plugin does convert the keys to date object.
So you can change the code to

key=lambda post: post.post.meta.get("updated") or post.post.meta.get("date")

continuing the idea of having a fallback

[Pageboy]

Here's a problem: I am using Obsidian to write the posts and this doesn't seem to support date mapping.
The metadata for date/updated would be on separate lines.
I can try again in a bit...

[kamilkrzyskow]

Perhaps check out:

• https://mkdocs-publisher.github.io/
• https://mkdocs-publisher.github.io/setup/general/pub-obsidian/
• https://mkdocs-publisher.github.io/setup/general/pub-blog/

The Publisher package kind of focuses on obsidian support / integration, but would require a refactor to your workflow.
Haven't used it myself, so can't tell you more.

I've also sent you an email on the @me.com domain.