mkdocs-easylinks-plugin 0.1.1__tar.gz

mkdocs_easylinks_plugin-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

mkdocs_easylinks_plugin-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest

mkdocs_easylinks_plugin-0.1.1/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

mkdocs_easylinks_plugin-0.1.1/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.1] - 2026-03-26
+
+### Fixed
+- Relative path calculation replaced with `os.path.relpath` — the previous custom algorithm could miscalculate paths for certain directory structures, producing silently broken links
+- `exclude_dirs` no longer incorrectly excludes directories whose names contain the excluded name as a substring (e.g. excluding `"api"` no longer excluded `"apidocs/"`)
+- Unresolved images now increment `images_unresolved` instead of `links_unresolved`, preventing misleading statistics
+- Duplicate filenames are now correctly counted in `files_indexed` statistics
+- `stats` and `link_counts` now reset on each build, preventing accumulation across rebuilds during `mkdocs serve` live reload
+- Restored `files` parameter to `on_page_markdown` signature for compatibility with MkDocs versions that pass all keyword arguments directly
+
+### Added
+- Per-page warning when a link resolves to an ambiguous filename, including the referring page path and all candidate locations
+- All plugin warnings now prefixed with `easylinks:` for easier identification in build output
+- `images_unresolved` statistic counter
+
+### Changed
+- Migrated plugin configuration from deprecated `config_scheme` tuple to typed `PluginConfig` class (MkDocs 1.5+ style)
+- Regex pattern for link matching compiled once at class level rather than per page
+- Removed unused `page` parameter from `_resolve_filename`
+- Merged duplicate closures in `_extract_protected_blocks` into a single function
+
+## [0.1.0] - Initial release
+
+- Simple filename-based link and image resolution
+- Automatic relative path calculation
+- Glob pattern support for `ignore_files`
+- Directory exclusion via `exclude_dirs`
+- Ambiguity detection and warnings
+- Code fence and HTML comment protection
+- Post-build link statistics via `show_stats`

mkdocs_easylinks_plugin-0.1.1/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/PKG-INFO

@@ -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.