mkdocs-easylinks-plugin 0.1.3__tar.gz → 0.2.0__tar.gz

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4
@@ -29,3 +29,20 @@ jobs:
 
       - name: Run tests
         run: pytest
+
+  typecheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run mypy
+        run: mypy mkdocs_easylinks --ignore-missing-imports

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2026-04-02
+
+### Removed
+- Dropped support for Python 3.8 and 3.9 (both EOL)
+
+## [0.1.4] - 2026-03-30
+
+### Changed
+- Pre-compiled code fence and HTML comment regex patterns as class-level constants for consistency and minor performance improvement
+- Excluded directories are now normalized once per build rather than on every file check
+- `_should_ignore_file` simplified to a single `any()` expression
+- `files_ambiguous` stat now tracked separately from `files_indexed`, making both counts accurate and meaningful
+- Development status classifier updated from Alpha to Beta
+- README stats section updated to reflect `files_ambiguous` and `files_ignored` counters
+
+### Fixed
+- `files_indexed` no longer counts ambiguous duplicate filenames — those are now counted in the new `files_ambiguous` stat
+
+### Dev
+- Added mypy type checking to CI (`typecheck` job in GitHub Actions)
+
 ## [0.1.3] - 2026-03-30
 
 ### Added

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-easylinks-plugin
-Version: 0.1.3
+Version: 0.2.0
 Summary: An MkDocs plugin that allows linking to files by filename only
 Author: Daniel Ferguson
 License: MIT
@@ -8,23 +8,22 @@ Project-URL: Homepage, https://github.com/dsferg/mkdocs-easylinks-plugin
 Project-URL: Documentation, https://github.com/dsferg/mkdocs-easylinks-plugin
 Project-URL: Repository, https://github.com/dsferg/mkdocs-easylinks-plugin
 Keywords: mkdocs,plugin,links,cross-references
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mkdocs>=1.4.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
 Dynamic: license-file
 
 # MkDocs EasyLinks Plugin
@@ -41,7 +40,7 @@ An MkDocs plugin that allows you to create cross-references and embed images by
 - **Link statistics**: See which files are most linked and find orphaned content
 - **Ambiguity warnings**: Get notified if multiple files share the same name
 - **Material for MkDocs compatible**: Works seamlessly with Material theme
-- **Smart protection**: Code fences and HTML comments are preserved unchanged
+- **Smart protection**: Code fences and HTML comments are preserved unchanged by default (configurable)
 
 ## Installation
 
