How to generate a custom index page with a TOC listing specific meta data for each page?

[venthur]

I have a project using mkdocs-material where I have a bunch of documents and I want to generate a custom index page that contains a table listing specific meta data provided in each of the documents.

Let's say the document tree looks like this:

docs/
- adr001.md
- adr002.md
- adr003.md

and each document has the the following (custom) meta data:

---
title: some title
status: accepted
date: 2025-06-06
keywords: foo, bar baz
---

(rest of document goes here

Now I want to generate an index page that contains a table with the rows: title, status, date, and keywords and each row represents one document displaying the respective meta data.

I've tried to use the underlying custom_dir feature via:

site_name: My Docs
theme:
  name: material
  custom_dir: overrides
docs_dir: docs

in mkdocs.yml, then writing this template and putting it in overrides/adr_overview.html:

{% extends "main.html" %}

{% block content %}
<h1>Architectural Decision Records (ADRs)</h1>

<table>
  <thead>
    <tr>
      <th>ID</th>
      <th>Title</th>
      <th>Status</th>
    </tr>
  </thead>
  <tbody>
    {% for page in pages %}
      {% if page.meta %}
      <tr>
        <td>{{ page.meta.id }}</td>
        <td>{{ page.meta.title }}</td>
        <td>{{ page.meta.status }}</td>
      </tr>
      {% endif %}
    {% endfor %}
  </tbody>
<table>
{% endblock %}

and finally providing adr_overview.html in docs with

---
template: adr_overview.html
---

However, while the adr_overview is generated, the table seems empty. The for loop does iterate through all pages but apparently page.meta is not available for any of them.

[kamilkrzyskow]

Hello @venthur,
yes, there won't be any page.meta for other pages, as pages are processed in sequence one after the other, you can look at the event chain map:
https://www.mkdocs.org/dev-guide/plugins/#events

I don't think this can be resolved using templates only, You have to aggregate the data yourself using a hook.

To solve that you either have to preprocess the pages yourself, like the Blog plugin:

mkdocs-material/src/plugins/blog/structure/__init__.py

Line 61 in 406a3ad

with open(file.abs_src_path, encoding = "utf-8-sig") as f:

The Blog plugin extracts the meta data and creates a separate Excerpt object for the Index pages, and then passes that into the custom template.

Another way could be to let MkDocs process all of the pages normally, your index page would include a placeholder.
The hook would gather the page.meta data for each page on_page_markdown and then create the contents on_post_build and replace the placeholder with the generated contents inside of the index page.

Personally, I would attempt the second idea if I would have to choose ✌️

[venthur]

Hi @kamilkrzyskow,

thanks for the reply! This was a very useful hint to approach it this way. I'm trying the second approach, where I collect the meta data in on_page_markdown and try to render the index page in on_post_build. However, I'm struggling a bit with the last part. I.e. I'm not sure what is the proper way to setup the jinja2 environment, load the index template and render it to the proper path.

E.g. this throws an error: ("'config' is undefined), probably because I'm calling render wrong.

adrs = []

def on_page_markdown(markdown, page, config, files):
    # this is just the MVP to get things running
    adrs.append((page, page.meta))

def on_post_build(config):
    env = config.theme.get_env()

    template = env.get_template('adr_overview.html')
    rendered = template.render()

    with open('adr_overview.html', 'w') as fh:
        fh.write(rendered)

adr_overview.html is located in the custom_dir defined in mkdocs.yml. Do you know what's the proper way to render it?

[kamilkrzyskow]

My initial suggestion was for MkDocs to create the Page using the main.html template, and the final site_dir/page.html would contain the placeholder, and you would generate your HTML table using other means and later on just replace the placeholder.

I haven't really considered using Jinja for that step, but good idea 👍
I couldn't pinpoint the issue with 'config' is undefined, and I didn't see anything wrong with the code related to that, so I run your hook code with the blog.html to see what happens and got a longer error traceback.

File "site-packages\material\templates\partials\language.html", line 4, in top
-level template code
    {% import "partials/languages/" ~ config.theme.language ~ ".html" as lang %}
    ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "site-packages\jinja2\environment.py", line 490, in getattr
    return getattr(obj, attribute)
           ^^^^^^^^^^^^^^^^^^^^^^^
jinja2.exceptions.UndefinedError: 'config' is undefined

So the issue is that the template extends main.html, and the theme templates expect the context from MkDocs.
Each page gets the context info about the prev/next page and other stuff, then the context is passed to the render function.
https://github.com/mkdocs/mkdocs/blob/4c7404485f988f409ccaf42fefe705222ff5965a/mkdocs/commands/build.py#L207-L223

You could remove the extends part inside your template and create your own context with your own data (another TypedDict).
https://github.com/mkdocs/mkdocs/blob/4c7404485f988f409ccaf42fefe705222ff5965a/mkdocs/commands/build.py#L48

---

Errata to the previous message. you're looping over page in pages, but as per the context creation above and MkDocs documentation pages is a list of File objects pages=files. So page.meta won't work, as File doesn't have this attribute. The correct access would look like page.page.meta inside the loop. Just a mention, because it would still be empty, unless...

Another errata is another idea how to solve this using your initial approach. Since the pages are processed sequentially, you could try to use the hook to move the processing of your index page to the end, when all of the pages have loaded their meta. Probably in on_files but I don't know if this would impact navigation. This way you would not have to do any re-rendering / placeholder replacement.

[venthur]

Errata to the previous message. you're looping over page in pages, but as per the context creation above and MkDocs documentation pages is a list of File objects pages=files. So page.meta won't work, as File doesn't have this attribute. The correct access would look like page.page.meta inside the loop. Just a mention, because it would still be empty, unless...

I think this is it! page.page.meta exists and seems to contain everything i need. So I think I can continue with my initial approach and don't have to use hooks in the first place.

Thanks a lot, I learned a lot about the way mkdocs processes pages.

[kamilkrzyskow]

Then I'm sorry about the confusion, I admit that this time, I've been too complacent in checking the event chain that I posted at the start that clearly shows that my initial statement is wrong, as the populate-page including on_page_markdown stage happens for every page before the on_env and template processing.

I must have been confusing this situation with another that required cross-page meta access during the populate-page stage.

Thanks for your patience in the debugging process and sticking out until the end 🫡
I guess I need to look at the page a few 60 times more😅

[venthur]

All good! The new knowledge about hooks is still useful for my project at hand. Do you know if it is possible to modify the page dict? Within:

def on_page_markdown(markdown, page, config, files):
    # let's augment the meta data so i can use that information later in the jinja2 template
    page.meta.test = 42

so I can augment it with extra information? Seems like Jinja2 did some magic to make it read-only:

AttributeError: 'dict' object has no attribute 'test' and no __dict__ for setting new attributes

[kamilkrzyskow]

This isn't JavaScript, pure dict assignment has to be done via ["key"], so page.meta["test"] = 42

[venthur]

Ouch :)

[kamilkrzyskow]

Both Jinja2 and MkDocs probably use some sort of class DictWrapper that get initialized with the dict, and then the dictWrapper.attribute invokes the __getattribute__ or __getattr__ which is customized to read the dict[attribute]
https://docs.python.org/3/reference/datamodel.html#customizing-attribute-access