I'm not sure what to think about this. But then I have never found diagrams depicting code to be helpful. They only confuse me. I much prefer reading the source code. So, I realize I'm not the target audience for this, but I am having a hard time seeing how this adds any value.

Although, I do appreciate it being hidden by default. Although, I wonder why you are introducing another third party Markdown extension. Why not make use the bootstrap, which is part of the theme? Thats what we are doing in the newly redesigned home page.

I'm not sure what to think about this. But then I have never found diagrams depicting code to be helpful. They only confuse me. I much prefer reading the source code. So, I realize I'm not the target audience for this, but I am having a hard time seeing how this adds any value.

For some people a visual representation of when a software does what with what order and under what conditions helps more than someone saying "Well the software does X after Y but only when condition Z is met".
This is especially prominent with people that are fairly new in that particular coding language or with using this software, so a visual guide to understand when what happens never hurts imo.

@oprypin Few design choices:

1. Maybe go with a PNG rather than an SVG. While it can be beneficial for scaling and such does it have issues for people like me who use extensions such as Dark Reader, as things like this one here happen:
   
2. Since this PR seems to add PyMdownx's "Snippets" extension, wouldn't it also be a better benefit to use the details extension? I barely could notice the little detail in the wall of text so having it more highlighted that way could probably help.

Maybe go with a PNG rather than an SVG

While it can be beneficial for scaling and such

also showing actual semantic text, that is selectable, and acts as hyperlinks.

Dark Reader just shouldn't be doing this... But I could instead check for some workaround to make it work though.

wouldn't it also be a better benefit to use the details extension

I think in the end the extension also simply produces a <details> element. Are you sure you're not confusing this with the theming that mkdocs-material theme provides?

I think in the end the extension also simply produces a <details> element. Are you sure you're not confusing this with the theming that mkdocs-material theme provides?

Could be.
It's always worth a try and also always better to have Markdown formatting rather than raw HTML in between everything.

Actually looking at the description of the details extension would I assume that you can just pass info as first arg to use the info admonition style.

https://facelessuser.github.io/pymdown-extensions/extensions/details/#syntax

always better to have Markdown formatting rather than raw HTML

In this particular case actually the Markdown parser totally messes up the SVG document, so I had to intentionally enter HTML mode for it.

you can just pass info as first arg to use the info admonition style.

That literally only adds class="info" to the markup, which then just happens to be handled by the styling of mkdocs-material theme.

@waylan
I am also not completely sure what others would think about it, I certainly don't have a fresh point of view, having stared at it for a day.
But I am sure that some diagram is needed. It is very important to be aware of these two fan-out points for pages; this even points out a particular event that happens in between the two fan-outs, which a reader would otherwise have no idea about. Myself, even knowing everything there is to know about the code itself, I often need to imagine this structure to better judge whether something is possible to achieve in MkDocs. And since that imagination can sometimes fail, I really wanted to make this once and for all.

I am having a hard time seeing how this adds any value

I just have to comment on this (mostly unrelated), because you say something like that so often.
I think not recognizing some points of view could come from the fact that you're not actively engaged with plugin development (unless I'm mistaken). Lacking that, I think you will have to give more trust to people who do actively develop.

I wonder why you are introducing another third party Markdown extension. Why not make use the bootstrap, which is part of the theme?

I don't know if you meant those two sentences to be related, but the two aspects are certainly not related as far as I see. So,

1. The extension is needed to paste one file's content into another file. The alternative would be to literally paste the whole SVG document into the HTML document. Another alternative that I dismissed would be to embed it as an image instead, but the browser would not recognize individual text elements and let them act as hyperlinks. Font family would need to be hardcoded as well.

2. Never used Bootstrap; could you explain how it could be useful here? I'm not using any styling, anyway, just standard elements. Do you mean that there is some Bootstrap-standard look for "spoiler" elements?

I want to generally support the effort of diagramming complex things.

A visual representation, if done well/correctly/thoroughly, can give significant confidence to a new entrant that they're seeing the entire landscape of a thing that is new to them. It also can provide hints and reminders to experienced community members about the dark(er) corners of a complex system.