@@ -126,7 +125,7 @@ plugins:
 ```
 
 This will display:
-- Files scanned and indexed
+- Files scanned, indexed, ambiguous, and ignored
 - Links processed, resolved, and unresolved
 - Images processed, resolved, and unresolved
 - Most frequently linked files
@@ -185,8 +184,8 @@ Anchors work for document links:
 - `[text](/absolute/path.md)` - Absolute paths
 - `[text](../relative/path.md)` - Explicit relative paths with directories
 - `[text](#anchor)` - Fragment-only links
-- Links/images inside code fences (` ``` ` or `~~~`)
-- Links/images inside HTML comments (`<!-- -->`)
+- Links/images inside code fences (` ``` ` or `~~~`) — unless `protect_code_fences: false`
+- Links/images inside HTML comments (`<!-- -->`) — unless `protect_html_comments: false`
 
 ### Protected Content
 
@@ -204,7 +203,7 @@ The plugin intelligently ignores links in:
 <!-- This [link](example.md) won't be processed -->
 ```
 
-This ensures that example code and commented-out content remain unchanged.
+This ensures that example code and commented-out content remain unchanged. Both behaviours are configurable via `protect_code_fences` and `protect_html_comments`.
 
 **Important: Indented Content**
 
@@ -228,6 +227,7 @@ This design choice ensures the plugin works seamlessly with MkDocs features like
 **Files that are excluded from mapping:**
 - Files starting with `.` (dotfiles) - always ignored
 - Files listed in `ignore_files` configuration - useful for drafts and templates
+- Files in directories listed in `exclude_dirs`
 
 ## Using with mkdocs-macros-plugin (Snippets)
 

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/README.md

@@ -12,7 +12,7 @@ An MkDocs plugin that allows you to create cross-references and embed images by
 - **Link statistics**: See which files are most linked and find orphaned content
 - **Ambiguity warnings**: Get notified if multiple files share the same name
 - **Material for MkDocs compatible**: Works seamlessly with Material theme
-- **Smart protection**: Code fences and HTML comments are preserved unchanged
+- **Smart protection**: Code fences and HTML comments are preserved unchanged by default (configurable)
 
 ## Installation
 
@@ -97,7 +97,7 @@ plugins:
 ```
 
 This will display:
-- Files scanned and indexed
+- Files scanned, indexed, ambiguous, and ignored
 - Links processed, resolved, and unresolved
 - Images processed, resolved, and unresolved
 - Most frequently linked files
@@ -156,8 +156,8 @@ Anchors work for document links:
 - `[text](/absolute/path.md)` - Absolute paths
 - `[text](../relative/path.md)` - Explicit relative paths with directories
 - `[text](#anchor)` - Fragment-only links
-- Links/images inside code fences (` ``` ` or `~~~`)
-- Links/images inside HTML comments (`<!-- -->`)
+- Links/images inside code fences (` ``` ` or `~~~`) — unless `protect_code_fences: false`
+- Links/images inside HTML comments (`<!-- -->`) — unless `protect_html_comments: false`
 
 ### Protected Content
 
@@ -175,7 +175,7 @@ The plugin intelligently ignores links in:
 <!-- This [link](example.md) won't be processed -->
 ```
 
-This ensures that example code and commented-out content remain unchanged.
+This ensures that example code and commented-out content remain unchanged. Both behaviours are configurable via `protect_code_fences` and `protect_html_comments`.
 
 **Important: Indented Content**
 
@@ -199,6 +199,7 @@ This design choice ensures the plugin works seamlessly with MkDocs features like
 **Files that are excluded from mapping:**
 - Files starting with `.` (dotfiles) - always ignored
 - Files listed in `ignore_files` configuration - useful for drafts and templates
+- Files in directories listed in `exclude_dirs`
 
 ## Using with mkdocs-macros-plugin (Snippets)
 

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/mkdocs_easylinks/__init__.py

@@ -1,3 +1,3 @@
 """MkDocs EasyLinks Plugin - Simplified cross-referencing by filename."""
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/mkdocs_easylinks/plugin.py

@@ -31,15 +31,19 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
     """Plugin to resolve markdown links by filename only."""
 
     _link_pattern = re.compile(r'(!)?\[([^\]]+)\]\(([^)]+)\)')
+    _code_fence_pattern = re.compile(r'^```[\s\S]*?^```|^~~~[\s\S]*?^~~~', re.MULTILINE)
+    _html_comment_pattern = re.compile(r'<!--[\s\S]*?-->')
 
     def __init__(self):
         super().__init__()
         self.file_map: Dict[str, str] = {}
         self.ambiguous_files: Dict[str, list] = {}
+        self._normalized_exclude_dirs: list = []
         # Statistics tracking
         self.stats = {
             "total_files_scanned": 0,
             "files_indexed": 0,
+            "files_ambiguous": 0,
             "files_ignored": 0,
             "links_processed": 0,
             "links_resolved": 0,
@@ -56,6 +60,9 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
         self.ambiguous_files = {}
         self.stats = {key: 0 for key in self.stats}
         self.link_counts = defaultdict(int)
+        self._normalized_exclude_dirs = [
+            d.replace("\\", "/").rstrip("/") + "/" for d in self.config["exclude_dirs"]
+        ]
 
         # Process all files (documentation pages, images, etc.)
         for file in files:
@@ -81,7 +88,7 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
                 if filename not in self.ambiguous_files:
                     self.ambiguous_files[filename] = [self.file_map[filename]]
                 self.ambiguous_files[filename].append(file.src_path)
-                self.stats["files_indexed"] += 1
+                self.stats["files_ambiguous"] += 1
             else:
                 self.file_map[filename] = file.src_path
                 self.stats["files_indexed"] += 1
@@ -100,32 +107,15 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
 
     def _is_excluded_dir(self, file_path: str) -> bool:
         """Check if a file is in an excluded directory."""
-        if not self.config["exclude_dirs"]:
+        if not self._normalized_exclude_dirs:
             return False
 
-        # Normalize the path
         normalized_path = file_path.replace("\\", "/")
-
-        for excluded_dir in self.config["exclude_dirs"]:
-            # Normalize excluded dir
-            excluded = excluded_dir.rstrip("/") + "/"
-            # Check if file path starts with excluded directory
-            if normalized_path.startswith(excluded):
-                return True
-
-        return False
+        return any(normalized_path.startswith(d) for d in self._normalized_exclude_dirs)
 
     def _should_ignore_file(self, filename: str) -> bool:
         """Check if a filename matches any ignore pattern (supports glob patterns)."""
-        if not self.config["ignore_files"]:
-            return False
-
-        for pattern in self.config["ignore_files"]:
-            # Support both exact match and glob patterns
-            if fnmatch.fnmatch(filename, pattern):
-                return True
-
-        return False
+        return any(fnmatch.fnmatch(filename, p) for p in self.config["ignore_files"])
 
     def on_page_markdown(
         self, markdown: str, *, page: Page, config: MkDocsConfig, files: Files
@@ -229,20 +219,11 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
         # Match fenced code blocks (both ``` and ~~~)
         # Indented code blocks are NOT protected to support MkDocs admonitions
         if self.config["protect_code_fences"]:
