1 files changed, 40 insertions, 27 deletions

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 8eda3085f3..921a823a7d 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -49,7 +49,7 @@ All new committers should read this document before they start, and existing com
 Almost all FreeBSD developers have commit rights to one or more repositories.
 However, a few developers do not, and some of the information here applies to them as well.
 (For instance, some people only have rights to work with the Problem Report database.)
-Please see <<non-committers>> for more information.
+Please see crossref:committers-guide[non-committers] for more information.
 
 This document may also be of interest to members of the FreeBSD community who want to learn more about how the project works.
 
@@ -74,7 +74,7 @@ toc::[]
 |`ref*.FreeBSD.org`, `universe*.freeBSD.org` (see also link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts])
 
 |_SMTP Host_
-|`smtp.FreeBSD.org:587` (see also <<smtp-setup>>).
+|`smtp.FreeBSD.org:587` (see also crossref:committers-guide[smtp-setup]).
 
 |`_src/_` Git Repository
 |`ssh://git@gitrepo.FreeBSD.org/src.git`
@@ -98,7 +98,8 @@ toc::[]
 |`stable/n` (`n`-STABLE), `main` (-CURRENT)
 |===
 
-man:ssh[1] is required to connect to the project hosts. For more information, see <<ssh.guide>>.
+man:ssh[1] is required to connect to the project hosts. For more information,
+	see crossref:committers-guide[ssh.guide].
 
 Useful links:
 
@@ -187,7 +188,8 @@ Rather than suggest a single way, here are some links to sites that describe var
 Protect the private key and passphrase.
 If either the private key or passphrase may have been compromised or disclosed, immediately notify mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] and revoke the key.
 
-Committing the new key is shown in <<commit-steps, Steps for New Committers>>.
+Committing the new key is shown in crossref:committers-guide[commit-steps, Steps
+for New Committers].
 
 [[kerberos-ldap]]
 == Kerberos and LDAP web Password for FreeBSD Cluster
@@ -472,7 +474,7 @@ Examples:
 * tag https://cgit.freebsd.org/src/tag/?h=release/13.2.0[release/13.2.0] on the https://cgit.freebsd.org/src/log/?h=releng/13.2[releng/13.2] branch.
 
 ===== Repositories
-Please see the <<admin,Administrative Details>> for the latest information on where to get FreeBSD sources.
+Please see the crossref:committers-guide[admin,Administrative Details] for the latest information on where to get FreeBSD sources.
 $URL below can be obtained from that page.
 
 Note: The project doesn't use submodules as they are a poor fit for our workflows and development model.
@@ -1335,7 +1337,8 @@ At this point, you should have a pristine copy of glorbnitz ready to commit.
 ....
 
 As above, I used `-m` for simplicity, but you should likely create a commit message that explains what a Glorb is and why you'd use a Nitz to get it.
-Not everybody will know so, for your actual commit, you should follow the <<commit-log-message,commit log message>> section instead of emulating the brief style used here.
+Not everybody will know so, for your actual commit, you should follow the
+crossref:committers-guide[commit-log-message,commit log message] section instead of emulating the brief style used here.
 
 ==== Now import it into our repository
 
@@ -1388,7 +1391,7 @@ Here 'good' means:
 
 . All the right files, and none of the wrong ones, were merged into contrib/glorbnitz.
 . No other changes are in the tree.
-. The commit messages look <<commit-log-message,good>>. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats.
+. The commit messages look crossref:committers-guide[commit-log-message,good]. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats.
 . UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc.
 
 [NOTE]
@@ -1515,7 +1518,7 @@ Note: merging vendor branch commits will not work with this technique.
 
 ===== Finding the Subversion Revision
 
-You'll need to make sure that you've fetched the notes (see the <<git-mini-daily-use>> for details).
+You'll need to make sure that you've fetched the notes (see the crossref:committers-guide[git-mini-daily-use]for details).
 Once you have these, notes will show up in the git log command like so:
 
 [source,shell]
@@ -1946,7 +1949,8 @@ The FreeBSD project's Git repositories do not, yet, allow user-created branches
 
 The following instructions show how to set up a user-generated branch, based on the FreeBSD `main` branch, and push it to GitHub.
 
-Before you begin, make sure that your local Git repo is up to date and has the correct origins set <<keeping_current,as shown above.>>
+Before you begin, make sure that your local Git repo is up to date and has the
+correct origins set crossref:committers-guide[keeping_current,as shown above].
 
 [source,shell]
 ````
