vexy-mkdocs-strip-number-prefix

Documentation: https://vexy.dev/vexy-mkdocs-strip-number-prefix/

A lightweight MkDocs plugin that strips numeric prefixes from page URLs while preserving them in source filenames for natural sorting.

Features

• ✅ Clean URLs: Remove numeric prefixes from generated URLs
• ✅ Natural Sorting: Keep prefixes in source files for predictable ordering
• ✅ Collision Detection: Prevent duplicate URLs with configurable strictness
• ✅ Link Rewriting: Automatically update internal markdown links
• ✅ Flexible Patterns: Customize prefix matching with regex patterns
• ✅ Debug Support: Verbose logging for troubleshooting

Installation

Install from PyPI:

uv pip install --system --upgrade vexy-mkdocs-strip-number-prefix

or from source:

pip install git+https://github.com/vexyart/vexy-mkdocs-strip-number-prefix

Quick Start

Add the plugin to your mkdocs.yml:

plugins:
  - search
  - strip-number-prefix

Name your files with numeric prefixes:

docs/
├── 010--introduction.md
├── 020--getting-started.md
├── 030--configuration.md
└── 999--faq.md

Build your site:

mkdocs build

Generated URLs will be clean:

• /introduction/
• /getting-started/
• /configuration/
• /faq/

Configuration

All configuration options with their defaults:

plugins:
  - strip-number-prefix:
      pattern: '^\d+--'     # Regex pattern for prefix (default: '^\d+--')
      verbose: false         # Enable debug logging (default: false)
      strict: true           # Fail on slug collisions (default: true)
      strip_links: false     # Strip prefixes from markdown links (default: false)
      strip_nav_titles: true # Strip prefixes from navigation titles (default: true)
      dry_run: false         # Log changes without applying them (default: false)

Pattern Examples

Collision Handling

When multiple files would generate the same URL after prefix removal:

plugins:
  - strip-number-prefix:
      strict: true   # Fail build (recommended)
      # strict: false  # Log warning and continue

Link Rewriting

Automatically update internal markdown links:

plugins:
  - strip-number-prefix:
      strip_links: true

Before:

[Setup Guide](020--setup.md)

After:

[Setup Guide](setup.md)

Caution: MkDocs resolves links against the prefixed source filenames, so rewritten links are reported as "not found" and stay unresolved. In most projects, leave strip_links: false and link to 020--setup.md; MkDocs then writes the clean URL for you.

Examples

Basic Usage

# mkdocs.yml
site_name: My Documentation
plugins:
  - strip-number-prefix

With Material Theme

# mkdocs.yml
site_name: My Documentation
theme:
  name: material
  features:
    - navigation.instant
    - navigation.sections

plugins:
  - search
  - strip-number-prefix:
      pattern: '^\d{3}--'
      verbose: true

With Awesome Nav

# mkdocs.yml
site_name: My Documentation
plugins:
  - search
  - awesome-nav
  - strip-number-prefix:
      pattern: '^\d+--'
      strip_links: true

Custom Pattern

# mkdocs.yml
plugins:
  - strip-number-prefix:
      pattern: '^\d{2}_'  # Matches: 01_file.md, 99_file.md
      strict: false

File Organization Strategies

Sequential Numbering

docs/
├── 010--introduction.md
├── 020--installation.md
├── 030--configuration.md
├── 040--advanced.md
└── 999--troubleshooting.md

Hierarchical Numbering

docs/
├── 100--getting-started.md
├── 110--installation.md
├── 120--first-steps.md
├── 200--configuration.md
├── 210--basic-config.md
├── 220--advanced-config.md
└── 900--appendix.md

Category Prefixes

docs/
├── 01--intro/
│   ├── 010--overview.md
│   └── 020--quickstart.md
├── 02--guides/
│   ├── 010--setup.md
│   └── 020--deployment.md
└── 99--reference/
    └── 010--api.md

Compatibility

• MkDocs: >= 1.5.0 (tested against 1.5.x and 1.6.x)
• Python: >= 3.9 (tested on 3.9, 3.10, 3.11, 3.12, 3.13)
• Works with:
  • Material for MkDocs
  • vexy-mkdocs-awesome-nav
  • vexy-mkdocs-nav-weight
  • Most other MkDocs plugins

Troubleshooting

Duplicate URLs

ERROR: Multiple files would map to 'intro.md': 010--intro.md, 020--intro.md

Solution: Use unique base names:

• 010--intro-basics.md
• 020--intro-advanced.md

Broken Links

Link to the prefixed source filename. MkDocs resolves it to the clean URL:

✅ [Next page](030--configuration.md)
❌ [Next page](configuration.md)   # no source file has this name

Keep strip_links: false (the default). With strip_links: true the link is rewritten to the clean filename before MkDocs resolves it, and MkDocs reports "the target is not found among documentation files". See Links and navigation.

Debug Mode

Enable verbose logging:

plugins:
  - strip-number-prefix:
      verbose: true

This shows:

• File transformations
• URL mappings
• Collision warnings
• Link rewriting

Development

Setup

git clone https://github.com/vexyart/vexy-mkdocs-strip-number-prefix
cd vexy-mkdocs-strip-number-prefix
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .[dev]
pre-commit install

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=mkdocs_strip_number_prefix --cov-report=html

# Run specific test
pytest tests/test_plugin.py::TestStripNumberPrefixPlugin::test_default_pattern

Code Quality

# Format and lint
black src tests
ruff check --fix src tests
mypy src

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Project Documentation