mkdocs-easylinks-plugin 0.1.1__py3-none-any.whl

mkdocs_easylinks/__init__.py

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

mkdocs_easylinks/plugin.py

@@ -0,0 +1,305 @@
+"""MkDocs plugin for easy cross-references using only filenames."""
+
+import os
+import re
+import logging
+import fnmatch
+from typing import Dict, Optional, Tuple
+from collections import defaultdict
+from mkdocs.config import config_options
+from mkdocs.config.base import Config
+from mkdocs.plugins import BasePlugin
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+from mkdocs.config.defaults import MkDocsConfig
+
+logger = logging.getLogger("mkdocs.plugins.easylinks")
+
+
+class EasyLinksConfig(Config):
+    warn_on_missing = config_options.Type(bool, default=True)
+    warn_on_ambiguous = config_options.Type(bool, default=True)
+    ignore_files = config_options.Type(list, default=[])
+    exclude_dirs = config_options.Type(list, default=[])
+    show_stats = config_options.Type(bool, default=False)
+
+
+class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
+    """Plugin to resolve markdown links by filename only."""
+
+    _link_pattern = re.compile(r'(!)?\[([^\]]+)\]\(([^)]+)\)')
+
+    def __init__(self):
+        super().__init__()
+        self.file_map: Dict[str, str] = {}
+        self.ambiguous_files: Dict[str, list] = {}
+        # Statistics tracking
+        self.stats = {
+            "total_files_scanned": 0,
+            "files_indexed": 0,
+            "files_ignored": 0,
+            "links_processed": 0,
+            "links_resolved": 0,
+            "links_unresolved": 0,
+            "images_processed": 0,
+            "images_resolved": 0,
+            "images_unresolved": 0,
+        }
+        self.link_counts = defaultdict(int)  # Track how many times each file is linked
+
+    def on_files(self, files: Files, *, config: MkDocsConfig) -> Files:
+        """Build a mapping of filenames to their full paths."""
+        self.file_map = {}
+        self.ambiguous_files = {}
+        self.stats = {key: 0 for key in self.stats}
+        self.link_counts = defaultdict(int)
+
+        # Process all files (documentation pages, images, etc.)
+        for file in files:
+            self.stats["total_files_scanned"] += 1
+            filename = os.path.basename(file.src_path)
+
+            # Ignore files starting with a dot (hidden files)
+            if filename.startswith('.'):
+                self.stats["files_ignored"] += 1
+                continue
+
+            # Check if file is in an excluded directory
+            if self._is_excluded_dir(file.src_path):
+                self.stats["files_ignored"] += 1
+                continue
+
+            # Ignore files matching patterns in ignore_files
+            if self._should_ignore_file(filename):
+                self.stats["files_ignored"] += 1
+                continue
+
+            if filename in self.file_map:
+                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
+            else:
+                self.file_map[filename] = file.src_path
+                self.stats["files_indexed"] += 1
+
+        # Warn about ambiguous files
+        if self.config["warn_on_ambiguous"] and self.ambiguous_files:
+            for filename, paths in self.ambiguous_files.items():
+                logger.warning(
+                    f"easylinks: Ambiguous filename '{filename}' found in multiple locations:\n"
+                    + "\n".join(f"  - {path}" for path in paths)
+                    + "\nLinks to this file will use the first occurrence. "
+                    "Consider using full paths for disambiguation."
+                )
+
+        return files
+
+    def _is_excluded_dir(self, file_path: str) -> bool:
+        """Check if a file is in an excluded directory."""
+        if not self.config["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
+
+    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
+
+    def on_page_markdown(
+        self, markdown: str, *, page: Page, config: MkDocsConfig, files: Files
+    ) -> str:
+        """Replace simple filename links with full path links."""
+        return self._process_links(markdown, page)
+
+    def _process_links(self, markdown: str, page: Page) -> str:
+        """Process markdown links and image links, replacing simple filenames with full paths."""
+        # Extract code fences and HTML comments before processing
+        markdown, protected_blocks = self._extract_protected_blocks(markdown)
+
+        def replace_link(match):
+            is_image = match.group(1)  # Will be '!' for images, None for regular links
+            link_text = match.group(2)
+            link_url = match.group(3)
+
+            # Skip if it's an external link, anchor, or absolute path
+            if (link_url.startswith(('http://', 'https://', '//', '#', '/'))
+                    or (':' in link_url and not link_url.startswith('file:'))):
+                return match.group(0)
+
+            # Extract anchor if present (only relevant for links, not images)
+            anchor = ""
+            if "#" in link_url:
+                link_url, anchor = link_url.split("#", 1)
+                anchor = "#" + anchor
+
+            # Check if this is just a filename (no path separators)
+            if "/" not in link_url and "\\" not in link_url:
+                # Track statistics
+                if is_image:
+                    self.stats["images_processed"] += 1
+                else:
+                    self.stats["links_processed"] += 1
+
+                resolved_path = self._resolve_filename(link_url)
+                if resolved_path:
+                    # Warn if this filename is ambiguous
+                    if self.config["warn_on_ambiguous"] and link_url in self.ambiguous_files:
+                        all_paths = self.ambiguous_files[link_url]
+                        logger.warning(
+                            f"easylinks: Ambiguous filename '{link_url}' referred to in "
+                            f"'{page.file.src_path}': exists at {all_paths}. "
+                            f"Using '{resolved_path}'."
+                        )
+
+                    # Track successful resolution
+                    if is_image:
+                        self.stats["images_resolved"] += 1
+                    else:
+                        self.stats["links_resolved"] += 1
+                        # Count how many times each file is linked
+                        self.link_counts[resolved_path] += 1
+
+                    # Calculate relative path from current page to target
+                    relative_path = self._get_relative_path(page.file.src_path, resolved_path)
+                    # Reconstruct with or without the ! prefix
+                    prefix = "!" if is_image else ""
+                    return f"{prefix}[{link_text}]({relative_path}{anchor})"
+                else:
+                    # Track unresolved links/images separately
+                    if is_image:
+                        self.stats["images_unresolved"] += 1
+                    else:
+                        self.stats["links_unresolved"] += 1
+
+                    if self.config["warn_on_missing"]:
+                        file_type = "image" if is_image else "file"
+                        logger.warning(
+                            f"easylinks: Could not resolve {file_type} link to '{link_url}' on page '{page.file.src_path}'"
+                        )
+
+            return match.group(0)
+
+        markdown = self._link_pattern.sub(replace_link, markdown)
+
+        # Restore code fences and HTML comments
+        markdown = self._restore_protected_blocks(markdown, protected_blocks)
+
+        return markdown
+
+    def _extract_protected_blocks(self, markdown: str) -> Tuple[str, dict]:
+        """Extract code fences and HTML comments, replacing them with placeholders.
+
+        Note: Only explicit fenced code blocks (``` or ~~~) are protected.
+        Indented content (like in MkDocs admonitions) is NOT protected and will
+        be processed normally. This is intentional to support MkDocs features.
+        """
+        protected_blocks = {}
+        counter = 0
+
+        def make_placeholder(match):
+            nonlocal counter
+            placeholder = f"___PROTECTED_BLOCK_{counter}___"
+            protected_blocks[placeholder] = match.group(0)
+            counter += 1
+            return placeholder
+
+        # Match fenced code blocks (both ``` and ~~~)
+        # Indented code blocks are NOT protected to support MkDocs admonitions
+        markdown = re.sub(
+            r'^```[\s\S]*?^```|^~~~[\s\S]*?^~~~',
+            make_placeholder,
+            markdown,
+            flags=re.MULTILINE
+        )
+
+        # Extract HTML comments
+        markdown = re.sub(
+            r'<!--[\s\S]*?-->',
+            make_placeholder,
+            markdown
+        )
+
+        return markdown, protected_blocks
+
+    def _restore_protected_blocks(self, markdown: str, protected_blocks: dict) -> str:
+        """Restore protected blocks from placeholders."""
+        for placeholder, original in protected_blocks.items():
+            markdown = markdown.replace(placeholder, original)
+        return markdown
+
+    def _resolve_filename(self, filename: str) -> Optional[str]:
+        """Resolve a filename to its full path within the docs."""
+        # Check if file exists in our mapping
+        if filename in self.ambiguous_files:
+            # Return the first occurrence for ambiguous files
+            return self.ambiguous_files[filename][0]
+
+        return self.file_map.get(filename)
+
+    def _get_relative_path(self, from_path: str, to_path: str) -> str:
+        """Calculate relative path from one file to another."""
+        from_dir = os.path.dirname(from_path)
+        rel = os.path.relpath(to_path, from_dir) if from_dir else to_path
+        return rel.replace("\\", "/")
+
+    def on_post_build(self, *, config: MkDocsConfig) -> None:
+        """Display statistics after the build completes."""
+        if not self.config["show_stats"]:
+            return
+
+        logger.info("=" * 60)
+        logger.info("EasyLinks Plugin Statistics")
+        logger.info("=" * 60)
+
+        # 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 ignored: {self.stats['files_ignored']}")
+
+        # Link statistics
+        logger.info(f"\nLinks processed: {self.stats['links_processed']}")
+        logger.info(f"Links resolved: {self.stats['links_resolved']}")
+        logger.info(f"Links unresolved: {self.stats['links_unresolved']}")
+
+        # Image statistics
+        logger.info(f"\nImages processed: {self.stats['images_processed']}")
+        logger.info(f"Images resolved: {self.stats['images_resolved']}")
+        logger.info(f"Images unresolved: {self.stats['images_unresolved']}")
+
+        # Most linked files
+        if self.link_counts:
+            logger.info(f"\nMost frequently linked files (top 10):")
+            sorted_links = sorted(self.link_counts.items(), key=lambda x: x[1], reverse=True)
+            for path, count in sorted_links[:10]:
+                logger.info(f"  {count:3d}x  {path}")
+
+        # Orphaned files (files that are indexed but never linked)
+        orphaned = set(self.file_map.values()) - set(self.link_counts.keys())
+        if orphaned:
+            logger.info(f"\nOrphaned files (indexed but never linked): {len(orphaned)}")
+            # Show first 10
+            for path in sorted(orphaned)[:10]:
+                logger.info(f"  - {path}")
+            if len(orphaned) > 10:
+                logger.info(f"  ... and {len(orphaned) - 10} more")
+
+        logger.info("=" * 60)

mkdocs_easylinks_plugin-0.1.1.dist-info/METADATA

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: mkdocs-easylinks-plugin
+Version: 0.1.1
+Summary: An MkDocs plugin that allows linking to files by filename only
+Author: Daniel Ferguson
+License: MIT
+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: 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
+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"
+Dynamic: license-file
+
+# MkDocs EasyLinks Plugin
+
+An MkDocs plugin that allows you to create cross-references and embed images by specifying only the filename, without needing to know the full path.
+
+## Features
+
+- **Simple linking**: Reference any file in your docs with just its filename
+- **Image support**: Embed images using simple filenames like `![alt](image.png)`
+- **Automatic resolution**: The plugin finds the file and generates the correct relative path
+- **Glob patterns**: Use wildcards to ignore multiple files (e.g., `draft-*.md`, `*.tmp`)
+- **Directory exclusion**: Exclude entire directories from being indexed
+- **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
+
+## Installation
+
+```bash
+pip install mkdocs-easylinks-plugin
+```
+
+Or install directly from source:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+Add the plugin to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - search
+  - easylinks
+```
+
+### Configuration Options
+
+```yaml
+plugins:
+  - easylinks:
+      warn_on_missing: true      # Warn when a file can't be found (default: true)
+      warn_on_ambiguous: true    # Warn when multiple files have the same name (default: true)
+      ignore_files: []           # List of filenames/patterns to ignore (default: [])
+      exclude_dirs: []           # List of directories to exclude (default: [])
+      show_stats: false          # Show link statistics after build (default: false)
+```
+
+#### Available Options
+
+- **`warn_on_missing`** (bool, default: `true`): Show warnings when a linked file cannot be found
+- **`warn_on_ambiguous`** (bool, default: `true`): Show warnings when multiple files share the same name
+- **`ignore_files`** (list, default: `[]`): List of filenames/patterns to exclude from link resolution (supports glob patterns)
+- **`exclude_dirs`** (list, default: `[]`): List of directories to exclude completely
+- **`show_stats`** (bool, default: `false`): Display link statistics after the build completes
+
+#### Ignoring Specific Files
+
+Use `ignore_files` to exclude certain files. Supports both exact matches and glob patterns:
+
+```yaml
+plugins:
+  - easylinks:
+      ignore_files:
+        - draft.md           # Exact match
+        - template.md        # Exact match
+        - "draft-*.md"       # Glob pattern - all files starting with "draft-"
+        - "*.tmp"            # Glob pattern - all .tmp files
+        - "test_*"           # Glob pattern - all files starting with "test_"
+```
+
+#### Excluding Directories
+
+Use `exclude_dirs` to exclude entire directories:
+
+```yaml
+plugins:
+  - easylinks:
+      exclude_dirs:
+        - drafts/
+        - templates/
+        - .archive/
+```
+
+All files in these directories (and subdirectories) will be excluded from indexing.
+
+> **Note:** Directory paths are matched as prefixes against each file's path within the docs directory. This means `exclude_dirs: ["api"]` excludes `api/page.md` but **not** `docs/api/page.md`. To exclude a nested directory, specify the full path from the docs root: `exclude_dirs: ["docs/api"]`.
+
+#### Link Statistics
+
+Enable `show_stats` to see detailed statistics after your build:
+
+```yaml
+plugins:
+  - easylinks:
+      show_stats: true
+```
+
+This will display:
+- Files scanned and indexed
+- Links processed, resolved, and unresolved
+- Images processed, resolved, and unresolved
+- Most frequently linked files
+- Orphaned files (indexed but never linked)
+
+## Examples
+
+### Documentation Links
+
+Instead of writing:
+
+```markdown
+[See the guide](../../advanced/guides/configuration.md)
+```
+
+You can now write:
+
+```markdown
+[See the guide](configuration.md)
+```
+
+The plugin will automatically resolve `configuration.md` to its full path and generate the correct relative link.
+
+### Images
+
+Works with images too! Instead of:
+
+```markdown
+![Diagram](../../assets/images/architecture.png)
+```
+
+Just write:
+
+```markdown
+![Diagram](architecture.png)
+```
+
+### With Anchors
+
+Anchors work for document links:
+
+```markdown
+[See section](somefile.md#advanced-features)
+```
+
+### What Links Are Processed
+
+**Processed** (converted to full paths):
+- `[text](filename.md)` - Simple document filenames
+- `[text](file.md#anchor)` - Document filenames with anchors
+- `![alt](image.png)` - Simple image filenames (png, jpg, svg, gif, etc.)
+
+**Not processed** (left as-is):
+- `[text](https://example.com)` - External URLs
+- `![alt](https://example.com/image.png)` - External images
+- `[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 (`<!-- -->`)
+
+### Protected Content
+
+The plugin intelligently ignores links in:
+
+**Code fences:**
+````markdown
+```python
+# This [link](example.md) won't be processed
+```
+````
+
+**HTML comments:**
+```markdown
+<!-- This [link](example.md) won't be processed -->
+```
+
+This ensures that example code and commented-out content remain unchanged.
+
+**Important: Indented Content**
+
+Only explicit code fences (``` or ~~~) are protected. Indented content, such as in MkDocs admonitions, **is processed normally**:
+
+```markdown
+!!! note
+    This [link](guide.md) WILL be processed.
+    The plugin works inside admonitions!
+```
+
+This design choice ensures the plugin works seamlessly with MkDocs features like admonitions, which rely heavily on indentation.
+
+## How It Works
+
+1. During the build, the plugin scans all files (documentation, images, assets, etc.)
+2. It creates a mapping of filenames to their full paths
+3. When processing each page, it finds markdown links and images with simple filenames
+4. It replaces them with the correct relative path from the current page to the target
+
+**Files that are excluded from mapping:**
+- Files starting with `.` (dotfiles) - always ignored
+- Files listed in `ignore_files` configuration - useful for drafts and templates
+
+## Using with mkdocs-macros-plugin (Snippets)
+
+If you use [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) to include snippet files via `{% include '...' %}`, easylinks works correctly with no extra configuration — as long as the plugin order in `mkdocs.yml` is correct:
+
+```yaml
+plugins:
+  - macros:
+      include_dir: docs/.snippets
+  - easylinks        # must come after macros
+```
+
+Because macros runs first, snippet content is inlined into the page before easylinks processes it. Links in snippets are resolved relative to the **including page**, not the snippet file itself — which is exactly the right behaviour when a snippet may be included from pages at different directory levels.
+
+**Best practices:**
+
+- Always list `easylinks` after `macros` in your `plugins` configuration.
+- Use simple filename links (e.g. `[text](target.md)`) in your snippets rather than relative paths, since relative paths would break when the same snippet is included from different locations.
+- If your snippets directory could contain files whose names clash with published docs files, add it to `exclude_dirs` to prevent false ambiguity warnings:
+
+```yaml
+plugins:
+  - easylinks:
+      exclude_dirs: ['.snippets']
+```
+
+## Handling Ambiguous Filenames
+
+If you have multiple files with the same name (e.g., `index.md` in different folders), the plugin will:
+
+1. Warn you about the ambiguity
+2. Use the first occurrence found
+3. Recommend using full paths for those specific files
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/dsferg/mkdocs-easylinks-plugin.git
+cd mkdocs-easylinks-plugin
+
+# Install in development mode
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

mkdocs_easylinks_plugin-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+mkdocs_easylinks/__init__.py,sha256=M2lR8vBkkdgXh50QhguwlTZvmWvJyGgR0VzXBB68aB0,97
+mkdocs_easylinks/plugin.py,sha256=2ibhM3614UUGMtMZhPXx3lT8jsomoF98I6O1pq0zjbg,12412
+mkdocs_easylinks_plugin-0.1.1.dist-info/licenses/LICENSE,sha256=dPBp6YMZ7j-4u99ZFKB3n3aVSAZ7kbZxdvJoKW_vV2I,1072
+mkdocs_easylinks_plugin-0.1.1.dist-info/METADATA,sha256=1ADTukmaxg3hCUBUQgBh7M5Ln4gyRPWIFSiCXQuxnug,9182
+mkdocs_easylinks_plugin-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mkdocs_easylinks_plugin-0.1.1.dist-info/entry_points.txt,sha256=TapjTFtRdQu0AygregEKyirmeWn0LZgvTOBSFDJeLSE,69
+mkdocs_easylinks_plugin-0.1.1.dist-info/top_level.txt,sha256=m1XUzruB4-Zu2zavZksLm1o_YoZJAg4fSapZDnvH9WA,17
+mkdocs_easylinks_plugin-0.1.1.dist-info/RECORD,,

mkdocs_easylinks_plugin-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mkdocs_easylinks_plugin-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+easylinks = mkdocs_easylinks.plugin:EasyLinksPlugin

mkdocs_easylinks_plugin-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Ferguson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_easylinks_plugin-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+mkdocs_easylinks