@@ -1968,7 +1972,8 @@ github	git@github.com:gvnn3/freebsd-src.git (push)
 freebsd	https://git.freebsd.org/src.git (fetch)
 freebsd	ssh://git@gitrepo.freebsd.org/src.git (push)
 ....
-With this in place you can create a branch <<keeping_a_local_branch,as shown above.>>
+With this in place you can create a branch
+crossref:committers-guide[keeping_a_local_branch,as shown above].
 
 [source,shell]
 ....
@@ -2034,7 +2039,8 @@ While this is not an official way to submit patches at this time, sometimes good
 Similar steps can be used to pull branches from other repositories and land those.
 When committing pull requests from others, one should take extra care to examine all the changes to ensure they are exactly as represented.
 
-Before beginning, make sure that the local Git repo is up to date and has the correct origins set <<keeping_current,as shown above.>>
+Before beginning, make sure that the local Git repo is up to date and has the
+correct origins set crossref:committers-guide[keeping_current,as shown above].
 In addition, make sure to have the following origins:
 [source,shell]
 ....
@@ -2103,7 +2109,7 @@ It is worth noting that if your `github` origin uses `https://`, the only step y
 [[vcs-history]]
 == Version Control History
 
-The project has moved to <<git-primer,git>>.
+The project has moved to crossref:committers-guide[git-primer,git].
 
 The FreeBSD source repository switched from CVS to Subversion on May 31st, 2008.
 The first real SVN commit is __r179447__.
@@ -2173,7 +2179,7 @@ It is very important to have a current PGP/GnuPG key in the repository. The key
 Add an entry for each additional mentor/mentee relationship in the bottom section.
 . Generate a Kerberos Password
 +
-See <<kerberos-ldap>> to generate or set a Kerberos account for use with other FreeBSD services like the link:https://bugs.freebsd.org/bugzilla/[bug-tracking database] (you get a bug-tracking account as part of that step).
+See crossref:committers-guide[kerberos-ldap] to generate or set a Kerberos account for use with other FreeBSD services like the link:https://bugs.freebsd.org/bugzilla/[bug-tracking database] (you get a bug-tracking account as part of that step).
 . Optional: Enable Wiki Account
 +
 link:https://wiki.freebsd.org[FreeBSD Wiki] Account - A wiki account allows sharing projects and ideas.
@@ -2222,7 +2228,8 @@ For those willing to send e-mail messages through the FreeBSD.org infrastructure
 . Point your mail client at `smtp.FreeBSD.org:587`.
 . Enable STARTTLS.
 . Ensure your `From:` address is set to `_yourusername_@FreeBSD.org`.
-. For authentication, you can use your FreeBSD Kerberos username and password (see <<kerberos-ldap>>). The `_yourusername_/mail` principal is preferred, as it is only valid for authenticating to mail resources.
+. For authentication, you can use your FreeBSD Kerberos username and password
+  (see crossref:committers-guide[kerberos-ldap]). The `_yourusername_/mail` principal is preferred, as it is only valid for authenticating to mail resources.
 +
 [NOTE]
 ======
@@ -2372,7 +2379,8 @@ Document that approval with an `Approved by:` line in the commit message.
 
 When the mentor decides that a mentee has learned the ropes and is ready to commit on their own, the mentor announces it with a commit to [.filename]#mentors#.
 This file is in the [.filename]#admin# orphan branch of each repository.
-Detailed information on how to access these branches can be found in <<admin-branch>>.
+Detailed information on how to access these branches can be found in
+crossref:committers-guide[admin-branch].
 
 [[pre-commit-review]]
 == Pre-Commit Review
@@ -2922,7 +2930,8 @@ Committers with non-``FreeBSD.org`` Bugzilla accounts can have the old account m
 ====
 . Log in using your old account.
 . Open new bug. Choose `Services` as the Product, and `Bug Tracker` as the Component. In bug description list accounts you wish to be merged.
-. Log in using `FreeBSD.org` account and post comment to newly opened bug to confirm ownership. See <<kerberos-ldap>> for more details on how to generate or set a password for your `FreeBSD.org` account.
+. Log in using `FreeBSD.org` account and post comment to newly opened bug to
+  confirm ownership. See crossref:committers-guide[kerberos-ldap] for more details on how to generate or set a password for your `FreeBSD.org` account.
 . If there are more than two accounts to merge, post comments from each of them.
 ====
 
@@ -2942,7 +2951,8 @@ Committers with non-``FreeBSD.org`` Phabricator accounts can have the old accoun
 [.procedure]
 ====
 . Change your Phabricator account email to your `FreeBSD.org` email.
