mkdocs-nav-numbering-plugin 0.1.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

mkdocs_nav_numbering_plugin/nav_numbering.py

@@ -1,4 +1,5 @@
 import re
+import unicodedata
 from typing import Dict, List
 
 from mkdocs.config import config_options
@@ -6,6 +7,39 @@ from mkdocs.plugins import BasePlugin
 from mkdocs.structure.nav import Navigation, Section, Page, Link
 
 
+def slugify(text: str) -> str:
+    """
+    Convert text to a URL-friendly slug, matching MkDocs' default toc behavior.
+
+    - Converts to lowercase
+    - Normalizes unicode characters
+    - Replaces spaces and underscores with hyphens
+    - Removes non-alphanumeric characters (except hyphens)
+    - Collapses multiple hyphens into one
+    - Strips leading/trailing hyphens
+    """
+    # Normalize unicode characters (e.g., accented chars -> base form)
+    text = unicodedata.normalize("NFKD", text)
+    text = text.encode("ascii", "ignore").decode("ascii")
+
+    # Convert to lowercase
+    text = text.lower()
+
+    # Replace spaces and underscores with hyphens
+    text = re.sub(r"[\s_]+", "-", text)
+
+    # Remove non-alphanumeric characters except hyphens
+    text = re.sub(r"[^\w-]", "", text)
+
+    # Collapse multiple hyphens into one
+    text = re.sub(r"-+", "-", text)
+
+    # Strip leading/trailing hyphens
+    text = text.strip("-")
+
+    return text
+
+
 class NavNumberingPlugin(BasePlugin):
     """
     MkDocs plugin to add hierarchical numbering to navigation items and page headings.
@@ -19,6 +53,7 @@ class NavNumberingPlugin(BasePlugin):
         number_h1: Add number to the first h1 (page title) (default: true)
         separator: Separator between number parts (default: ".")
         exclude: List of page paths to exclude from numbering (default: [])
+        preserve_anchor_ids: Preserve original anchor IDs without number prefixes (default: false)
     """
 
     config_scheme = (
@@ -30,6 +65,7 @@ class NavNumberingPlugin(BasePlugin):
         ("number_h1", config_options.Type(bool, default=True)),
         ("separator", config_options.Type(str, default=".")),
         ("exclude", config_options.Type(list, default=[])),
+        ("preserve_anchor_ids", config_options.Type(bool, default=False)),
     )
 
     def __init__(self):
@@ -97,6 +133,9 @@ class NavNumberingPlugin(BasePlugin):
         Prepend the nav number to headings inside each page.
         - The first h1 (page title) gets the base_number (e.g., 3.1.1)
         - Subsequent h2, h3, etc. get sub-numbers (e.g., 3.1.1.1, 3.1.1.2)
