Automatic "Related content" / "See also" section

[Guts]

First of all, thanks for mkdocs-materialx! I'm using it on a documentation website with a growing number of pages, and I think there is an opportunity to make content discovery easier.

Motivation

The Blog plugin already supports manually defined related links through the links frontmatter metadata (https://jaywhj.github.io/mkdocs-materialx/plugins/blog.html#meta.links). This works well, but maintaining those links manually quickly becomes tedious as the documentation evolves.

It would be useful to have an optional plugin that automatically suggests related pages based on page metadata.

I've considered existing plugins (from https://github.com/mkdocs/catalog?#-links--references) but but none of them seem to be a good fit.

Ideally it would be an external plugin and I already started some work on my side but I would like to share the idea here to avoid duplicating efforts and to have feedback before going forward.

Proposal

Introduce a plugin (or extend the existing related links mechanism) that automatically computes a list of related pages for each document.

The similarity score could be based on configurable metadata, for example:

• tags (probably the strongest signal) (using the tags.json file)
• categories
• authors
• creation/update dates (Git history if available)
• any other frontmatter metadata

The implementation could combine several metadata sources with configurable weights.

Possible configuration

For example:

• configurable section title (e.g. Related content, See also, You may also like, ...)
• configurable metadata fields used to compute similarity
• configurable weights for each metadata source
• maximum number of related pages to display
• include/exclude pages using glob patterns or regular expressions
• optionally ignore pages with low similarity scores

Manual links remain the priority

If a page explicitly defines links in its frontmatter, those links should be displayed first.

If fewer than the configured maximum number of links are provided manually, the remaining slots could optionally be filled with automatically computed related pages.

This keeps manual curation possible while reducing maintenance effort.

Benefits

• better content discoverability
• less manual maintenance
• automatic updates as documentation grows
• still allows authors to override the automatic suggestions when needed

Would such a feature fit within the scope of MaterialX? I'd be happy to discuss the design or even contribute an implementation if the idea sounds interesting.

[jaywhj]

@Guts

Features that offer users related content recommendations or content exposure are indeed practical and worthwhile, and I’d be happy to discuss this together. It would be fantastic if you’ve already started work on this feature—feel free to keep developing it, and we can align on requirements as follows:

• Propose building this as a standalone external plugin
• It needs to support relevance matching across all content types, including blog posts and regular documentation pages. The link logic built specifically for blog posts is likely only applicable within the blog section.
• Similarity calculation requires careful design. A lightweight implementation can rely on structured metadata such as tags, titles, categories, source directories, and custom keywords. A more advanced implementation would integrate AI to generate content summaries for similarity scoring, alongside caching mechanisms. We can start with the lightweight version first and iterate on advanced features later, taking it step by step.

From the perspective of content discoverability and exposure, the recently-updated component I built for the document-dates module serves the exact same goal: boosting content visibility by displaying all recently revised entries in a single view.

Thanks a lot for your suggestion; I believe this feature carries real value and practical utility. I haven’t been working on comparable features recently. My current focus is a full refactor of the search module, which brings massive improvements and will be released later this month.

[Guts]

Introducing https://github.com/Guts/mkdocs-related-content. Still in WIP status but basics are here.

[Guts]

Released on PyPi: https://pypi.org/project/mkdocs-related-content-plugin/