Separately, it might be worth the discussion of looking into https://plantuml.com/activity-diagram-legacy (or apparently, the newer https://plantuml.com/activity-diagram-beta). It can embed HTML/links and might be easier to maintain than the relatively extensive .gv file?

While refactoring mkdocstrings into a plugin + markdown extension, I also had to draw a less extensive version of this, so this would have definitely helped me! See mkdocstrings/mkdocstrings#28

Never used Bootstrap; could you explain how it could be useful here? I'm not using any styling, anyway, just standard elements. Do you mean that there is some Bootstrap-standard look for "spoiler" elements?

See Bootstrap's documentation. Simply assign the appropriate class to an HTML element, it automatically gets the described behavior, look and color, all which match the theme. For example, see the accordian component. There are many different components. Perhaps another would work better. Either way, you would need to use raw HTML for this. Although, as the content is SVG, that shouldn't be an issue.

Soooo that component doesn't do anything without JavaScript, i.e. the diagram will not be viewable without JavaScript.
I actually found this documentation when I did a quick search last time, but I dismissed it, because surely they wouldn't force a component that needlessly breaks without JS..?

Usually I'd find this unacceptable, but now seeing that even the site nav itself doesn't work without JS, .. .. OK. I can reluctantly replace it.

Ah no, I was able to pick out only the styling from their example. Let me know if the JavaScript solution is still preferred.

Could you update your preview to the latest so we can see how that looks/behaves?

As I stated previously, these sorts of diagrams are of no value to me personally. That said (as some seemed to miss), I understand that they are useful to others. My point is that I am not equipped to evaluate whether this particular diagram is any good. Therefore, I need to rely of others for this. I see some comments suggesting that the diagram could be improved. And well, to me it looks like a mess so I'm inclined to believe those comments. However, I don't see that any changes have been made to address those concerns.

However, I don't see that any changes have been made to address those concerns.

You can't expect contributors to react instantly and fix everything in a short time. This is still a discussion: please give time to contributors before saying things like that. When I read your comment, it sounds like you're saying "people suggested improvements, and 2 days later I still don't see them, so I won't even consider merging this." This is not welcoming at all.

Besides, @oprypin did push changes to fix some things that were mentioned, such as the issue with DarkReader.

And well, to me it looks like a mess

It represents the code and data flow, so if the flow is a mess, I think it's even more worth having a diagram showing an overview of it.

You can't expect contributors to react instantly and fix everything in a short time. This is still a discussion: please give time to contributors before saying things like that. When I read your comment, it sounds like you're saying "people suggested improvements, and 2 days later I still don't see them, so I won't even consider merging this." This is not welcoming at all.

This may a misinterpretation of what was said. @waylan is certainly more direct than some, but I don't think he meant anything mean or dismissive by his statement. I think he's just asking for an updated image showing changes, and also reminding that there seem to be some suggestions for improvement (which has been admitted is not an area he is well equipped to judge), so it's kind of being asked if there is something that can be done in those areas.

It is hard to guess the intent through written text indeed, so it might absolutely be a misinterpretation. But it was my first impression 😕

@facelessuser is correct. I certainly did not mean to offend. I was simply trying to communicate clearly what I expect before I would consider this to be in an acceptable state.

@pawamoy I've worked with @waylan on Python Markdown for a while, so I've learned his personality a bit more 🙂. And yes, tone is not always easily conveyed in text.

I know I've upset a few people here and there over the years maintaining my projects. While I never mean to offend, sometimes it still happens 🤷🏻. It's tough sometimes as you are quickly firing off comments in your free time to keep things moving or to try and convey you are not comfortable with the maintenance burden a pull request may place on you, the maintainer. Sometimes, things just don't translate to others as you intend.

Thanks @facelessuser, I'll try to keep all this in mind!

Could you update your preview to the latest so we can see how that looks/behaves?

Done.

I see some comments suggesting that the diagram could be improved. And well, to me it looks like a mess so I'm inclined to believe those comments. However, I don't see that any changes have been made to address those concerns.

I don't actually see any concrete comments that are not addressed.
Let me summarize what I did see and address:

why you are introducing another third party Markdown extension

Replied why

Why not make use the bootstrap, which is part of the theme

Done

