[tags plugin] [mod] sort by date and display date

[balansczerni]

What

A simple solution to sort links under tags + (probably not the best) solution to add date next to links.

In my case, I needed to place links in the following order:

1. pages (usually without a date in the meta)
2. newest entries from blog
3. oldest entries from blog

Related

• Configuration - Built-in tags plugin: tags_pages_compare
• Tags index: Sorting pages by title instead of path #5612
• How to enable custom tags sorting? #4968

Why

For people who don't know how to program at all (like me) and would spend too much time figuring out how to define custom comparison function (also like me).

I'm pasting my step-by-step solution in case it's useful to someone. 🥸

I'm a rookie and there's probably a smarter way to do this.

Code

Structure

Make a file for the sorting function - it may be named differently and be somewhere else, but it will change the path you enter in mkdocs.yml.

.
├── material/
|   └── plugins/tags/plugin.py
│       └── tagsort.py
├── mkdocs.yml
└── docs/
    ├── index.md
    └── ...

Sorting by date

tagsort.py

def date(page):
    return page.meta.get('date', '9999-99-99')

Fallback to "9999-99-99" is "a hack" to to display pages without a date at the top/bottom (depending on the value of the tags_compare_reverse option - when sorting a list that contains empty values, the sorted() function treats empty values as "smaller" than non-empty values. This means that empty values will be placed at the beginning of the sorted list).

mkdocs.yml

plugins:
  - tags:
      tags_pages_compare: !!python/name:material.plugins.tagsort.date
      tags_pages_compare_reverse: true

---

Adding date to links

Roaming around with build-in plugins requires following the instructions from Theme development or directly editing the files in your python environment or .overrides 🤪 (this requires addtional attention when upgrading to newer versions).

In that case, you might also love this git ci.yml fragment:

      - run: |
          python_version=$(python -V 2>&1 | cut -d " " -f 2)
          cp -f material/.overrides/plugins/tags/plugin.py  /opt/hostedtoolcache/Python/"$python_version"/x64/lib/python3.11/site-packages/material/plugins/tags/plugin.py
      

plugins/tags/plugin.py

In order to display the Polish date (in my case) after each link under the tag, we need to import Babel.

import logging
import sys
import babel.dates

Now we replace the section that renders the link to the page with:

# Render link to page
title = page.meta.get("title", page.title)
date = page.meta.get("date", "")
# Fallback protection from earlier tagsort.py and for undated entries.
if date == "9999-99-99" or date == "":
    # Render normal link
    content.append(f"- [{title}]({url})")
else:
    try:
        # Format the date object into a human-readable string in your lang
        formatted_date = babel.dates.format_date(date, 'd MMMM yyyy', locale='pl_PL')
        # Render link with date
        content.append(f"- [{title}]({url}) <small>- <time datetime=\"{date}\">{formatted_date}</time></small>")
    except ValueError:
        log.error("Wrong date format for " + str(page))
        sys.exit(1)

You can mess with Babel with help of:

• Localize
• Pattern syntax

I probably wouldn't post such simple things if it wasn't for the fact that 1) sometimes there are questions from equally inexperienced people here, 2) such a little digging helps me learn how everything works and maybe it will also help someone in the future.

Kisses!

[squidfunk]

Thanks for sharing! ❤️