Remove hack changing the order of plugin execution

Instead, now informs and warns users

Author: timvink

README.md

@@ -37,6 +37,8 @@ plugins:
   - enumerate-headings
 ```
 
+> MkDocs executes plugins in the order they are defined. If you use any other plugins that alter the navigation, make sure to define them *before* the `enumerate-headings` plugin.
+
 > If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set.
 
 ## Usage

mkdocs_enumerate_headings_plugin/plugin.py

@@ -32,27 +32,39 @@ def on_pre_build(self, config, **kwargs):
 
     def on_config(self, config, **kwargs):
 
-        # Move plugin to be last in the plugins list
-        # Because some plugins alter the navigation, and we need the final navigation
-        # This hack might not be necessary in future MkDocs versions, when `nav` is available on other later events as well
-        plugins = config["plugins"]
-        plugins.move_to_end("enumerate-headings")
-
-        # Move plugin's on_nav event to be last to run
-        # Because some plugins alter the navigation, and we need the final navigation
-        # This hack might not be necessary in future MkDocs versions, when `nav` is available on other later events as well
-        nav_events = plugins.events["nav"]
-
-        def get_plugin_name(bound_method):
-            return type(bound_method.__self__).__name__
-
-        plugin_nav_event = [
-            e for e in nav_events if get_plugin_name(e) == "EnumerateHeadingsPlugin"
-        ][0]
-        nav_events.append(nav_events.pop(nav_events.index(plugin_nav_event)))
-        plugins.events["nav"] = nav_events
-
-        config["plugins"] = plugins
+        # This plugin needs the navigation
+        # But some plugins alter the navigation
+        # MkDocs executes plugins in order they are defined
+        # So we can do some checks on other plugins defined.
+
+        plugins = [*dict(config["plugins"])]
+
+        def check_position(plugin):
+            if plugin in plugins:
+                if plugins.index("enumerate-headings") < plugins.index(plugin):
+                    logging.warning(
+                        "[enumerate-headings-plugin] enumerate-headings should be defined after the %s plugin in your mkdocs.yml file"
+                        % plugin
+                    )
+
+        # Check list of plugins that alter the navigation
+        # To make sure they are not defined after the enumerate-heading plugin
+        # taken from https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#navigation--page-building
+        check_plugins = [
+            "monorepo",
+            "exclude",
+            "select-files",
+            "awesome-pages",
+            "mkdocs-nav-enhancements",
+            "navtitles",
+            "encryptcontent",
+            "awesome-list",
+            "toc-sidebar",
+            "mkdocs-simple-hooks",
+        ]
+        for p in check_plugins:
+            check_position(p)
+
         return config
 
     def on_nav(self, nav, config, files, **kwargs):

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name="mkdocs-enumerate-headings-plugin",
-    version="0.4.1",
+    version="0.4.2",
     description="MkDocs Plugin to enumerate the headings (h1-h6) across site pages",
     long_description=long_description,
     long_description_content_type="text/markdown",

tests/test_builds.py

@@ -183,13 +183,19 @@ def test_compatibility_monorepo_plugin1(self, tmp_path):
         assert re.search(r"2.</span> Hello world!", contents)
 
     @pytest.mark.skip(reason="monorepo v0.4.9 is broken in production")
-    def test_compatibility_monorepo_plugin2(self, tmp_path):
+    def test_compatibility_monorepo_plugin2(self, tmp_path, caplog):
         tmp_proj = setup_clean_mkdocs_folder(
             "tests/fixtures/projects/monorepo_ok/mkdocs_enum_first.yml", tmp_path
         )
         result = build_docs_setup(tmp_proj)
         assert result.exit_code == 0, "'mkdocs build' command failed"
 
+        # Make sure warning is raised
+        assert (
+            "[enumerate-headings-plugin] enumerate-headings should be defined after"
+            in caplog.text
+        )
+
         page = tmp_proj / "site/test/index.html"
         contents = page.read_text(encoding="utf-8")
         assert re.search(r"2.</span> Hello world!", contents)
@@ -207,14 +213,20 @@ def test_compatibility_monorepo_plugin3(self, tmp_path):
         assert re.search(r"7.</span> Changelog", contents)
 
     @pytest.mark.skip(reason="monorepo v0.4.9 is broken in production")
-    def test_compatibility_monorepo_plugin4(self, tmp_path):
+    def test_compatibility_monorepo_plugin4(self, tmp_path, caplog):
         tmp_proj = setup_clean_mkdocs_folder(
             "tests/fixtures/projects/monorepo_sample_docs/mkdocs_enum_first.yml",
             tmp_path,
         )
         result = build_docs_setup(tmp_proj)
         assert result.exit_code == 0, "'mkdocs build' command failed"
 
+        # Make sure warning is raised
+        assert (
+            "[enumerate-headings-plugin] enumerate-headings should be defined after"
+            in caplog.text
+        )
+
         page = tmp_proj / "site/versions/v2/changelog/index.html"
         contents = page.read_text(encoding="utf-8")
         assert re.search(r"7.</span> Changelog", contents)
@@ -236,20 +248,26 @@ def test_compatibility_awesomepages_plugin1(tmp_path):
     assert re.search(r"1.</span> Page 4", contents)
 
 
-def test_compatibility_awesomepages_plugin2(tmp_path):
+def test_compatibility_awesomepages_plugin2(tmp_path, caplog):
     tmp_proj = setup_clean_mkdocs_folder(
         "tests/fixtures/projects/awesome_pages/mkdocs_enum_first.yml", tmp_path
     )
     result = build_docs_setup(tmp_proj)
     assert result.exit_code == 0, "'mkdocs build' command failed"
 
-    page = tmp_proj / "site/index.html"
-    contents = page.read_text(encoding="utf-8")
-    assert re.search(r"5.</span> Homepage", contents)
+    # Make sure warning is raised
+    assert (
+        "[enumerate-headings-plugin] enumerate-headings should be defined after"
+        in caplog.text
+    )
 
-    page = tmp_proj / "site/section2/page4/index.html"
-    contents = page.read_text(encoding="utf-8")
-    assert re.search(r"1.</span> Page 4", contents)
+    # page = tmp_proj / "site/index.html"
+    # contents = page.read_text(encoding="utf-8")
+    # assert re.search(r"5.</span> Homepage", contents)
+
+    # page = tmp_proj / "site/section2/page4/index.html"
+    # contents = page.read_text(encoding="utf-8")
+    # assert re.search(r"1.</span> Page 4", contents)
 
 
 def test_compatibility_material(tmp_path):