+
+        When preserve_anchor_ids is enabled, explicit {#slug} attributes are added
+        to headings to preserve the original anchor IDs without number prefixes.
         """
         if not self.config["enabled"] or not self.config["number_headings"]:
             return markdown
@@ -109,6 +148,7 @@ class NavNumberingPlugin(BasePlugin):
         heading_depth = self.config["heading_depth"]
         number_h1 = self.config["number_h1"]
         separator = self.config["separator"]
+        preserve_anchor_ids = self.config["preserve_anchor_ids"]
         base_depth = len(base_number.split(separator))
 
         # Track whether we've seen the first h1 (page title)
@@ -118,11 +158,42 @@ class NavNumberingPlugin(BasePlugin):
         # h2 -> counter[0], h3 -> counter[1], etc.
         counters: List[int] = []
 
+        # Track used slugs for duplicate detection (per page)
+        used_slugs: Dict[str, int] = {}
+
+        def get_unique_slug(title: str) -> str:
+            """Generate a unique slug, adding suffix for duplicates."""
+            base_slug = slugify(title)
+            if not base_slug:
+                base_slug = "heading"
+
+            if base_slug not in used_slugs:
+                used_slugs[base_slug] = 0
+                return base_slug
+            else:
+                used_slugs[base_slug] += 1
+                return f"{base_slug}-{used_slugs[base_slug]}"
+
+        def extract_existing_id(title: str) -> tuple:
+            """
+            Extract existing {#custom-id} from title if present.
+            Returns (clean_title, existing_id) or (title, None).
+            """
+            match = re.search(r'\s*\{#([^}]+)\}\s*$', title)
+            if match:
+                existing_id = match.group(1)
+                clean_title = title[:match.start()].strip()
+                return clean_title, existing_id
+            return title, None
+
         def repl(match: re.Match) -> str:
             hashes = match.group("hashes")
-            title = match.group("title").strip()
+            raw_title = match.group("title").strip()
             level = len(hashes)  # "#"=1, "##"=2, etc.
 
+            # Check for existing {#custom-id} attribute
+            title, existing_id = extract_existing_id(raw_title)
+
             # Avoid double-numbering if already numbered
             if re.match(r"^\d+(\.\d+)*\s+", title):
                 return match.group(0)
@@ -132,12 +203,22 @@ class NavNumberingPlugin(BasePlugin):
                 if not first_h1_seen[0]:
                     first_h1_seen[0] = True
                     if number_h1:
+                        if preserve_anchor_ids and not existing_id:
+                            slug = get_unique_slug(title)
+                            return f"{hashes} {base_number} {title} {{#{slug}}}"
+                        elif existing_id:
+                            return f"{hashes} {base_number} {title} {{#{existing_id}}}"
                         return f"{hashes} {base_number} {title}"
                     return match.group(0)
                 else:
                     # Additional h1s in the same page - handle gracefully
                     counters.clear()
                     if number_h1:
+                        if preserve_anchor_ids and not existing_id:
+                            slug = get_unique_slug(title)
+                            return f"{hashes} {base_number} {title} {{#{slug}}}"
+                        elif existing_id:
+                            return f"{hashes} {base_number} {title} {{#{existing_id}}}"
                         return f"{hashes} {base_number} {title}"
                     return match.group(0)
 
@@ -162,6 +243,11 @@ class NavNumberingPlugin(BasePlugin):
             rel = separator.join(str(c) for c in counters[:adjusted_level])
             full_number = f"{base_number}{separator}{rel}"
 
+            if preserve_anchor_ids and not existing_id:
+                slug = get_unique_slug(title)
+                return f"{hashes} {full_number} {title} {{#{slug}}}"
+            elif existing_id:
+                return f"{hashes} {full_number} {title} {{#{existing_id}}}"
             return f"{hashes} {full_number} {title}"
 
         heading_pattern = re.compile(r"^(?P<hashes>#{1,6})\s+(?P<title>.+)$", re.MULTILINE)

{mkdocs_nav_numbering_plugin-0.1.0.dist-info → mkdocs_nav_numbering_plugin-1.1.0.dist-info}/METADATA

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: mkdocs-nav-numbering-plugin
-Version: 0.1.0
+Version: 1.1.0
 Summary: MkDocs plugin to add hierarchical numbering to nav and page headings
-Author: ZMT Zurich MedTech AG
+Author: Matus Drobuliak
 License: MIT
-Project-URL: Homepage, https://github.com/your-org/mkdocs-nav-numbering-plugin
-Project-URL: Repository, https://github.com/your-org/mkdocs-nav-numbering-plugin
-Project-URL: Issues, https://github.com/your-org/mkdocs-nav-numbering-plugin/issues
+Project-URL: Homepage, https://github.com/matusdrobuliak66/mkdocs-nav-numbering-plugin
+Project-URL: Repository, https://github.com/matusdrobuliak66/mkdocs-nav-numbering-plugin
+Project-URL: Issues, https://github.com/matusdrobuliak66/mkdocs-nav-numbering-plugin/issues
 Keywords: mkdocs,plugin,navigation,numbering,documentation
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Plugins
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -51,9 +51,13 @@ plugins:
       number_h1: true
       number_nav: true
       number_headings: true
+      preserve_anchor_ids: false
       separator: "."
       exclude:
         - index.md
+
+markdown_extensions:
+  - attr_list  # Required when preserve_anchor_ids is true
 ```
 
 ## Options
@@ -64,5 +68,21 @@ plugins:
 - `number_nav` (bool, default: true)
 - `number_headings` (bool, default: true)
 - `number_h1` (bool, default: true)
+- `preserve_anchor_ids` (bool, default: false) — Preserve original heading anchor IDs without number prefixes (requires `attr_list`)
 - `separator` (str, default: ".")
 - `exclude` (list, default: [])
+
+### `preserve_anchor_ids`
+
+By default, MkDocs generates heading IDs from the final heading text. Since this plugin prepends numbering, your anchors can end up including the numbers.
+
+Enable `preserve_anchor_ids: true` to add explicit `{#...}` IDs based on the original (un-numbered) heading text. Duplicate headings are automatically suffixed with `-1`, `-2`, etc.
+
+```yaml
+plugins:
+  - nav-numbering:
+      preserve_anchor_ids: true
+
+markdown_extensions:
+  - attr_list
+```

mkdocs_nav_numbering_plugin-1.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mkdocs_nav_numbering_plugin/__init__.py,sha256=McZEZwPtatKF0PvPVKMD7_nBeaOjdHNME6tQNwNIt8M,80
+mkdocs_nav_numbering_plugin/nav_numbering.py,sha256=AC6QEk7muwKj-BwklfAZJXGsmfKIqb4xLZodpJmPW6M,10779
+mkdocs_nav_numbering_plugin-1.1.0.dist-info/licenses/LICENSE,sha256=3xENzADezoOh8w__sH4AAF-e-757l_y4sooIAwjqpL0,1072
+mkdocs_nav_numbering_plugin-1.1.0.dist-info/METADATA,sha256=pEGEBi9VxtxinF__oATLP2c2mQ5WjJWhAt4FZIZGnuI,2760
+mkdocs_nav_numbering_plugin-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mkdocs_nav_numbering_plugin-1.1.0.dist-info/entry_points.txt,sha256=NnO7O_09mMyAHFIspg2zmsfri_m7nt8Km8xZK0tgvtQ,80
+mkdocs_nav_numbering_plugin-1.1.0.dist-info/top_level.txt,sha256=UcRwMarClerK-Iuj0RooOAq7IVhn_oRmQRiCZgSCfN4,28
+mkdocs_nav_numbering_plugin-1.1.0.dist-info/RECORD,,

{mkdocs_nav_numbering_plugin-0.1.0.dist-info → mkdocs_nav_numbering_plugin-1.1.0.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ZMT Zurich MedTech AG
+Copyright (c) 2026 Matus Drobuliak
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

mkdocs_nav_numbering_plugin-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-mkdocs_nav_numbering_plugin/__init__.py,sha256=McZEZwPtatKF0PvPVKMD7_nBeaOjdHNME6tQNwNIt8M,80
-mkdocs_nav_numbering_plugin/nav_numbering.py,sha256=zRiG9_AZdLKe21pnb_b_vQSw8LkWpL8HK6UdY14WoPc,7263
-mkdocs_nav_numbering_plugin-0.1.0.dist-info/licenses/LICENSE,sha256=o8hK_UrJ1kd51VuQ5ZP4d8gwK5WPlt6Zg5vO-T42eoo,1078
-mkdocs_nav_numbering_plugin-0.1.0.dist-info/METADATA,sha256=Erwhh43scMWp4QOY-uGORxkA-5TPRs88iZfNoqqoDew,2005
-mkdocs_nav_numbering_plugin-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-mkdocs_nav_numbering_plugin-0.1.0.dist-info/entry_points.txt,sha256=NnO7O_09mMyAHFIspg2zmsfri_m7nt8Km8xZK0tgvtQ,80
-mkdocs_nav_numbering_plugin-0.1.0.dist-info/top_level.txt,sha256=UcRwMarClerK-Iuj0RooOAq7IVhn_oRmQRiCZgSCfN4,28
-mkdocs_nav_numbering_plugin-0.1.0.dist-info/RECORD,,