-. Open new bug on our bug tracker using your `FreeBSD.org` account, see <<bugzilla>> for more information. Choose `Services` as the Product, and `Code Review` as the Component. In bug description request that your Phabricator account be renamed, and provide a link to your Phabricator user. For example, `https://reviews.freebsd.org/p/bob_example.com/`
+. Open new bug on our bug tracker using your `FreeBSD.org` account, see
+  crossref:committers-guide[bugzilla] for more information. Choose `Services` as the Product, and `Code Review` as the Component. In bug description request that your Phabricator account be renamed, and provide a link to your Phabricator user. For example, `https://reviews.freebsd.org/p/bob_example.com/`
 ====
 
 [IMPORTANT]
@@ -3097,7 +3107,7 @@ Their contributions are as valid and as important as your own.
 After all, you made many contributions before you became a committer.
 Always remember that.
 +
-Consider the points raised under <<respect,Respect other committers>> and apply them also to contributors.
+Consider the points raised under crossref:committers-guide[respect,Respect other committers] and apply them also to contributors.
 . Discuss any significant change _before_ committing.
 +
 The repository is not where changes are initially submitted for correctness or argued over, that happens first in the mailing lists or by use of the Phabricator service.
@@ -3154,7 +3164,8 @@ If your changes are to the kernel, make sure you can still compile both GENERIC
 If your changes are anywhere else, make sure you can still make world.
 If your changes are to a branch, make sure your testing occurs with a machine which is running that code.
 If you have a change which also may break another architecture, be sure and test on all supported architectures.
-Please ensure your change works for <<compilers,supported toolchains>>.
+Please ensure your change works for
+crossref:committers-guide[compilers,supported toolchains].
 Please refer to the https://www.FreeBSD.org/internal/[FreeBSD Internal Page] for a list of available resources.
 As other architectures are added to the FreeBSD supported platforms list, the appropriate shared testing resources will be made available.
 . Do not commit to contributed software without _explicit_ approval from the respective maintainers.
@@ -3445,7 +3456,8 @@ For a platform to be promoted to a higher tier, any missing support guarantees m
 [[ports-qa-add-new]]
 ==== How do I add a new port?
 
-Adding a port to the tree is relatively simple. Once the port is ready to be added, as explained later <<ports-qa-add-new-extra,here>>, you need to add the port's directory entry in the category's [.filename]#Makefile#.
+Adding a port to the tree is relatively simple. Once the port is ready to be
+added, as explained later crossref:committers-guide[ports-qa-add-new-extra,here], you need to add the port's directory entry in the category's [.filename]#Makefile#.
 In this [.filename]#Makefile#, ports are listed in alphabetical order and added to the `SUBDIR` variable, like this:
 
 [.programlisting]
@@ -3462,7 +3474,7 @@ Once the port and its category's Makefile are ready, the new port can be committ
 ....
 [TIP]
 ====
-Don't forget to <<port-commit-message-formats,setup git hooks for the ports tree as explained here>>; a specific hook has been developed to verify the category's [.filename]#Makefile#.
+Don't forget to crossref:committers-guide[port-commit-message-formats,setup git hooks for the ports tree as explained here]; a specific hook has been developed to verify the category's [.filename]#Makefile#.
 ====
 
 [[ports-qa-add-new-extra]]
@@ -3565,7 +3577,8 @@ It usually lasted a couple of weeks.
 During that time, build problems were fixed, and the release packages were built.
 This practice is no longer used, as the packages for the releases are built from the current stable, quarterly branch.
 
-For more information on how to merge commits to the quarterly branch, see <<ports-qa-misc-request-mfh>>.
+For more information on how to merge commits to the quarterly branch, see
+crossref:committers-guide[ports-qa-misc-request-mfh].
 
 [[ports-qa-quarterly]]
 === Quarterly Branches
@@ -3714,16 +3727,16 @@ A few people who have access to the FreeBSD machines do not have commit bits.
 Almost all of this document will apply to these developers as well (except things specific to commits and the mailing list memberships that go with them).
 In particular, we recommend that you read:
 
-* <<admin>>
-* <<conventions-everyone>>
+* crossref:committers-guide[admin]
+* crossref:committers-guide[conventions-everyone]
 +
 [NOTE]
 ====
 Get your mentor to add you to the "Additional Contributors" ([.filename]#doc/shared/contrib-additional.adoc#), if you are not already listed there.
 ====
-* <<developer.relations>>
-* <<ssh.guide>>
-* <<rules>>
+* crossref:committers-guide[developer.relations]
+* crossref:committers-guide[ssh.guide]
+* crossref:committers-guide[rules]
 
 [[google-analytics]]
 == Information About Google Analytics