-            markdown = re.sub(
-                r'^```[\s\S]*?^```|^~~~[\s\S]*?^~~~',
-                make_placeholder,
-                markdown,
-                flags=re.MULTILINE
-            )
+            markdown = self._code_fence_pattern.sub(make_placeholder, markdown)
 
         # Extract HTML comments
         if self.config["protect_html_comments"]:
-            markdown = re.sub(
-                r'<!--[\s\S]*?-->',
-                make_placeholder,
-                markdown
-            )
+            markdown = self._html_comment_pattern.sub(make_placeholder, markdown)
 
         return markdown, protected_blocks
 
@@ -279,6 +260,7 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
         # File statistics
         logger.info(f"Files scanned: {self.stats['total_files_scanned']}")
         logger.info(f"Files indexed: {self.stats['files_indexed']}")
+        logger.info(f"Files ambiguous: {self.stats['files_ambiguous']}")
         logger.info(f"Files ignored: {self.stats['files_ignored']}")
 
         # Link statistics

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/mkdocs_easylinks_plugin.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-easylinks-plugin
-Version: 0.1.3
+Version: 0.2.0
 Summary: An MkDocs plugin that allows linking to files by filename only
 Author: Daniel Ferguson
 License: MIT
@@ -8,23 +8,22 @@ Project-URL: Homepage, https://github.com/dsferg/mkdocs-easylinks-plugin
 Project-URL: Documentation, https://github.com/dsferg/mkdocs-easylinks-plugin
 Project-URL: Repository, https://github.com/dsferg/mkdocs-easylinks-plugin
 Keywords: mkdocs,plugin,links,cross-references
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mkdocs>=1.4.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
 Dynamic: license-file
 
 # MkDocs EasyLinks Plugin
@@ -41,7 +40,7 @@ An MkDocs plugin that allows you to create cross-references and embed images by
 - **Link statistics**: See which files are most linked and find orphaned content
 - **Ambiguity warnings**: Get notified if multiple files share the same name
 - **Material for MkDocs compatible**: Works seamlessly with Material theme
