Skip to content

Check and fix nix-manual redirect targets #14711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Ericson2314 merged 4 commits into from
Dec 5, 2025
Merged

Check and fix nix-manual redirect targets #14711

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3632abb
nix-manual: Split out redirects.json
roberth Dec 5, 2025
ee30827
Check nix-manual redirect targets in linkcheck
roberth Dec 5, 2025
d509927
Remove _redirects from link checking for now
roberth Dec 5, 2025
c8601a2
Fix redirects.json targets
roberth Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions doc/manual/generate-redirects.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
#!/usr/bin/env python3
"""Generate redirects.js from template and JSON data."""

import sys

template_path, json_path, output_path = sys.argv[1:]

with open(json_path) as f:
json_content = f.read().rstrip()

with open(template_path) as f:
template = f.read()

with open(output_path, 'w') as f:
f.write(template.replace('@REDIRECTS_JSON@', json_content))
19 changes: 19 additions & 0 deletions doc/manual/meson.build
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,24 @@ generate_manual_deps = files(
'generate-deps.py',
)

# Generate redirects.js from template and JSON data
redirects_js = custom_target(
'redirects.js',
command : [
python,
'@INPUT0@',
'@INPUT1@',
'@INPUT2@',
'@OUTPUT@',
],
input : [
'generate-redirects.py',
'redirects.js.in',
'redirects.json',
],
output : 'redirects.js',
)

# Generates types
subdir('source/store')
# Generates builtins.md and builtin-constants.md.
Expand Down Expand Up @@ -109,6 +127,7 @@ manual = custom_target(
'book.toml.in',
'anchors.jq',
'custom.css',
redirects_js,
nix3_cli_files,
experimental_features_shortlist_md,
experimental_feature_descriptions_md,
Expand Down
42 changes: 28 additions & 14 deletions doc/manual/package.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
{
lib,
callPackage,
mkMesonDerivation,
runCommand,

meson,
ninja,
Expand Down Expand Up @@ -95,22 +97,34 @@ mkMesonDerivation (finalAttrs: {
*/
passthru.site = finalAttrs.finalPackage + "/share/doc/nix/manual";

passthru.tests = {
# https://nixos.org/manual/nixpkgs/stable/index.html#tester-lycheeLinkCheck
linkcheck = testers.lycheeLinkCheck {
inherit (finalAttrs.finalPackage) site;
extraConfig = {
exclude = [
# Exclude auto-generated JSON schema documentation which has
# auto-generated fragment IDs that don't match the link references
".*/protocols/json/.*\\.html"
# Exclude undocumented builtins
".*/language/builtins\\.html#builtins-addErrorContext"
".*/language/builtins\\.html#builtins-appendContext"
];
passthru.tests =
let
redirect-targets = callPackage ./redirect-targets-html.nix { };
in
{
# https://nixos.org/manual/nixpkgs/stable/index.html#tester-lycheeLinkCheck
linkcheck = testers.lycheeLinkCheck {
site =
let
plain = finalAttrs.finalPackage.site;
in
runCommand "nix-manual-with-redirect-targets" { } ''
cp -r ${plain} $out
chmod -R u+w $out
cp ${redirect-targets}/redirect-targets.html $out/redirect-targets.html
'';
extraConfig = {
exclude = [
# Exclude auto-generated JSON schema documentation which has
# auto-generated fragment IDs that don't match the link references
".*/protocols/json/.*\\.html"
# Exclude undocumented builtins
".*/language/builtins\\.html#builtins-addErrorContext"
".*/language/builtins\\.html#builtins-appendContext"
];
};
};
};
};

meta = {
platforms = lib.platforms.all;
Expand Down
62 changes: 62 additions & 0 deletions doc/manual/redirect-targets-html.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Generates redirect-targets.html containing all redirect targets for link checking.
# Used by: doc/manual/package.nix (passthru.tests.linkcheck)

{
stdenv,
lib,
jq,
}:

stdenv.mkDerivation {
name = "redirect-targets-html";

src = lib.fileset.toSource {
root = ./.;
fileset = ./redirects.json;
};

nativeBuildInputs = [ jq ];

installPhase = ''
mkdir -p $out

{
echo '<!DOCTYPE html>'
echo '<html><head><title>Nix Manual Redirect Targets</title></head><body>'
echo '<h1>Redirect Targets to Check</h1>'
echo '<p>This document contains all redirect targets from the Nix manual.</p>'

echo '<h2>Client-side redirects (from redirects.json)</h2>'
echo '<ul>'

# Extract all redirects with their source pages to properly resolve relative paths
jq -r 'to_entries[] | .key as $page | .value | to_entries[] | "\($page)\t\(.value)"' \
redirects.json | while IFS=$'\t' read -r page target; do

page_dir=$(dirname "$page")

# Handle fragment-only targets (e.g., #primitives)
if [[ "$target" == \#* ]]; then
# Fragment is on the same page
resolved="$page$target"
echo "<li><a href=\"$resolved\">$resolved</a> (fragment on $page)</li>"
continue
fi

# Resolve relative path based on the source page location
resolved="$page_dir/$target"

echo "<li><a href=\"$resolved\">$resolved</a> (from $page)</li>"
done

echo '</ul>'
echo '</body></html>'
} > $out/redirect-targets.html

echo "Generated redirect targets document with $(grep -c '<li>' $out/redirect-targets.html) links"
'';

meta = {
description = "HTML document listing all Nix manual redirect targets for link checking";
};
}
Loading
Loading