Maybe go with a PNG rather than an SVG

I have replied why I wouldn't do that

extensions such as Dark Reader

Done

wouldn't it also be a better benefit to use the details extension

I have replied why it's invalid

it might be worth the discussion of looking into plantuml.com/activity-diagram-legacy (or apparently, the newer plantuml.com/activity-diagram-beta). It can embed HTML/links and might be easier to maintain than the relatively extensive .gv file?

This is throwing options without showing their merits and possibly suggesting that I haven't already looked into various options.
Additionally, following this comment, I refactored the "extensive .gv file" as Python. (but still really not sure if that's more accessible to hypothetical people trying to significantly alter it in the future, or perhaps even less accessible).
Now with that refactor, the data is in such a shape that it wouldn't be too hard for a commenter to directly try to apply a different graphing solution based on it, as part of evaluating alternatives. I am currently not interested in evaluating any more alternative solutions myself.

There's also the discussions thread, which can be considered unresolved, but I said there that I would need a concrete suggestion for improvement, because the current flaws I was already aware of but didn't find an improvement myself.

First-time plugin developer here with a rather bad Python-fu 👋 this would've been a tremendous help!

First of all, the improvements you've made look much better. Thank you.

Now bear with me as I look at the content of the diagram itself. Why are there three boxes each for populate_page, build_page and build_template? Also, what is up with the three arrows which start from nothing and point to the build_template boxes? I realize that there are multiple different 'types' of templates, which each follow a slightly different code path, but there is only one 'type' of page. I don't understand what these elements are supposed to be representing.

I am also concerned that the render objects (green ovals) could be misleading. In the build_template box, render obviously refers to the template, and that is fine. But in the two 'page' boxes (populate_page and build_page), render does not mean "render page." In the one instance it means "render Markdown" and in the other it means "render template". The two outer boxes combined result in one "render page" (which is not represented in the diagram at all) I wonder if we should clarify what is being rendered in each instance. Perhaps use render Markdown and render template or something to that effect?

I considered if perhaps both the populate_page and build_page boxes should be wrapped in an outer box which represents all 'page' relates steps, but then I realized that on_env needs to be a step between those two inner boxes, but, it should be outside the outer box. Maybe someone could find a clever way to represent that, but I certainly am not going to try and don't expect that we will include such a change. I only mention it in the event that someone does have an idea of a good way to do so. If not, that's fine.

Finally, moving on to the general design, please don't take this the wrong way, but I find it ugly. I'm no designer, but in my opinion, the colors do not work with the site design and the wavy lines seem inappropriate to me. Some of the sweeping curves look fine, but others come across as very haphazard (or hand-drawn) to me. I would have expected straight lines, with sharp corners. But then, what do I know. Diagrams are not my thing. Still, I wonder if the general look could be improved so that it looks like if belongs on the site. I realize this is completely subjective and opinions differ. But if we can improve it, then we should.

[...] and the wavy lines [...]

Well, GraphViz, aye?

First of all, the improvements you've made look much better. Thank you.

Now bear with me as I look at the content of the diagram itself. Why are there three boxes each for populate_page, build_page and build_template? Also, what is up with the three arrows which start from nothing and point to the build_template boxes? I realize that there are multiple different 'types' of templates, which each follow a slightly different code path, but there is only one 'type' of page. I don't understand what these elements are supposed to be representing.

I am also concerned that the render objects (green ovals) could be misleading. In the build_template box, render obviously refers to the template, and that is fine. But in the two 'page' boxes (populate_page and build_page), render does not mean "render page." In the one instance it means "render Markdown" and in the other it means "render template". The two outer boxes combined result in one "render page" (which is not represented in the diagram at all) I wonder if we should clarify what is being rendered in each instance. Perhaps use render Markdown and render template or something to that effect?

I considered if perhaps both the populate_page and build_page boxes should be wrapped in an outer box which represents all 'page' relates steps, but then I realized that on_env needs to be a step between those two inner boxes, but, it should be outside the outer box. Maybe someone could find a clever way to represent that, but I certainly am not going to try and don't expect that we will include such a change. I only mention it in the event that someone does have an idea of a good way to do so. If not, that's fine.

Finally, moving on to the general design, please don't take this the wrong way, but I find it ugly. I'm no designer, but in my opinion, the colors do not work with the site design and the wavy lines seem inappropriate to me. Some of the sweeping curves look fine, but others come across as very haphazard (or hand-drawn) to me. I would have expected straight lines, with sharp corners. But then, what do I know. Diagrams are not my thing. Still, I wonder if the general look could be improved so that it looks like if belongs on the site. I realize this is completely subjective and opinions differ. But if we can improve it, then we should.

Agree to most of your points. Some of the instructions seem weird and the duplicate cases could easily be combined into a single box of that type. But maybe the reason behind this is specific event-cases or something?

Also, to be fair here: This is a generated flowchart by mermaid.js, so it's not 100% perfect obviously. So for what it is, is it actually okay. Maybe the chart will improve if we get rid of the duplicate boxes.

@oprypin Something I wonder is, how a Left-to-Right version would look compared to the Top-to-Bottom one. Could you perhaps also provide such an example in a comment? I'm curious about this.

Left-to-right version

Well there's something to it, but would need to figure out some solution to scroll it horizontally and ideally expand it fully.

diff --git a/docs/img/plugin-events.py b/docs/img/plugin-events.py
index 6f30b981d..401834fd0 100644
--- a/docs/img/plugin-events.py
+++ b/docs/img/plugin-events.py
@@ -9,7 +9,7 @@ from graphviz import Digraph
 
 
 g = Digraph("MkDocs", format="svg")
-g.attr(compound="true", bgcolor="transparent")
+g.attr(compound="true", rankdir="LR", bgcolor="transparent")
 g.graph_attr.update(fontname="inherit", tooltip=" ")
 g.node_attr.update(fontname="inherit", tooltip=" ", style="filled")
 g.edge_attr.update(fontname="inherit", tooltip=" ")
@@ -49,11 +49,11 @@ def edge(g, a, b, dashed=False, **kwargs):
         b = subgraph_to_first_node[b]
 
     if a.startswith(("on_", "placeholder_")):
-        a += ":s"
+        a += ":e"
     else:
         node(g, a.split(":")[0])
     if b.startswith(("on_", "placeholder_")):
-        b += ":n"
+        b += ":w"
     else:
         node(g, b.split(":")[0])

Also, to be fair here: This is a generated flowchart by mermaid.js, so it's not 100% perfect obviously. So for what it is, is it actually okay. Maybe the chart will improve if we get rid of the duplicate boxes.

Ah, I missed that detail. That explains the lack of alignment, among other oddities.

For what it's worth (probably not much), I like the ortho option best. At least I would if there was some more spacing added between the lines and the objects. As it is now, its terrible. But I'm guessing that such adjustments aren't available in a generated diagram. in their current state, I think the lines option is the easiest to read. If only the lines didn't cut right through the boxes. I suspect I won't find any "generated" diagram acceptable. But then, as I've mentioned, I'm generally biased against diagrams in general.

I realize I'm being overly picky here. What is bothering me is the "because we know its generated we can excuse the less than ideal output" sort of thinking. Sorry, but I don't buy that. If the output is not good enough, then it is not good enough. I'm resisting the urge to demand that the diagram should be custom crafted as I realize that is a lot more work and time, but I suspect it would look a lot better. In any event, these comments probably aren't all that helpful. I'm just trying to explain my hesitation to approve this. I'm not saying we can't include a diagram. But I am saying that I don't think the diagram is acceptable in its current state and from what I've seen may not ever be with the tools used to create it. Some seem to suggest that a bad diagram is better than none, but I'm having a hard time accepting that.

I don't know why I made the mistake of opening a PR.
I'll just cut my losses here.

Well... that took a sudden turn

Overall, I think it was starting to look pretty good. The weird multiple populate_page, build_template, and build_page were the main standout issues I noticed.

In my case (a casual user who would like to create a plugin or add some hooks). It gives an overview of the process and some pointers to some functions, without having to read code. So both a good starting point and a reference.
I came across it once and struggled to find it back expecting to find it in the core documentation, btw.

thanks @oprypin

Yeah, thanks! I've found myself repeatedely looking up this PR. Great to have it in the docs.