-- **Smart protection**: Code fences and HTML comments are preserved unchanged
+- **Smart protection**: Code fences and HTML comments are preserved unchanged by default (configurable)
 
 ## Installation
 
@@ -126,7 +125,7 @@ plugins:
 ```
 
 This will display:
-- Files scanned and indexed
+- Files scanned, indexed, ambiguous, and ignored
 - Links processed, resolved, and unresolved
 - Images processed, resolved, and unresolved
 - Most frequently linked files
@@ -185,8 +184,8 @@ Anchors work for document links:
 - `[text](/absolute/path.md)` - Absolute paths
 - `[text](../relative/path.md)` - Explicit relative paths with directories
 - `[text](#anchor)` - Fragment-only links
-- Links/images inside code fences (` ``` ` or `~~~`)
-- Links/images inside HTML comments (`<!-- -->`)
+- Links/images inside code fences (` ``` ` or `~~~`) — unless `protect_code_fences: false`
+- Links/images inside HTML comments (`<!-- -->`) — unless `protect_html_comments: false`
 
 ### Protected Content
 
@@ -204,7 +203,7 @@ The plugin intelligently ignores links in:
 <!-- This [link](example.md) won't be processed -->
 ```
 
-This ensures that example code and commented-out content remain unchanged.
+This ensures that example code and commented-out content remain unchanged. Both behaviours are configurable via `protect_code_fences` and `protect_html_comments`.
 
 **Important: Indented Content**
 
@@ -228,6 +227,7 @@ This design choice ensures the plugin works seamlessly with MkDocs features like
 **Files that are excluded from mapping:**
 - Files starting with `.` (dotfiles) - always ignored
 - Files listed in `ignore_files` configuration - useful for drafts and templates
+- Files in directories listed in `exclude_dirs`
 
 ## Using with mkdocs-macros-plugin (Snippets)
 

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/mkdocs_easylinks_plugin.egg-info/requires.txt

@@ -3,3 +3,4 @@ mkdocs>=1.4.0
 [dev]
 pytest>=7.0
 pytest-cov>=4.0
+mypy>=1.0

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/pyproject.toml

@@ -4,22 +4,20 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mkdocs-easylinks-plugin"
-version = "0.1.3"
+version = "0.2.0"
 description = "An MkDocs plugin that allows linking to files by filename only"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 license = {text = "MIT"}
 authors = [
     {name = "Daniel Ferguson"}
 ]
 keywords = ["mkdocs", "plugin", "links", "cross-references"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -33,6 +31,7 @@ dependencies = [
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
+    "mypy>=1.0",
 ]
 
 [project.urls]

{mkdocs_easylinks_plugin-0.1.3 → mkdocs_easylinks_plugin-0.2.0}/tests/test_plugin.py

@@ -176,7 +176,7 @@ class TestEasyLinksPlugin:
         assert any("docs/about.md" in msg and "index.md" in msg for msg in caplog.messages)
 
     def test_ambiguous_files_counted_in_indexed_stats(self):
-        """Test that duplicate filenames are counted in files_indexed."""
+        """Test that duplicate filenames are counted in files_ambiguous, not files_indexed."""
         mock_config = MagicMock()
         mock_files = MagicMock(spec=Files)
 
@@ -189,7 +189,8 @@ class TestEasyLinksPlugin:
         self.plugin.on_files(mock_files, config=mock_config)
 
         assert self.plugin.stats["total_files_scanned"] == 3
-        assert self.plugin.stats["files_indexed"] == 3  # all three, including the duplicate
+        assert self.plugin.stats["files_indexed"] == 2    # unique filenames only
+        assert self.plugin.stats["files_ambiguous"] == 1  # duplicates tracked separately
         assert self.plugin.stats["files_ignored"] == 0
         assert "index.md" in self.plugin.ambiguous_files