diff options
author | Robert Hensing <roberth@users.noreply.github.com> | 2024-05-27 01:14:19 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-05-27 01:14:19 +0200 |
commit | e0c43a96d20d8604b84f07d016aeb90e2ff0e437 (patch) | |
tree | 46e123ce3f635f8289e3af7d0e0941990f1b963b /doc | |
parent | 5a279778af727927f638dcf136a1a04cd550b3e2 (diff) |
testers.lycheeLinkCheck: init (#298665)
* testers.lycheeLinkCheck: init Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/build-helpers/testers.chapter.md | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md index b734cbbbd4e29..80d293cf1c70c 100644 --- a/doc/build-helpers/testers.chapter.md +++ b/doc/build-helpers/testers.chapter.md @@ -40,6 +40,82 @@ If the `moduleNames` argument is omitted, `hasPkgConfigModules` will use `meta.p ::: +## `lycheeLinkCheck` {#tester-lycheeLinkCheck} + +Check a packaged static site's links with the [`lychee` package](https://search.nixos.org/packages?show=lychee&type=packages&query=lychee). + +You may use Nix to reproducibly build static websites, such as for software documentation. +Some packages will install documentation in their `out` or `doc` outputs, or maybe you have dedicated package where you've made your static site reproducible by running a generator, such as [Hugo](https://gohugo.io/) or [mdBook](https://rust-lang.github.io/mdBook/), in a derivation. + +If you have a static site that can be built with Nix, you can use `lycheeLinkCheck` to check that the hyperlinks in your site are correct, and do so as part of your Nix workflow and CI. + +:::{.example #ex-lycheelinkcheck} + +# Check hyperlinks in the `nix` documentation + +```nix +testers.lycheeLinkCheck { + site = nix.doc + "/share/doc/nix/manual"; +} +``` + +::: + +### Return value {#tester-lycheeLinkCheck-return} + +This tester produces a package that does not produce useful outputs, but only succeeds if the hyperlinks in your site are correct. The build log will list the broken links. + +It has two modes: + +- Build the returned derivation; its build process will check that internal hyperlinks are correct. This runs in the sandbox, so it will not check external hyperlinks, but it is quick and reliable. + +- Invoke the `.online` attribute with [`nix run`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run) ([experimental](https://nixos.org/manual/nix/stable/contributing/experimental-features#xp-feature-nix-command)). This runs outside the sandbox, and checks that both internal and external hyperlinks are correct. + Example: + + ```shell + nix run nixpkgs#lychee.tests.ok.online + ``` + +### Inputs {#tester-lycheeLinkCheck-inputs} + +`site` (path or derivation) {#tester-lycheeLinkCheck-param-site} + +: The path to the files to check. + +`remap` (attribe set, optional) {#tester-lycheeLinkCheck-param-remap} + +: An attribute set where the attribute names are regular expressions. + The values should be strings, derivations, or path values. + + In the returned check's default configuration, external URLs are only checked when you run the `.online` attribute. + + By adding remappings, you can check offline that URLs to external resources are correct, by providing a stand-in from the file system. + + Before checking the existence of a URL, the regular expressions are matched and replaced by their corresponding values. + + Example: + + ```nix + { + "https://nix\\.dev/manual/nix/[a-z0-9.-]*" = "${nix.doc}/share/doc/nix/manual"; + "https://nixos\\.org/manual/nix/(un)?stable" = "${emptyDirectory}/placeholder-to-disallow-old-nix-docs-urls"; + } + ``` + + Store paths in the attribute values are automatically prefixed with `file://`, because lychee requires this for paths in the file system. + If this is a problem, or if you need to control the order in which replacements are performed, use `extraConfig.remap` instead. + +`extraConfig` (attribute set) {#tester-lycheeLinkCheck-param-extraConfig} + +: Extra configuration to pass to `lychee` in its [configuration file](https://github.com/lycheeverse/lychee/blob/master/lychee.example.toml). + It is automatically [translated](https://nixos.org/manual/nixos/stable/index.html#sec-settings-nix-representable) to TOML. + + Example: `{ "include_verbatim" = true; }` + +`lychee` (derivation, optional) {#tester-lycheeLinkCheck-param-lychee} + +: The `lychee` package to use. + ## `testVersion` {#tester-testVersion} Checks that the output from running a command contains the specified version string in it as a whole word. |