# BrokeLink
A powerful CLI tool to scan Markdown and HTML files for broken links, missing images, and invalid references.
## Features
- ✅ **Broken local links** - Find `[text](broken-link.md)` that don't exist
- ✅ **Dead image references** - Detect `` pointing to missing files
- ✅ **Outdated internal references** - Check heading anchors and fragments
- 🎨 **Colored output** - Easy-to-read results with syntax highlighting
- 📄 **Multiple formats** - Support for Markdown (`.md`) and HTML (`.html/.htm`)
- 🔧 **Flexible scanning** - Include/exclude patterns, recursive directory scanning
- 📊 **JSON output** - Machine-readable results for CI/CD integration
## Installation
### From PyPI (when published)
```bash
pip install brokelink
```
### From Source
```bash
git clone https://github.com/000xs/brokelink.git
cd brokelink
pip install -e .
```
### verify installation
```
brokelink
```
## Quick Start
```bash
# Scan current directory
brokelink
# Scan specific directory
brokelink ./docs
# Scan with verbose output
brokelink -v
# Check only Markdown files
brokelink --include="*.md"
# Output as JSON
brokelink --format=json
# Include anchor checking (experimental)
brokelink --check-anchors
```
## Usage
```
Usage: brokelink [OPTIONS] [PATH]
🔗 BrokeLink - Scan for broken links in Markdown and HTML files.
Options:
-i, --include TEXT File patterns to include (default: *.md *.html)
-e, --exclude TEXT File patterns to exclude
-img, --check-images Check image references (default: enabled)
-a, --check-anchors Check heading anchors (experimental)
-v, --verbose Verbose output
-q, --quiet Only show errors
-f, --format [text|json] Output format
--help Show this message and exit.
```
## Examples
### Basic Usage
```bash
# Scan all .md and .html files in current directory
brokelink
# Scan specific file
brokelink README.md
# Scan docs folder recursively
brokelink ./docs
```
### Advanced Filtering
```bash
# Only check Markdown files
brokelink --include="*.md"
# Exclude certain directories
brokelink --exclude="node_modules/*" --exclude="build/*"
# Skip image checking
brokelink --no-check-images
```
### CI/CD Integration
```bash
# JSON output for parsing
brokelink --format=json --quiet > broken-links.json
# Exit code 1 if broken links found (perfect for CI)
brokelink || echo "Broken links detected!"
```
## Output Example
```
🔗 BrokeLink v1.0.0 - Scanning for broken links...
💥 Found 3 broken link(s) in 2 file(s):
📄 docs/README.md:
🔗 Missing files (2):
Line 15: ./nonexistent.md ('Documentation Link')
Line 23: ../missing-guide.md ('Setup Guide')
🖼️ Missing images (1):
Line 8: ./images/logo.png ('BrokeLink Logo')
📄 index.html:
⚓ Invalid anchors (1):
Line 42: #missing-section ('Jump to Section')
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/000xs/brokelink.git
cd brokelink
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .
```
### Running Tests
```bash
python -m pytest tests/
```
### Project Structure
```
brokelink/
├── brokelink/ # Main package
│ ├── __init__.py
│ ├── cli.py # CLI interface
│ ├── parser.py # Link extraction
│ └── utils.py # Link checking & reporting
├── demo/ # Sample files for testing
├── tests/ # Test suite
├── README.md
├── LICENSE
└── pyproject.toml # Modern Python packaging
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Roadmap
- [ ] External URL checking (with timeout/retry)
- [ ] Whitelist/blacklist for URLs
- [ ] Integration with popular static site generators
- [ ] Performance optimizations for large repositories
- [ ] GitHub Actions integration
- [ ] VS Code extension
---
Made with ❤️ for documentation maintainers everywhere!"# brokelink"
Raw data
{
"_id": null,
"home_page": "https://github.com/000xs/brokelink",
"name": "brokelink",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Sithum Sathsara Rajapakshe | 000x",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5d/1f/cb5cdf50c10b35240dd20c80b7f11658de394591635c80bf8da432122938/brokelink-0.1.0.tar.gz",
"platform": null,
"description": "\n\n# BrokeLink\n\nA powerful CLI tool to scan Markdown and HTML files for broken links, missing images, and invalid references.\n\n## Features\n\n- \u2705 **Broken local links** - Find `[text](broken-link.md)` that don't exist\n- \u2705 **Dead image references** - Detect `` pointing to missing files \n- \u2705 **Outdated internal references** - Check heading anchors and fragments\n- \ud83c\udfa8 **Colored output** - Easy-to-read results with syntax highlighting\n- \ud83d\udcc4 **Multiple formats** - Support for Markdown (`.md`) and HTML (`.html/.htm`)\n- \ud83d\udd27 **Flexible scanning** - Include/exclude patterns, recursive directory scanning\n- \ud83d\udcca **JSON output** - Machine-readable results for CI/CD integration\n\n## Installation\n\n### From PyPI (when published)\n```bash\npip install brokelink\n```\n\n### From Source\n```bash\ngit clone https://github.com/000xs/brokelink.git\ncd brokelink\npip install -e .\n\n```\n### verify installation\n```\nbrokelink\n```\n\n## Quick Start\n\n```bash\n# Scan current directory\nbrokelink\n\n# Scan specific directory\nbrokelink ./docs\n\n# Scan with verbose output\nbrokelink -v\n\n# Check only Markdown files\nbrokelink --include=\"*.md\"\n\n# Output as JSON\nbrokelink --format=json\n\n# Include anchor checking (experimental)\nbrokelink --check-anchors\n```\n\n## Usage\n\n```\nUsage: brokelink [OPTIONS] [PATH]\n\n \ud83d\udd17 BrokeLink - Scan for broken links in Markdown and HTML files.\n\nOptions:\n -i, --include TEXT File patterns to include (default: *.md *.html)\n -e, --exclude TEXT File patterns to exclude\n -img, --check-images Check image references (default: enabled)\n -a, --check-anchors Check heading anchors (experimental)\n -v, --verbose Verbose output\n -q, --quiet Only show errors\n -f, --format [text|json] Output format\n --help Show this message and exit.\n```\n\n## Examples\n\n### Basic Usage\n```bash\n# Scan all .md and .html files in current directory\nbrokelink\n\n# Scan specific file\nbrokelink README.md\n\n# Scan docs folder recursively \nbrokelink ./docs\n```\n\n### Advanced Filtering\n```bash\n# Only check Markdown files\nbrokelink --include=\"*.md\"\n\n# Exclude certain directories\nbrokelink --exclude=\"node_modules/*\" --exclude=\"build/*\"\n\n# Skip image checking\nbrokelink --no-check-images\n```\n\n### CI/CD Integration\n```bash\n# JSON output for parsing\nbrokelink --format=json --quiet > broken-links.json\n\n# Exit code 1 if broken links found (perfect for CI)\nbrokelink || echo \"Broken links detected!\"\n```\n\n## Output Example\n\n```\n\ud83d\udd17 BrokeLink v1.0.0 - Scanning for broken links...\n\n\ud83d\udca5 Found 3 broken link(s) in 2 file(s):\n\n\ud83d\udcc4 docs/README.md:\n \ud83d\udd17 Missing files (2):\n Line 15: ./nonexistent.md ('Documentation Link')\n Line 23: ../missing-guide.md ('Setup Guide')\n \ud83d\uddbc\ufe0f Missing images (1):\n Line 8: ./images/logo.png ('BrokeLink Logo')\n\n\ud83d\udcc4 index.html:\n \u2693 Invalid anchors (1):\n Line 42: #missing-section ('Jump to Section')\n```\n\n## Development\n\n### Setup Development Environment\n```bash\ngit clone https://github.com/000xs/brokelink.git\ncd brokelink\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\npip install -e .\n```\n\n### Running Tests\n```bash\npython -m pytest tests/\n```\n\n### Project Structure\n```\nbrokelink/\n\u251c\u2500\u2500 brokelink/ # Main package\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 cli.py # CLI interface\n\u2502 \u251c\u2500\u2500 parser.py # Link extraction\n\u2502 \u2514\u2500\u2500 utils.py # Link checking & reporting\n\u251c\u2500\u2500 demo/ # Sample files for testing\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 LICENSE\n\u2514\u2500\u2500 pyproject.toml # Modern Python packaging\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Roadmap\n\n- [ ] External URL checking (with timeout/retry)\n- [ ] Whitelist/blacklist for URLs\n- [ ] Integration with popular static site generators\n- [ ] Performance optimizations for large repositories\n- [ ] GitHub Actions integration\n- [ ] VS Code extension\n\n---\n\nMade with \u2764\ufe0f for documentation maintainers everywhere!\"# brokelink\" \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Dead link scanner for .md and .html docs",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/000xs/brokelink"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3b5589fedc3660771fafd41de6248b49c4b3a587a9a79c60e1ecc6c4a67191e2",
"md5": "df2baf8d44f9d25a5dc01bdacf93c704",
"sha256": "87440e0e8ea605312a1f3a78710fc5c24eb4c528bf320661a99cfbc6f9fe4c57"
},
"downloads": -1,
"filename": "brokelink-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df2baf8d44f9d25a5dc01bdacf93c704",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9333,
"upload_time": "2025-07-16T13:54:23",
"upload_time_iso_8601": "2025-07-16T13:54:23.422882Z",
"url": "https://files.pythonhosted.org/packages/3b/55/89fedc3660771fafd41de6248b49c4b3a587a9a79c60e1ecc6c4a67191e2/brokelink-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5d1fcb5cdf50c10b35240dd20c80b7f11658de394591635c80bf8da432122938",
"md5": "690a72d437a418c211b443a306383ad3",
"sha256": "e7a14958b88299fabae39e8e1c16cb20776f7f8f8af1952e39bb1d7f033501a3"
},
"downloads": -1,
"filename": "brokelink-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "690a72d437a418c211b443a306383ad3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8976,
"upload_time": "2025-07-16T13:54:24",
"upload_time_iso_8601": "2025-07-16T13:54:24.313892Z",
"url": "https://files.pythonhosted.org/packages/5d/1f/cb5cdf50c10b35240dd20c80b7f11658de394591635c80bf8da432122938/brokelink-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 13:54:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "000xs",
"github_project": "brokelink",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "colorama",
"specs": [
[
">=",
"0.4.0"
]
]
},
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.9.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"2.10.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"21.0.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"0.800"
]
]
}
],
"lcname": "brokelink"
}
JSON
