# vexy-mkdocs-strip-number-prefix
[](https://pypi.org/project/vexy-mkdocs-strip-number-prefix/)
[](https://github.com/vexyart/vexy-mkdocs-strip-number-prefix/actions/workflows/ci.yml)
[](https://codecov.io/gh/vexyart/vexy-mkdocs-strip-number-prefix)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/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:
```bash
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`:
```yaml
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:
```bash
mkdocs build
```
Generated URLs will be clean:
- `/introduction/`
- `/getting-started/`
- `/configuration/`
- `/faq/`
## Configuration
All configuration options with their defaults:
```yaml
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)
```
### Pattern Examples
| Pattern | Matches | Example |
|---------|---------|---------|
| `^\\d+--` | Any digits + `--` | `123--file.md` |
| `^\\d{3}--` | Exactly 3 digits + `--` | `001--file.md` |
| `^\\d+-` | Any digits + `-` | `42-file.md` |
| `^\\d+\\.` | Any digits + `.` | `1.file.md` |
### Collision Handling
When multiple files would generate the same URL after prefix removal:
```yaml
plugins:
- strip-number-prefix:
strict: true # Fail build (recommended)
# strict: false # Log warning and continue
```
### Link Rewriting
Automatically update internal markdown links:
```yaml
plugins:
- strip-number-prefix:
strip_links: true
```
Before:
```markdown
[Setup Guide](020--setup.md)
```
After:
```markdown
[Setup Guide](setup.md)
```
## Examples
### Basic Usage
```yaml
# mkdocs.yml
site_name: My Documentation
plugins:
- strip-number-prefix
```
### With Material Theme
```yaml
# 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
```yaml
# mkdocs.yml
site_name: My Documentation
plugins:
- search
- awesome-nav
- strip-number-prefix:
pattern: '^\\d+--'
strip_links: true
```
### Custom Pattern
```yaml
# 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
- **Python**: >= 3.9
- **Works with**:
- [Material for MkDocs](https://squidfunk.github.io/vexy-mkdocs-material/)
- [vexy-mkdocs-awesome-nav](https://github.com/lukasgeiter/vexy-mkdocs-awesome-nav)
- [vexy-mkdocs-nav-weight](https://github.com/shu307/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
When `strip_links: false` (default), use clean slugs in links:
```markdown
✅ [Next page](configuration.md)
❌ [Next page](030--configuration.md)
```
When `strip_links: true`, both forms work:
```markdown
✅ [Next page](configuration.md)
✅ [Next page](030--configuration.md) # Auto-converted
```
### Debug Mode
Enable verbose logging:
```yaml
plugins:
- strip-number-prefix:
verbose: true
```
This shows:
- File transformations
- URL mappings
- Collision warnings
- Link rewriting
## Development
### Setup
```bash
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
```bash
# 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
```bash
# 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](LICENSE) file for details.
## Support
- 🐛 **Issues**: [GitHub Issues](https://github.com/vexyart/vexy-mkdocs-strip-number-prefix/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/vexyart/vexy-mkdocs-strip-number-prefix/discussions)
- 📖 **Documentation**: [Project Documentation](https://vexyart.github.io/vexy-mkdocs-strip-number-prefix/)
Raw data
{
"_id": null,
"home_page": null,
"name": "vexy-mkdocs-strip-number-prefix",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Vexy Lines Team <help@vexy.art>",
"keywords": "documentation, mkdocs, numbering, plugin, prefix, slug, url",
"author": null,
"author_email": "Vexy Lines Team <help@vexy.art>",
"download_url": "https://files.pythonhosted.org/packages/19/07/38cfe18963ad78534e01def82a66d69dab67e8525dc9706cb67d57a33d04/vexy_mkdocs_strip_number_prefix-1.0.11.tar.gz",
"platform": null,
"description": "# vexy-mkdocs-strip-number-prefix\n\n[](https://pypi.org/project/vexy-mkdocs-strip-number-prefix/)\n[](https://github.com/vexyart/vexy-mkdocs-strip-number-prefix/actions/workflows/ci.yml)\n[](https://codecov.io/gh/vexyart/vexy-mkdocs-strip-number-prefix)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/vexy-mkdocs-strip-number-prefix/)\n\nA lightweight MkDocs plugin that strips numeric prefixes from page URLs while preserving them in source filenames for natural sorting.\n\n## Features\n\n- \u2705 **Clean URLs**: Remove numeric prefixes from generated URLs\n- \u2705 **Natural Sorting**: Keep prefixes in source files for predictable ordering\n- \u2705 **Collision Detection**: Prevent duplicate URLs with configurable strictness\n- \u2705 **Link Rewriting**: Automatically update internal markdown links\n- \u2705 **Flexible Patterns**: Customize prefix matching with regex patterns\n- \u2705 **Debug Support**: Verbose logging for troubleshooting\n\n## Installation\n\nInstall from PyPI:\n\n```bash\nuv pip install --system --upgrade vexy-mkdocs-strip-number-prefix\n```\n\nor from source: \n\n```\npip install git+https://github.com/vexyart/vexy-mkdocs-strip-number-prefix\n```\n\n## Quick Start\n\nAdd the plugin to your `mkdocs.yml`:\n\n```yaml\nplugins:\n - search\n - strip-number-prefix\n```\n\nName your files with numeric prefixes:\n\n```\ndocs/\n\u251c\u2500\u2500 010--introduction.md\n\u251c\u2500\u2500 020--getting-started.md\n\u251c\u2500\u2500 030--configuration.md\n\u2514\u2500\u2500 999--faq.md\n```\n\nBuild your site:\n\n```bash\nmkdocs build\n```\n\nGenerated URLs will be clean:\n- `/introduction/`\n- `/getting-started/`\n- `/configuration/`\n- `/faq/`\n\n## Configuration\n\nAll configuration options with their defaults:\n\n```yaml\nplugins:\n - strip-number-prefix:\n pattern: '^\\\\d+--' # Regex pattern for prefix (default: '^\\\\d+--')\n verbose: false # Enable debug logging (default: false)\n strict: true # Fail on slug collisions (default: true)\n strip_links: false # Strip prefixes from markdown links (default: false)\n```\n\n### Pattern Examples\n\n| Pattern | Matches | Example |\n|---------|---------|---------|\n| `^\\\\d+--` | Any digits + `--` | `123--file.md` |\n| `^\\\\d{3}--` | Exactly 3 digits + `--` | `001--file.md` |\n| `^\\\\d+-` | Any digits + `-` | `42-file.md` |\n| `^\\\\d+\\\\.` | Any digits + `.` | `1.file.md` |\n\n### Collision Handling\n\nWhen multiple files would generate the same URL after prefix removal:\n\n```yaml\nplugins:\n - strip-number-prefix:\n strict: true # Fail build (recommended)\n # strict: false # Log warning and continue\n```\n\n### Link Rewriting\n\nAutomatically update internal markdown links:\n\n```yaml\nplugins:\n - strip-number-prefix:\n strip_links: true\n```\n\nBefore:\n```markdown\n[Setup Guide](020--setup.md)\n```\n\nAfter:\n```markdown\n[Setup Guide](setup.md)\n```\n\n## Examples\n\n### Basic Usage\n\n```yaml\n# mkdocs.yml\nsite_name: My Documentation\nplugins:\n - strip-number-prefix\n```\n\n### With Material Theme\n\n```yaml\n# mkdocs.yml\nsite_name: My Documentation\ntheme:\n name: material\n features:\n - navigation.instant\n - navigation.sections\n\nplugins:\n - search\n - strip-number-prefix:\n pattern: '^\\\\d{3}--'\n verbose: true\n```\n\n### With Awesome Nav\n\n```yaml\n# mkdocs.yml\nsite_name: My Documentation\nplugins:\n - search\n - awesome-nav\n - strip-number-prefix:\n pattern: '^\\\\d+--'\n strip_links: true\n```\n\n### Custom Pattern\n\n```yaml\n# mkdocs.yml\nplugins:\n - strip-number-prefix:\n pattern: '^\\\\d{2}\\\\.' # Matches: 01.file.md, 99.file.md\n strict: false\n```\n\n## File Organization Strategies\n\n### Sequential Numbering\n\n```\ndocs/\n\u251c\u2500\u2500 010--introduction.md\n\u251c\u2500\u2500 020--installation.md\n\u251c\u2500\u2500 030--configuration.md\n\u251c\u2500\u2500 040--advanced.md\n\u2514\u2500\u2500 999--troubleshooting.md\n```\n\n### Hierarchical Numbering\n\n```\ndocs/\n\u251c\u2500\u2500 100--getting-started.md\n\u251c\u2500\u2500 110--installation.md\n\u251c\u2500\u2500 120--first-steps.md\n\u251c\u2500\u2500 200--configuration.md\n\u251c\u2500\u2500 210--basic-config.md\n\u251c\u2500\u2500 220--advanced-config.md\n\u2514\u2500\u2500 900--appendix.md\n```\n\n### Category Prefixes\n\n```\ndocs/\n\u251c\u2500\u2500 01--intro/\n\u2502 \u251c\u2500\u2500 010--overview.md\n\u2502 \u2514\u2500\u2500 020--quickstart.md\n\u251c\u2500\u2500 02--guides/\n\u2502 \u251c\u2500\u2500 010--setup.md\n\u2502 \u2514\u2500\u2500 020--deployment.md\n\u2514\u2500\u2500 99--reference/\n \u2514\u2500\u2500 010--api.md\n```\n\n## Compatibility\n\n- **MkDocs**: >= 1.5.0\n- **Python**: >= 3.9\n- **Works with**:\n - [Material for MkDocs](https://squidfunk.github.io/vexy-mkdocs-material/)\n - [vexy-mkdocs-awesome-nav](https://github.com/lukasgeiter/vexy-mkdocs-awesome-nav)\n - [vexy-mkdocs-nav-weight](https://github.com/shu307/vexy-mkdocs-nav-weight)\n - Most other MkDocs plugins\n\n## Troubleshooting\n\n### Duplicate URLs\n\n```\nERROR: Multiple files would map to 'intro.md': 010--intro.md, 020--intro.md\n```\n\n**Solution**: Use unique base names:\n- `010--intro-basics.md`\n- `020--intro-advanced.md`\n\n### Broken Links\n\nWhen `strip_links: false` (default), use clean slugs in links:\n\n```markdown\n\u2705 [Next page](configuration.md)\n\u274c [Next page](030--configuration.md)\n```\n\nWhen `strip_links: true`, both forms work:\n\n```markdown\n\u2705 [Next page](configuration.md)\n\u2705 [Next page](030--configuration.md) # Auto-converted\n```\n\n### Debug Mode\n\nEnable verbose logging:\n\n```yaml\nplugins:\n - strip-number-prefix:\n verbose: true\n```\n\nThis shows:\n- File transformations\n- URL mappings\n- Collision warnings\n- Link rewriting\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/vexyart/vexy-mkdocs-strip-number-prefix\ncd vexy-mkdocs-strip-number-prefix\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\npip install -e .[dev]\npre-commit install\n```\n\n### Testing\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=mkdocs_strip_number_prefix --cov-report=html\n\n# Run specific test\npytest tests/test_plugin.py::TestStripNumberPrefixPlugin::test_default_pattern\n```\n\n### Code Quality\n\n```bash\n# Format and lint\nblack src tests\nruff check --fix src tests\nmypy src\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udc1b **Issues**: [GitHub Issues](https://github.com/vexyart/vexy-mkdocs-strip-number-prefix/issues)\n- \ud83d\udcac **Discussions**: [GitHub Discussions](https://github.com/vexyart/vexy-mkdocs-strip-number-prefix/discussions)\n- \ud83d\udcd6 **Documentation**: [Project Documentation](https://vexyart.github.io/vexy-mkdocs-strip-number-prefix/)",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs plugin to strip numeric prefixes from page URLs while keeping them in source files",
"version": "1.0.11",
"project_urls": {
"Changelog": "https://github.com/vexyart/vexy-mkdocs-strip-number-prefix/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/vexyart/vexy-mkdocs-strip-number-prefix",
"Homepage": "https://github.com/vexyart/vexy-mkdocs-strip-number-prefix",
"Issues": "https://github.com/vexyart/vexy-mkdocs-strip-number-prefix/issues",
"Repository": "https://github.com/vexyart/vexy-mkdocs-strip-number-prefix"
},
"split_keywords": [
"documentation",
" mkdocs",
" numbering",
" plugin",
" prefix",
" slug",
" url"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "05f286ba7a00d7525ae531751f0767c0cc52495d9b75363d78e8e5247092ed9a",
"md5": "4bf56997dc3cf8c0e602f1b7344aba6d",
"sha256": "37b08d01e2ca971f46253b8912e154c3cf7ecaf32ddd14456f2be09b1e65f3ce"
},
"downloads": -1,
"filename": "vexy_mkdocs_strip_number_prefix-1.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bf56997dc3cf8c0e602f1b7344aba6d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9190,
"upload_time": "2025-07-15T00:25:56",
"upload_time_iso_8601": "2025-07-15T00:25:56.023655Z",
"url": "https://files.pythonhosted.org/packages/05/f2/86ba7a00d7525ae531751f0767c0cc52495d9b75363d78e8e5247092ed9a/vexy_mkdocs_strip_number_prefix-1.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "190738cfe18963ad78534e01def82a66d69dab67e8525dc9706cb67d57a33d04",
"md5": "111a268c6d94cd666994f9ad34294ce4",
"sha256": "1e7544fc100ddd265a1c96914579b0cb39d79b31baf7812e569e92ae3038d0f4"
},
"downloads": -1,
"filename": "vexy_mkdocs_strip_number_prefix-1.0.11.tar.gz",
"has_sig": false,
"md5_digest": "111a268c6d94cd666994f9ad34294ce4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13913,
"upload_time": "2025-07-15T00:25:54",
"upload_time_iso_8601": "2025-07-15T00:25:54.975062Z",
"url": "https://files.pythonhosted.org/packages/19/07/38cfe18963ad78534e01def82a66d69dab67e8525dc9706cb67d57a33d04/vexy_mkdocs_strip_number_prefix-1.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 00:25:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vexyart",
"github_project": "vexy-mkdocs-strip-number-prefix",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vexy-mkdocs-strip-number-prefix"
}
JSON
