nix/2.home-manager
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4

docs: fix cross-page links broken by mdbook migration

Browse source 
The mdBook migration split the manual into one HTML page per section,
but same-page fragment links (e.g. [Standalone setup](#sec-flakes-standalone))
were left pointing at anchors that now live on other pages, so they
silently do nothing when clicked.

Rewrite all cross-page fragment links in docs/manual and
docs/release-notes to page-qualified relative links. Option anchor
links (#opt-*, #nixos-opt-*, #nix-darwin-opt-*) are untouched since
convert-markup.py rewrites those at build time.

Also give the previously empty-label [](#sec-tests) link in the 25.05
release notes a "Tests" label, since the mdBook renderer does not
auto-fill labels from the target heading.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Vyacheslav Matyukhin 2026-07-10 16:53:39 -04:00 • committed by Austin Horstman
parent a45a7c4514
commit 6dc9e081ba
19 changed files with 31 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/manual/contributing.md
View file

@ -3,8 +3,8 @@
Contributions to Home Manager are very welcome. To make the process as
smooth as possible for both you and the Home Manager maintainers we
provide some guidelines that we ask you to follow. See [Getting
started](#sec-contrib-getting-started) for information on how to set up
a suitable development environment and [Guidelines](#sec-guidelines) for
started](contributing/getting-started.md#sec-contrib-getting-started) for information on how to set up
a suitable development environment and [Guidelines](contributing/guidelines.md#sec-guidelines) for
the actual guidelines.
This text is mainly directed at those who would like to make code

4
docs/manual/contributing/getting-started.md
View file

@ -8,7 +8,7 @@ how to do this.
Once you have a fork of Home Manager you should create a branch starting
at the most recent `master` branch. Give your branch a reasonably
descriptive name. Commit your changes to this branch and when you are
happy with the result and it fulfills [Guidelines](#sec-guidelines) then
happy with the result and it fulfills [Guidelines](guidelines.md#sec-guidelines) then
push the branch to GitHub and [create a pull
request](https://help.github.com/articles/creating-a-pull-request/).
@ -21,7 +21,7 @@ the `home-manager` command use it by either
$ home-manager -I home-manager=$HOME/devel/home-manager
```
or, if using [flakes](#sec-flakes-standalone):
or, if using [flakes](../nix-flakes/standalone.md#sec-flakes-standalone):
``` shell
$ home-manager --override-input home-manager ~/devel/home-manager

8
docs/manual/contributing/guidelines.md
View file

@ -89,7 +89,7 @@ configuration location with an environment variable, for example
If at all possible, make sure to add new tests and expand existing tests
so that your change will keep working in the future. See
[Tests](#sec-tests) for more information about the Home Manager test
[Tests](tests.md#sec-tests) for more information about the Home Manager test
suite.
All contributed code *must* pass the test suite.
@ -182,7 +182,7 @@ consistent commit message format as described in
If your contribution includes a change that should be communicated to
users of Home Manager then you can add a news entry. The entry must be
formatted as described in [News](#sec-news).
formatted as described in [News](news.md#sec-news).
When new modules are added a news entry should be included.
@ -190,7 +190,7 @@ News entries and release notes serve different purposes. Release notes
should be updated separately when a change affects users migrating
between stable releases, such as state version default changes, required
migration steps, or broad behavior changes. See
[Release Notes](#sec-contributing-release-notes) and [News](#sec-news)
[Release Notes](release-notes.md#sec-contributing-release-notes) and [News](news.md#sec-news)
for more details.
## Use conditional modules and news {#sec-guidelines-conditional-modules}
@ -209,7 +209,7 @@ in the module behavior and in any platform-specific tests rather than in a
separate module discovery call.
Similarly, if you are adding a news entry then it should be shown only
to users that may find it relevant, see [News](#sec-news) for a
to users that may find it relevant, see [News](news.md#sec-news) for a
description of conditional news.
## Mind the license {#sec-guidelines-licensing}

2
docs/manual/contributing/news.md
View file

@ -12,7 +12,7 @@ communication about noteworthy changes, such as a new module, a new
feature, or a specific deprecation. Release notes are read from the
website documentation and should summarize what users need to know before
or during a stable-release upgrade. See
[Release Notes](#sec-contributing-release-notes) for guidance on changes
[Release Notes](release-notes.md#sec-contributing-release-notes) for guidance on changes
that affect stable-release upgrades.
If you do have a change worthy of a news entry then please add one in

2
docs/manual/faq/change-package-module.md
View file

@ -31,7 +31,7 @@ this package. This can typically be done in two ways.
should work OK. With flakes, pass the unstable package set as
described in
[How do I install packages from Nixpkgs unstable?](#_how_do_i_install_packages_from_nixpkgs_unstable)
[How do I install packages from Nixpkgs unstable?](unstable.md#_how_do_i_install_packages_from_nixpkgs_unstable)
and then use the extra module argument:
``` nix

8
docs/manual/installation.md
View file

@ -6,26 +6,26 @@ Home Manager can be used in three primary ways:
NixOS and Darwin, this is the only available choice. It is also
recommended for people on NixOS or Darwin that want to manage their
home directory independently of the system as a whole. See
[Standalone installation](#sec-install-standalone) for instructions
[Standalone installation](installation/standalone.md#sec-install-standalone) for instructions
on how to perform this installation.
2. As a module within a NixOS system configuration. This allows the
user profiles to be built together with the system when running
`nixos-rebuild`. See [NixOS module](#sec-install-nixos-module) for a
`nixos-rebuild`. See [NixOS module](installation/nixos.md#sec-install-nixos-module) for a
description of this setup.
3. As a module within a
[nix-darwin](https://github.com/nix-darwin/nix-darwin/) system
configuration. This allows the user profiles to be built together
with the system when running `darwin-rebuild`. See [nix-darwin
module](#sec-install-nix-darwin-module) for a description of this
module](installation/nix-darwin.md#sec-install-nix-darwin-module) for a description of this
setup.
:::{.note}
In this chapter we describe how to install Home Manager in the standard
way using channels. If you prefer to use [Nix
Flakes](https://wiki.nixos.org/wiki/Flakes) then please see the instructions
in [nix flakes](#ch-nix-flakes).
in [nix flakes](nix-flakes.md#ch-nix-flakes).
:::
```{=include=} sections

2
docs/manual/installation/nix-darwin.md
View file

@ -124,5 +124,5 @@ Use `home-manager.sharedModules` to add Home Manager modules to every user
declared under `home-manager.users`.
:::
Once installed you can see [Using Home Manager](#ch-usage) for a more detailed
Once installed you can see [Using Home Manager](../usage.md#ch-usage) for a more detailed
description of Home Manager and how to use it.

2
docs/manual/installation/nixos.md
View file

@ -171,5 +171,5 @@ Use `home-manager.sharedModules` to add Home Manager modules to every user
declared under `home-manager.users`.
:::
Once installed you can see [Using Home Manager](#ch-usage) for a more detailed
Once installed you can see [Using Home Manager](../usage.md#ch-usage) for a more detailed
description of Home Manager and how to use it.

2
docs/manual/installation/standalone.md
View file

@ -71,5 +71,5 @@ checkout of the repository then you can use the
[home-manager.path](#opt-programs.home-manager.path) option to specify the absolute
path to the repository.
Once installed you can see [Using Home Manager](#ch-usage) for a more detailed
Once installed you can see [Using Home Manager](../usage.md#ch-usage) for a more detailed
description of Home Manager and how to use it.

6
docs/manual/nix-flakes.md
View file

@ -12,18 +12,18 @@ flake in three ways:
NixOS and Darwin, this is the only available choice. It is also
recommended for people on NixOS or Darwin that want to manage their
home directory independently of the system as a whole. See
[Standalone setup](#sec-flakes-standalone) for instructions on how
[Standalone setup](nix-flakes/standalone.md#sec-flakes-standalone) for instructions on how
to perform this installation.
2. As a module within a NixOS system configuration. This allows the
user profiles to be built together with the system when running
`nixos-rebuild`. See [NixOS module](#sec-flakes-nixos-module) for a
`nixos-rebuild`. See [NixOS module](nix-flakes/nixos.md#sec-flakes-nixos-module) for a
description of this setup.
3. As a module within a [nix-darwin](https://github.com/nix-darwin/nix-darwin/)
system configuration. This allows the user profiles to be built
together with the system when running `darwin-rebuild`. See
[nix-darwin module](#sec-flakes-nix-darwin-module) for a
[nix-darwin module](nix-flakes/nix-darwin.md#sec-flakes-nix-darwin-module) for a
description of this setup.
Advanced users may want Home Manager's `nixpkgs` input to follow the

2
docs/manual/nix-flakes/prerequisites.md
View file

@ -33,5 +33,5 @@
Unlike the channel-based setup, `home.nix` will be evaluated when
the flake is built, so it must be present before bootstrap of Home
Manager from the flake. See [Configuration Example](#sec-usage-configuration) for
Manager from the flake. See [Configuration Example](../usage/configuration.md#sec-usage-configuration) for
introduction about writing a Home Manager configuration.

2
docs/manual/usage.md
View file

@ -43,7 +43,7 @@ option will state the expected type, for
[programs.emacs.enable](#opt-programs.emacs.enable) you will see "Type: boolean". You
there also find information about the default value and a description of
the option. You can find the complete option documentation in
[Home Manager Configuration Options](#ch-options) or directly in the terminal by running
[Home Manager Configuration Options](options.md#ch-options) or directly in the terminal by running
``` shell
man home-configuration.nix

2
docs/manual/usage/dotfiles.md
View file

@ -39,7 +39,7 @@ This error is about a file that Home Manager wants to manage as a
symbolic link in your home directory. It is separate from package
profile collisions, which usually mention `installPackages` or a
`collision between .../bin/...` path. For package collisions, see
[Why is there a collision error when switching generation?](#_why_is_there_a_collision_error_when_switching_generation).
[Why is there a collision error when switching generation?](../faq/collision.md#_why_is_there_a_collision_error_when_switching_generation).
## Resolving file collisions {#sec-usage-dotfiles-collisions}

2
docs/manual/usage/updating.md
View file

@ -8,7 +8,7 @@ without changing release branches.
If you want to move from one release branch to another, such as
`release-25.05` to `release-25.11`, or between a release branch and
`master`, see
[Upgrading to a new Home Manager release](#sec-upgrade-release).
[Upgrading to a new Home Manager release](upgrading.md#sec-upgrade-release).
## Flake-Based Configurations {#sec-updating-flakes}

4
docs/manual/usage/upgrading.md
View file

@ -169,7 +169,7 @@ affected configuration.
### Common Issues {#sec-upgrade-release-state-troubleshooting-common-issues}
Check the [Home Manager Release Notes](#ch-release-notes) for breaking changes.
Check the [Home Manager Release Notes](../release-notes/release-notes.md#ch-release-notes) for breaking changes.
1. **Version Mismatch Warning**: If you see warnings about version
mismatches, ensure your Home Manager branch matches the Nixpkgs
@ -199,4 +199,4 @@ the expected release branch.
## Additional Resources {#sec-upgrade-release-resources}
- [NixOS Stable Release Notes](https://nixos.org/manual/nixos/stable/release-notes)
- [Home Manager Release Notes](#ch-release-notes)
- [Home Manager Release Notes](../release-notes/release-notes.md#ch-release-notes)

2
docs/release-notes/rl-2305.md
View file

@ -36,7 +36,7 @@ This release has the following notable changes:
optionally also activate it. The recommended installation method for
a standalone Home Manager setup with Nix flakes uses this new
command. The standard installation method remains the same but uses
the new command internally. See [sec-flakes-standalone](#sec-flakes-standalone) for
the new command internally. See [sec-flakes-standalone](../nix-flakes/standalone.md#sec-flakes-standalone) for
more.
## State Version Changes {#sec-release-23.05-state-version-changes}

2
docs/release-notes/rl-2505.md
View file

@ -19,7 +19,7 @@ This release has the following notable changes:
- The Home Manager test suite has been removed from the main Nix Flake
since it caused unnecessary evaluations and downloads. Instead the
tests are available through a Nix Flake file inside the `tests`
directory. See [](#sec-tests) for example commands.
directory. See [Tests](../contributing/tests.md#sec-tests) for example commands.
## State Version Changes {#sec-release-25.05-state-version-changes}

4
docs/release-notes/rl-2511.md
View file

@ -16,7 +16,7 @@ This release has the following notable changes:
term removed all together. If you have developed tooling that
directly call the generated activation script, then you are
encouraged to adapt to the new behavior. See the
[Activation](#sec-internals-activation) section in the manual for
[Activation](../internals/activation.md#sec-internals-activation) section in the manual for
details on how to call the activation script.
- The `home-manager switch` command now offers a `--rollback` option.
@ -25,7 +25,7 @@ This release has the following notable changes:
previously possible to accomplish this by manually activating an old
generation, it always created a new profile generation. The new
behavior mirrors the behavior of `nixos-rebuild switch --rollback`.
See the [Rollbacks](#sec-usage-rollbacks) section for more.
See the [Rollbacks](../usage/rollbacks.md#sec-usage-rollbacks) section for more.
- The `home-manager switch` command now offers a
`--specialisation NAME` option. When given, the switch activates the

2
docs/release-notes/rl-2605.md
View file

@ -61,7 +61,7 @@ This release has the following notable changes:
[modular services](https://nixos.org/manual/nixos/unstable/#modular-services).
Service modules shipped with packages (e.g.
`pkgs.<name>.passthru.services.default`) drop in unchanged and are lifted to
user systemd units. See [Modular Services](#sec-usage-modular-services) for
user systemd units. See [Modular Services](../usage/modular-services.md#sec-usage-modular-services) for
details.
- Dedicated modules were added for several VSCode forks (`programs.cursor`,