Hackage :: [Package]

xrefcheck

[ library, mpl, program, unclassified ] [ Propose Tags ] [ Report a vulnerability ]

Please see the README on GitHub at https://github.com/serokell/xrefcheck#readme

[Skip to Readme]

Modules

[Last Documentation]

  • Xrefcheck
    • Xrefcheck.CLI
    • Xrefcheck.Command
    • Xrefcheck.Config
      • Xrefcheck.Config.Default
    • Xrefcheck.Core
    • Xrefcheck.Orphans
    • Xrefcheck.Progress
    • Xrefcheck.Scan
    • Xrefcheck.Scanners
      • Xrefcheck.Scanners.Markdown
    • Xrefcheck.System
    • Xrefcheck.Util
      • Xrefcheck.Util.Colorize
    • Xrefcheck.Verify

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.1, 0.1.1.1, 0.1.1.2, 0.1.2, 0.1.3, 0.2, 0.2.1, 0.2.2
Change log CHANGES.md
Dependencies aeson, aeson-casing, async, base (>=4.14.3.0 && <5), bytestring, cmark-gfm (>=0.2.5), containers, data-default, directory, dlist, exceptions, filepath, fmt, ftp-client, Glob, http-client, http-types, lens, modern-uri, mtl, o-clock, optparse-applicative (<0.18), pretty-terminal, process, raw-strings-qq, reflection, regex-tdfa, req, tagsoup, text, text-metrics, th-lift-instances, time, transformers, universum, uri-bytestring, with-utf8, xrefcheck, yaml [details]
License MPL-2.0
Copyright 2018-2019 Serokell <https://serokell.io>
Author Kostya Ivanov, Serokell
Maintainer Serokell <hi@serokell.io>
Revised Revision 1 made by AndreasAbel at 2023-06-10T17:38:06Z
Home page https://github.com/serokell/xrefcheck#readme
Bug tracker https://github.com/serokell/xrefcheck/issues
Source repo head: git clone https://github.com/serokell/xrefcheck
Uploaded by dcastro at 2022-10-26T10:56:01Z
Distributions
Executables xrefcheck
Downloads 1240 total (29 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2022-10-26 [all 2 reports]

Readme for xrefcheck-0.2.2

[back to package description]

Xrefcheck

Build status

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

Motivation

As the project evolves, links in documentation have a tendency to get broken. This is usually because of:

  1. File movements;
  2. Markdown header renames;
  3. 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 specified 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 writing, 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 specific file at a time. Supports mailto: link resolution.
  • url-checker - GitHub action which checks links in specified files.
  • linkcheck - advanced site crawler, checks for HTML files. There are other solutions for this particular task which we don't mention here.

At the moment of writing, the listed solutions don't support ftp/ftps links.

Dependencies ↑

Xrefcheck requires you to have git version 2.18.0 or later in your PATH.

Usage ↑

We provide the following ways for you to use xrefcheck:

If none of those are suitable for you, please open an issue!

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

Special functionality

Ignoring external links

If you want some external links to not be verified, you can use one of the following ways to ignore those links:

  1. Add the regular expression that matches the ignoring link to the ignoreRefs parameter of your config file.

    For example:

    ignoreRefs:
  - https://bad.reference.(org|com)(/?)

    allows to ignore both https://bad.reference.org and https://bad.reference.com with or without last "/".

  2. Add right in-place annotation using one of the following ignoring modes (each mode is just a comment with a certain syntax).

    • Ignore the link:

      There are several ways to add this annotation:

      • Just add it like a regular text before the ignoring link.

        Bad ['com' reference](https://bad.reference.com) <!-- xrefcheck: ignore link --> and bad ['org' reference](https://bad.reference.org)

      • Separate the ignoring link from the annotation and the following text with single new lines.

        Bad ['com' reference](https://bad.reference.com) and bad <!-- xrefcheck: ignore link -->
['org'](https://bad.reference.org)
reference

        Therefore only https://bad.reference.org will be ignored.

      • If the ignoring link is the first in a paragraph, then the annotation can also be added before a paragraph.

        <!-- xrefcheck: ignore link -->
[Bad 'org' reference](https://bad.reference.org)
[Bad 'com' reference](https://bad.reference.com)

        It is still the same https://bad.reference.org will be ignored in this case.

    • Ignore the paragraph:

      <!-- xrefcheck: ignore paragraph -->
Bad ['org' reference](https://bad.reference.org)
Bad ['com' reference](https://bad.reference.com)

Bad ['io' reference](https://bad.reference.io)

      In this way, https://bad.reference.org and https://bad.reference.com will be ignored and https://bad.reference.io will still be verified.

    • Ignore the whole file:

      <!-- a comment -->
<!-- another comment -->

<!-- xrefcheck: ignore file -->
...the rest of the file...

      Using this you can ignore the whole file.

Configuring

Configuration template (with all options explained) can be dumped with:

xrefcheck dump-config -t GitHub

Currently supported options include:

  • Timeout for checking external references;
  • List of ignored files.

Build instructions ↑

Run stack install to build everything and install the executable. If you want to use cabal, you need to run (stack2cabal)[https://hackage.haskell.org/package/stack2cabal] first!

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.

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!