{"id":13622556,"url":"https://github.com/UmbrellaDocs/linkspector","last_synced_at":"2025-04-15T09:32:55.403Z","repository":{"id":194553067,"uuid":"681883401","full_name":"UmbrellaDocs/linkspector","owner":"UmbrellaDocs","description":"Uncover broken links in your content.","archived":false,"fork":false,"pushed_at":"2025-04-15T00:13:47.000Z","size":406,"stargazers_count":83,"open_issues_count":22,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-15T00:31:53.300Z","etag":null,"topics":["hacktoberfest","link-check","link-checker","markdown-link-check","markdown-links"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UmbrellaDocs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"liberapay":"gaurav-nelson"}},"created_at":"2023-08-23T01:11:20.000Z","updated_at":"2025-04-15T00:13:51.000Z","dependencies_parsed_at":"2024-05-30T13:36:18.046Z","dependency_job_id":"df871dc4-e5c6-4cd2-b1d9-5f318c7153c0","html_url":"https://github.com/UmbrellaDocs/linkspector","commit_stats":null,"previous_names":["umbrelladocs/linkspector"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmbrellaDocs%2Flinkspector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmbrellaDocs%2Flinkspector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmbrellaDocs%2Flinkspector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UmbrellaDocs%2Flinkspector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UmbrellaDocs","download_url":"https://codeload.github.com/UmbrellaDocs/linkspector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248986271,"owners_count":21194022,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["hacktoberfest","link-check","link-checker","markdown-link-check","markdown-links"],"created_at":"2024-08-01T21:01:21.054Z","updated_at":"2025-04-15T09:32:55.374Z","avatar_url":"https://github.com/UmbrellaDocs.png","language":"JavaScript","funding_links":["https://liberapay.com/gaurav-nelson","https://liberapay.com/gaurav-nelson/donate"],"categories":["JavaScript","Quality Assurance"],"sub_categories":[],"readme":"[![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-action%20linkspector-brightgreen?style=for-the-badge)](https://github.com/marketplace/actions/run-linkspector-with-reviewdog)\n[![NPM](https://img.shields.io/npm/v/@umbrelladocs/linkspector?style=for-the-badge)](https://www.npmjs.com/package/@umbrelladocs/linkspector)\n\u003ca href=\"https://liberapay.com/gaurav-nelson/donate\"\u003e\u003cimg alt=\"Donate using Liberapay\" src=\"https://liberapay.com/assets/widgets/donate.svg\"\u003e\u003c/a\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/UmbrellaDocs/linkspector\"\u003e\u003cimg src=\"https://i.ibb.co/VD70DX3/linkspectorelogonewtransparentupscale.png\" alt=\"Logo\" height=170\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003eUncover broken links in your content.\u003c/h3\u003e\n\u003ch1 align=\"center\"\u003eLinkspector\u003c/h1\u003e\n\nLinkspector is a CLI app that checks for dead hyperlinks in files.\nIt supports multiple markup languages such as Markdown, AsciiDoc (limited - hyperlinks only), and ReStructured Text (coming soon).\n\nWith Linkspector, you can easily check all hyperlinks in your files, ensuring that they are not broken and that your readers can access all the relevant content.\nThe app allows you to quickly and easily identify any broken links, so you can fix them before publishing your content.\n\nLinkspector is a powerful tool for anyone who creates content using markup languages.\n\n## How this is different from existing tools?\n\n1. **Enhanced Link Checking with Puppeteer**: It uses [Puppeteer](https://pptr.dev/) to check links in Chrome's headless mode, reducing the number of false positives.\n2. **Addresses limitations and adds user-requested features**: It is built to adress the shortcomings in [GitHub Action - Markdown link check](https://github.com/gaurav-nelson/github-action-markdown-link-check) and adds many user requested features.\n3. **Single repository for seamless collaboration**: All the code it needs to run is in a single repository, making it easier for community to collaborate.\n4. **Focused for CI/CD use**: Linkspector ([action-linkspector](https://github.com/UmbrellaDocs/action-linkspector)) is purposefully tailored to run into your CI/CD pipelines. This ensures that link checking becomes an integral part of your development workflow.\n\n## Installation\n\nBefore you can use Linkspector, you need to install it. You can do this using the following command:\n\n```bash\nnpm install -g @umbrelladocs/linkspector\n```\n\nThis command installs Linkspector globally, allowing you to use it from anywhere in your terminal. If you don't want to install using `npm` you can download the binary from GitHub releases.\n\n### GitHub action\n\nFor more details, see [action-linkspector](https://github.com/UmbrellaDocs/action-linkspector)\n\n## Checking Hyperlinks\n\nTo check hyperlinks in your markup language files, follow these steps:\n\n1. Open your terminal.\n\n1. Navigate to the directory containing the files you want to check.\n\n1. (**Optional**) Create a [configuration](#configuration) file called `.linkspector.yml`. By default, Linkspector looks for a configuration file named `.linkspector.yml` in the current directory. If you have a custom configuration file or want to specify its path, you can use the `-c` or `--config` option.\n\n1. Use the `linkspector check` command to initiate the hyperlink check. For example:\n\n   ```bash\n   linkspector check\n   ```\n\n   - To specify a custom configuration file path:\n\n     ```bash\n     linkspector check -c /path/to/custom-config.yml\n     ```\n\n   - To output the results in JSON format:\n\n     ```bash\n     linkspector check -j\n     ```\n\n     The JSON output follows [rdjson](https://github.com/reviewdog/reviewdog/tree/master/proto/rdf#rdjson) format.\n\n1. Linkspector starts checking the hyperlinks in your files based on the configuration provided in the configuration file or using the default configuration. It then displays the results in your terminal.\n\n1. After the check is complete, Linkspector provides a summary of the results. If any dead links are found, they are listed in the terminal, along with their status codes and error messages.\n\n   - To display statistics about the checked links, use the `-s` or `--showstat` option:\n\n     ```bash\n     linkspector check -s\n     ```\n\n     This command shows a summary table with the number of files checked, total links, hyperlinks, file and header links, and the count of correct and failed links.\n     Note that this option cannot be used together with the JSON output option (`-j`).\n\n1. If no dead links are found, Linkspector displays a success message, indicating that all links are working.\n\n## Configuration\n\nLinkspector uses a configuration file named `.linkspector.yml` to customize its behavior. If this file is not found in the current directory when the program is run, Linkspector displays a message saying \"Configuration file not found. Using default configuration.\" and uses a default configuration.\n\n### Default Configuration\n\nThe default configuration is as follows:\n\n```yaml\ndirs:\n  - .\nuseGitIgnore: true\n```\n\nIf you are defining a custom configuration, you must include the `dirs` or `files` section in the configuration file.\n\nFollowing are the available configuration options:\n\n| Option                                            | Description                                                                                           | Required                          |\n| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------- |\n| [`files`](#files-to-check)                        | The list of Markdown files to check for broken links.                                                 | Yes, if `dirs` is not specified.  |\n| [`dirs`](#directories-to-search)                  | The list of directories to search for Markdown files.                                                 | Yes, if `files` is not specified. |\n| [`excludedFiles`](#excluded-files)                | The list of Markdown files to exclude from the link checking process.                                 | No                                |\n| [`excludedDirs`](#excluded-directories)           | The list of directories to exclude from the link checking process.                                    | No                                |\n| [`baseUrl`](#base-url)                            | The base URL to use when checking relative links in Markdown files.                                   | No                                |\n| [`ignorePatterns`](#ignore-patterns)              | The list of regular expressions that match URLs to be ignored during link checking.                   | No                                |\n| [`replacementPatterns`](#replacement-patterns)    | The list of regular expressions and replacement strings to modify URLs during link checking.          | No                                |\n| [`aliveStatusCodes`](#alive-status-codes)         | The list of HTTP status codes that are considered as \"alive\" links.                                   | No                                |\n| [`useGitIgnore`](#use-gitignore)                  | Indicates whether to use the rules defined in the `.gitignore` file to exclude files and directories. | No                                |\n| [`modifiedFilesOnly`](#check-modified-files-only) | Indicates whether to check only the files that have been modified in the last git commit.             | No                                |\n| [`httpHeaders`](#http-headers)                    | The list of URLs and their corresponding HTTP headers to be used during link checking.                | No                                |\n\n### Files to Check\n\nThe `files` section specifies the Markdown files that Linkspector should check for broken links. You can add the file paths you want to include in this list. For example:\n\n```yaml\nfiles:\n  - README.md\n  - file2.md\n  - file3.md\n```\n\n### Directories to Search\n\nThe `dirs` section lists the directories where Linkspector should search for Markdown files. You can specify directories relative to the current working directory. For example:\n\n```yaml\ndirs:\n  - ./\n  - folder2\n```\n\n### Excluded Files\n\nThe `excludedFiles` section allows you to specify Markdown files that should be excluded from the link checking process. Add the paths of the files you want to exclude. For example:\n\n```yaml\nexcludedFiles:\n  - ./check.md\n  - excluded-file2.md\n```\n\n### Excluded Directories\n\nThe `excludedDirs` section lets you specify directories that should be excluded from the link checking process. Provide the paths of the directories you want to exclude. For example:\n\n```yaml\nexcludedDirs:\n  - ./lib\n  - excluded-folder2\n```\n\n### Base URL\n\nThe `baseUrl` option sets the base URL that will be used when checking relative links in Markdown files. In this example:\n\n```yaml\nbaseUrl: https://example.com\n```\n\nThe base URL is set to `https://example.com`.\n\n### Ignore Patterns\n\nThe `ignorePatterns` section allows you to define regular expressions that match URLs to be ignored during the link checking process. For example:\n\n```yaml\nignorePatterns:\n  - pattern: '^https://example.com/skip/.*$'\n  - pattern: \"^(ftp)://[^\\\\s/$?#]*\\\\.[^\\\\s]*$\"\n```\n\nIn this example, URLs matching the specified patterns will be skipped during link checking.\n\n### Replacement Patterns\n\nThe `replacementPatterns` section lets you define regular expressions and replacement strings to modify URLs during link checking. For example:\n\n```yaml\nreplacementPatterns:\n  - pattern: \"(https?://example.com)/(\\\\w+)/(\\\\d+)\"\n    replacement: '$1/id/$3'\n  - pattern: \"\\\\[([^\\\\]]+)\\\\]\\\\((https?://example.com)/file\\\\)\"\n    replacement: '\u003ca href=\"$2/file\"\u003e$1\u003c/a\u003e'\n```\n\nThese patterns and replacements will be applied to URLs found in the Markdown files.\n\n### Alive Status Codes\n\nThe `aliveStatusCodes` section allows you to specify a list of HTTP status codes that are considered as \"alive\" links. In this example:\n\n```yaml\naliveStatusCodes:\n  - 200\n  - 201\n  - 204\n```\n\nLinks returning any of these status codes will be considered valid.\n\n### Use .gitignore\n\nThe `useGitIgnore` option, when set to `true`, indicates that Linkspector should use the rules defined in the `.gitignore` file to exclude files and directories. For example:\n\n```yaml\nuseGitIgnore: true\n```\n\nWhen enabled, the app will respect the `.gitignore` rules during link checking.\n\n### Check Modified Files Only\n\nThe `modifiedFilesOnly` option, when set to `true`, indicates that Linkspector should only check the files that have been modified in the last git commit. For example:\n\n```yaml\nmodifiedFilesOnly: true\n```\n\nWhen enabled, Linkspector will use `git` to find the list of modified files and only check those files. Please note that this option requires `git` to be installed and available on your system path. If `git` is not installed or not found in the system path, Linkspector will throw an error.\n\nAlso, if no modified files are found in the list of files to check, Linkspector will skip link checking and exit with a message indicating that no modified files have been edited so it will skip checking.\n\n### HTTP headers\n\nThe `httpHeaders` option allows you to specify HTTP headers for specific URLs that require authorization. You can use environment variables for secure values.\n\n1. Create a `.env` file in the root directory of your project and add the environment variables. For example:\n\n   ```env\n   AUTH_TOKEN=abcdef123456\n   ```\n\n1. Add the `httpHeaders` section to the configuration file and specify the URLs and headers. For example:\n\n   ```yaml\n   httpHeaders:\n     - url:\n         - https://example1.com\n       headers:\n         Foo: Bar\n     - url:\n         - https://example2.com\n       headers:\n         Authorization: ${AUTH_TOKEN}\n         Foo: Bar\n   ```\n\n### Sample configuration\n\n```yml\nfiles:\n  - README.md\n  - file2.md\n  - file3.md\ndirs:\n  - ./\n  - folder2\nexcludedFiles:\n  - ./check.md\n  - excluded-file2.md\nexcludedDirs:\n  - ./lib\n  - excluded-folder2\nbaseUrl: https://example.com\nignorePatterns:\n  - pattern: '^https://example.com/skip/.*$'\n  - pattern: \"^(ftp)://[^\\\\s/$?#]*\\\\.[^\\\\s]*$\"\nreplacementPatterns:\n  - pattern: \"(https?://example.com)/(\\\\w+)/(\\\\d+)\"\n    replacement: '$1/id/$3'\n  - pattern: \"\\\\[([^\\\\]]+)\\\\]\\\\((https?://example.com)/file\\\\)\"\n    replacement: '\u003ca href=\"$2/file\"\u003e$1\u003c/a\u003e'\nhttpHeaders:\n  - url:\n      - https://example1.com\n    headers:\n      Authorization: Basic Zm9vOmJhcg==\n      Foo: Bar\naliveStatusCodes:\n  - 200\n  - 201\n  - 204\nuseGitIgnore: true\n```\n\n## Sample output\n\nIf there are failed links, linkspector shows the output as comma-seprated values and exit with error.\n`File, HTTP status code, Line number, Error message`\n\n```\nREDISTRIBUTED.md, https://unlicense.org/, null, 186, net::ERR_SSL_VERSION_OR_CIPHER_MISMATCH at https://unlicense.org/]\n💥 Error: Some hyperlinks in the specified files are invalid.\n```\n\nIf there are no errors, linkspector shows the following message:\n\n```\n✨ Success: All hyperlinks in the specified files are valid.\n```\n\n## Using Linkspector with Docker\n\nTo use Linkspector with Docker, follow these steps:\n\n1. Clone the Linkspector repository to your local machine and switch to the cloned directory:\n   ```bash\n   git clone git@github.com:UmbrellaDocs/linkspector.git\n   cd linkspector\n   ```\n1. Build the docker image locally, while being at the root (`.`) of this project:\n\n   ```bash\n   docker build --no-cache --pull --build-arg LINKSPECTOR_PACKAGE= -t umbrelladocs/linkspector .\n   ```\n\n1. To perform a check using the default configuration, while being at the root (`$PWD`) of the project to be checked:\n\n   ```bash\n   docker run --rm -it -v $PWD:/app \\\n          --name linkspector umbrelladocs/linkspector \\\n          bash -c 'linkspector check'\n   ```\n\n   To specify a custom configuration file path:\n\n   ```bash\n   docker run --rm -it -v $PWD:/app -v $PWD/custom-config.yml:/path/to/custom-config.yml \\\n          --name linkspector umbrelladocs/linkspector \\\n          bash -c 'linkspector check -c /path/to/custom-config.yml'\n   ```\n\n## Contributing\n\nIf you would like to contribute to Linkspector, please read the [contributing guidelines](/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUmbrellaDocs%2Flinkspector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FUmbrellaDocs%2Flinkspector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUmbrellaDocs%2Flinkspector/lists"}