{"id":15043997,"url":"https://github.com/merlos/broken-links","last_synced_at":"2026-02-04T12:04:54.405Z","repository":{"id":252192431,"uuid":"839698151","full_name":"merlos/broken-links","owner":"merlos","description":"Are the links of a page broken? A command line and github action to check it out","archived":false,"fork":false,"pushed_at":"2024-08-12T07:06:51.000Z","size":95,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-04T04:23:19.018Z","etag":null,"topics":["docker-image","github-actions","github-pages","links-checker","pypi-package","python","url-checker"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/merlos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-08T06:37:13.000Z","updated_at":"2025-03-28T02:44:53.000Z","dependencies_parsed_at":"2024-09-21T14:02:47.484Z","dependency_job_id":"667a4d6b-f0cf-474c-99a6-d667c6378004","html_url":"https://github.com/merlos/broken-links","commit_stats":null,"previous_names":["merlos/link-checker-action","merlos/broken-links"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/merlos/broken-links","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merlos%2Fbroken-links","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merlos%2Fbroken-links/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merlos%2Fbroken-links/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merlos%2Fbroken-links/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/merlos","download_url":"https://codeload.github.com/merlos/broken-links/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merlos%2Fbroken-links/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29084088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-image","github-actions","github-pages","links-checker","pypi-package","python","url-checker"],"created_at":"2024-09-24T20:49:56.177Z","updated_at":"2026-02-04T12:04:54.390Z","avatar_url":"https://github.com/merlos.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Broken Links Checker\n\nThis tool scrapes all pages within a specified URL and checks if the destination links exist. It reports the original page, the text of the anchor, the destination URL, and whether the link is working or not. If any of the links does not work, the tool exits with an error code. It also provides a summary of the analysis.\n\nIt can be run as a **GitHub Action**, as a **command line tool** and as a **Docker Container**.\n\n\n* [GitHub Action Use](#github-action-use)\n* [Command-Line Tool Use](#command-line-tool-use) (pypi)\n* [Docker Image Use](#docker-image-use)\n\n## GitHub Action Use\n\nThis tool can also be used as a GitHub Action to automatically check links in your repository.\n\n### Inputs\n- `url` (optional): The base URL to start scraping from. Default is `http://localhost:4444/`.\n- `only-errors` (optional): If set to true, only display errors. Default is `false`.\n- `ignore-file` (optional): Path to the ignore file. Default is `./check-ignore`. If the parameter is set and the file does not exist, the action exits with an error. See _Ignore File Format_ section above for more information.\n\n### Ignore File Format\n\nThe ignore file should contain one URL pattern per line. The patterns can include wildcards (*) to match multiple URLs. Here are some examples:\n\n- `http://example.com/ignore-this-page` - Ignores this specific URL.\n- `http://example.com/ignore/*` - Ignores all URLs that start with `http://example.com/ignore/`.\n- `*/ignore-this-path/*` - Ignores all URLs that contain `/ignore-this-path/`.\n- `https://*.domain.com*` - Ignores all subdomains of `domain.com` such as `https://sub.domain.com` or `https://sub2.domain.com/page`, etc.\n\n\n### Outputs\n\nThis action does not produce any outputs. However, at the end of the analysis, it prints a summary of the results with:\n\n- Number of pages analyzed\n- Number of links analyzed\n- Total number of links working\n- Total number of links not working\n- Number of external links working\n- Number of external links not working\n- Number of internal links working\n- Number of internal links not working\n\n### Examples of Usage\n\n#### Basic Usage (external URL)\n\n```yaml\nname: Broken-links Checker\n\non: [push]\n\njobs:\n  check-links:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v2\n\n      - name: Run Link Checker\n        uses: merlos/broken-links@0.2.2\n        with:\n          url: 'http://example.com'\n          only-errors: 'true'\n```\n\n#### Check links with MkDocs\n\n```yaml\nname: MkDocs Preview and Link Check\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  preview_and_check:\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v2\n\n      - name: Set up Python\n        uses: actions/setup-python@v2\n        with:\n          python-version: '3.x'\n\n      - name: Install dependencies\n        run: |\n          python -m pip install --upgrade pip\n          pip install mkdocs mkdocs-material\n\n      - name: Run MkDocs server\n        run: mkdocs serve -a 0.0.0.0:4444 \u0026\n        continue-on-error: true\n\n      - name: Wait for server to start\n        run: sleep 10\n\n      - name: Run Link Checker\n        uses: merlos/broken-links@0.2.2\n        with:\n          url: 'http://localhost:4444'\n          only-errors: 'true'\n          ignore-file: './check-ignore'\n```\n\n#### Check links with Quarto\n\n```yaml\nname: Quarto Preview and Link Check\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  preview_and_check:\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v2\n\n      - name: Set up Quarto\n        uses: quarto-dev/quarto-actions/setup@v2\n\n      - name: Render Quarto project\n        run: quarto preview --port 444 \u0026\n        continue-on-error: true\n\n      - name: Wait for server to start\n        run: sleep 10\n\n      - name: Run Link Checker\n        uses: merlos/broken-links@0.2.2\n        with:\n          url: 'http://localhost:444'\n          only-errors: 'true'\n          ignore-file: './check-ignore'\n```\n\n\n## Command-Line Tool Use\n\n#### Installation\n\n1. Install the package:\n    ```sh\n    pip install broken-links\n    ```\n    \n3. Use the `broken-links` command:\n\n  ```sh\n  broken-links http://example.com --only-error --ignore-file ./check-ignore\n  ```\n\nCommand-line arguments:\n\n- `url` (optional): The base URL to start scraping from. Default is `http://localhost:4444/`.\n- `--only-error` or `-o` (optional): If set, only display errors. Default is `false`.\n- `--ignore-file` or `-i` (optional): Path to the ignore file. Default is `./check-ignore`. If the parameter is NOT set and the file does not exist, it checks all the links. If the parameter is set and the file does not exist, the tool exits with an error. \n\nThe format of the ignore file is explained in the [Ignore File Format (#ignore-file-format) section above.\n\n## Docker Image Use\n\nThe docker image has been built for these architectures: `arm64`, `amd64`, and `arm7` and has been released in [docker-hub](https://hub.docker.com/repository/docker/merlos/broken-links/general) and [GitHub Container Registy](https://github.com/merlos/broken-links/pkgs/container/broken-links)\n\n\n1. Get the image\n```sh\ndocker pull merlos/broken-links:latest\n# or from GitHub Container Registry\ndocker pull ghcr.io/merlos/broken-links:latest\n```\n\n2. Run the container\n```sh\ndocker run -ti merlos/broken-links https://www.example.com\n```\nThe arguments are the same as the command line (`url`, `--only-error`, `--ignore-file`) as explained above. The `-ti` option used with `docker` run displays the output of the command as it is generated.  \n\nIn order to use the `--ignore-file` argument you need to mount a volume. For example:\n\n```sh\ndocker run -ti -v /path/on/host/to/ignore-file:/ignore-file merlos/broken-links https://www.example.com --ignore-file /ignore-file\n```\n\n## Development\n\nIt has been developed using python. So you need to have python installed in your system.\n\nClone the repository:\n```sh\ngit clone https://github.com/merlos/broken-links\ncd broken-links\n```\n\nSet a virtual environment:\n```sh\npython -m venv venv\nsource venv/bin/activate\n```\nInstall the package in edit mode (`-e`)\n```sh\npip install -e .\n```\nStart coding!\n\n### Build the docker image\n\n```sh\ndocker build -t broken-links .\n```\n```sh\ndocker run --rm broken-links http://example.com --only-error \n```\n\n### Tests\nTo run the tests, use the following command:\n\n```sh\npython -m unittest discover tests\n```\n## Contributing\nFork and send a pull request. Please update/add the unit tests.\n\n## License\nThis project is licensed under the terms of the [GNU General Public License v3.0](LICENSE) by merlos.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerlos%2Fbroken-links","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmerlos%2Fbroken-links","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerlos%2Fbroken-links/lists"}