Currently, for events like on_page_markdown, on_page_content, on_post_page, MkDocs iterates once on pages, calling each plugin's hook(s) on the way (depending on specified priority or order in mkdocs.yml).

I find myself in need for something different: I want MkDocs to support running specific plugins' hook(s) in isolation from the other plugins, in a second (or third, etc.) iteration of the pages.

Currently:

• pluginA's on_page_content(page1)
• pluginB's on_page_content(page1)
• pluginC's on_page_content(page1)
• pluginA's on_page_content(page2)
• pluginB's on_page_content(page2)
• pluginC's on_page_content(page2)
• etc.

What I need:

• pluginA's on_page_content(page1)
• pluginB's on_page_content(page1)
• pluginA's on_page_content(page2)
• pluginB's on_page_content(page2)
• pluginC's on_page_content(page1)
• pluginC's on_page_content(page2)
• etc.

Why?

Some plugins need to collect data on all pages in a certain hook, before using this data in a later hook. With plugin interactions, and a limited number of hooks, I find myself cornered into on_post_build (where files have already been written to disk), because I must wait for another plugin to have collected data on all pages in the on_post_page event.

Instead of hacking on_post_build, I want to hook into on_post_page too. But since pluginA and pluginB will run on each page one after the other (A, then B, then A, etc.), that doesn't work: when pluginB's hook runs, data in pluginA is incomplete.

Concrete example: I'm working on a backlinks feature in mkdocs-autorefs + mkdocstrings. mkdocs-autorefs transforms <autoref> elements it finds in pages' HTML. It's collecting data in on_page_content for this, so it must wait until on_post_page before transforming the HTML. To avoid running possibly expensive stuff twice (regex on HTML), I tried collecting backlinks data in autoref's on_post_page too, since this data is included in <autoref> element (once again for perf reasons). But then mkdocstrings wants to transform the HTML too, using data collected by autorefs in on_post_page. Unfortunately, since on_post_page is the last hook that runs on each page, mkdocstrings is cornered: there's no later hook that runs on all pages that it could use to transform their HTML. Running at on_post_page is not possible either since autorefs is still collecting backlinks data. So essentially, I would like the on_post_page iteration to run twice: once normally, and once again for mkdocstrings (thanks to some configuration or decorators in mkdocstrings' plugin).

There are many more scenarios that I won't repeat here where this would be useful. This has been a long standing issue for plugins who collect data across all pages. I believe allowing several iterations for events that run on a collection of items would help solve that 🙂