Problem: the previous name `crossref-verifier` was found long and boring. Solution: rename to `xrefcheck`. |
||
---|---|---|
.buildkite | ||
.github | ||
.reuse | ||
exec | ||
LICENSES | ||
nix | ||
release | ||
src/Crv | ||
src-files | ||
tests | ||
.gitignore | ||
default.nix | ||
LICENSE | ||
package.yaml | ||
README.md | ||
Setup.hs | ||
stack.yaml | ||
stack.yaml.lock | ||
stack.yaml.lock.license | ||
xrefcheck.nix |
Xrefcheck
Xrefcheck is a tool for verifying local and external references in repository documentation that is quick, easy to setup, and suitable to be added to CI.
![Output sample](https://user-images.githubusercontent.com/5394217/70820564-06b06e00-1dea-11ea-9680-27f661ca2a58.png)
Motivation
As the project evolves, links in documentation have a tendency to get broken. This is usually because of:
- File movements;
- Markdown header renames;
- Outer sites ceasing their existence.
This tool will help you to keep references in order.
Aims
Comparing to alternative solutions, this tool tries to achieve the following points:
- Quickness - local references are verified instantly even for moderately-sized repositories.
- Easy setup - no extra actions required, just run the tool in the repository root. Both relative and absolute local links are supported out of the box.
- Conservative verifier allows using this tool in CI, no false positives (e.g. on sites which require authentication) should be reported.
A comparison with other solutions
- linky - a well-configurable verifier written in Rust, scans one file at a time and works good in pair with system utilities like
find
. This tool requires some configuring before it can be applied to a repository or added to CI. - awesome_bot - a solution written in Ruby that can be easily included in CI or integrated into GitHub. Its features include duplicated URLs detection, specifying allowed HTTP error codes and reporting generation. At the moment of writting, it scans only external references and checking anchors is not possible.
- remark-validate-links and remark-lint-no-dead-urls - highly configurable Javascript solution for checking local and remote links resp. It is able to check multiple repositores at once if they are gathered in one folder. Being written on JavaScript, it is fairly slow on large repositories.
- markdown-link-check - another checker written in JavaScript, scans one file at a time.
Supports
mailto:
link resolution. - url-checker - GitHub action which checks links in specified files.
- broken-link-checker - advanced checker for
HTML
files.
Build instructions ↑
Run stack install
to build everything and install the executable.
CI and nix ↑
To build only the executables, run nix-build
. You can use this line on your CI to use xrefcheck:
nix run -f https://github.com/serokell/xrefcheck/archive/master.tar.gz -c xrefcheck
Our CI uses nix-build xrefcheck.nix
to build the whole project, including tests and Haddock.
It is based on the haskell.nix
project.
You can do that too if you wish.
Details
There is a bug which causes us to put some redundancy into Nix files:
nix/sources.json
lists all such dependencies that we obtain usinggit
. It specifies concrete git revisions and SHA256 checksums.xrefcheck.nix
lists all such dependencies as well, but without revisions.
As a consequence, you may have to update these files when you update stack.yaml
.
You can use niv update
to update nix/sources.json
.
Usage ↑
To find all broken links in a repository, run from within its folder:
xrefcheck
To also display all found links and anchors:
xrefcheck -v
For description of other options:
xrefcheck --help
Configuring
Configuration template (with all options explained) can be dumped with:
xrefcheck dump-config
Currently supported options include:
- Timeout for checking external references;
- List of ignored folders.
For further work ↑
- Support for non-Unix systems.
- Support link detection in different languages, not only Markdown.
- Haskell Haddock is first in turn.
Issue tracker ↑
We use GitHub issues as our issue tracker. You can login using your GitHub account to leave a comment or create a new issue.
For Contributors ↑
Please see CONTRIBUTING.md for more information.
About Serokell ↑
Xrefcheck is maintained and funded with ❤️ by Serokell. The names and logo for Serokell are trademark of Serokell OÜ.
We love open source software! See our other projects or hire us to design, develop and grow your idea!