Merge pull request #182 from circleci/DOCSS-1854-html-proofer

rosieyohannan · web-flow · commit b6b8f753c3aa · 2025-08-07T00:31:20.000+01:00
set up htmlproofer and fix links
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -95,7 +95,14 @@ jobs:
           command: |
             set -e
             echo "[INFO] Validating built site with HTML Proofer..."
-            htmlproofer ./build --checks html --ignore-urls "/#.*/" --ignore-empty-alt
+            # Handle path prefix and ignore search template placeholders
+            htmlproofer ./build \
+              --ignore-empty-alt \
+              --checks 'Links,Images' \
+              --disable-external \
+              --swap-urls '^/docs/:/' \
+              --ignore-files './build/api/v1/index.html,./build/api/v2/index.html' \
+              --ignore-urls '[url],[path]'
       - notify_error:
           message: "Validation job failed for branch ${CIRCLE_BRANCH}"
 
diff --git a/api-v1/index.html b/api-v1/index.html
@@ -2169,8 +2169,8 @@ <h2 id='list-ordering'>List Ordering</h2>
 <p>There are two API endpoints where the list order is significant:</p>
 
 <ul>
-<li><a href="https://circleci.com/docs/api/v1-reference/#recent-builds">Recent jobs across all projects</a></li>
-<li><a href="https://circleci.com/docs/api/v1-reference/#recent-builds-project">Recent jobs for a single project</a></li>
+<li><a href="#recent-jobs-across-all-projects">Recent jobs across all projects</a></li>
+<li><a href="#recent-jobs-for-a-single-project">Recent jobs for a single project</a></li>
 </ul>
 
 <p>In both cases, jobs are returned in the order that they were created. For all other endpoints, the order has no special significance.</p>
diff --git a/docs/guides/modules/ROOT/partials/runner/terms.adoc b/docs/guides/modules/ROOT/partials/runner/terms.adoc
@@ -20,7 +20,7 @@ Your role within your org is determined differently depending on how you integra
 * If your code is integrated with CircleCI via the GitHub App, GitLab, or Bitbucket Data Center, you can check roles by navigating to menu:Organization Settings[People]. Full details on roles and permissions are available in the xref:guides:permissions-authentication:roles-and-permissions-overview.adoc[Roles and permissions overview].
 
 ****
-To find out which GitHub integration you are using, head to the link:https://circleci.com/app[CircleCI web app], select your org, select **Organization Home** from the sidebar, and inspect the URL in your browser:
+To find out which GitHub integration you are using, head to the link:https://app.circleci.com[CircleCI web app], select your org, select **Organization Home** from the sidebar, and inspect the URL in your browser:
 
 * This style of URL indicates you authenticated with the **GitHub App**: `https://app.circleci.com/organization/circleci/UTxCZDiJ9MLGLC8hR1ZDmg`
 * This style of URL indicates you authenticated with the **GitHub OAuth app**: `https://app.circleci.com/pipelines/github/<your GitHub username/organization name>`
diff --git a/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc b/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc
@@ -261,7 +261,7 @@ In terms of network and storage, usage can be tricky to understand, so it is sug
 
 image::guides:ROOT:web_ui_plan_network.png[Network usage]
 
-You can learn more about billing in the billing section of the xref:server-admin:operator:faq.adoc#billing[FAQ] page.
+You can learn more about billing in the billing section of the xref:reference:ROOT:faq.adoc#billing[FAQ] page.
 
 [#usage-controls]
 === Usage controls
diff --git a/docs/guides/modules/deploy/pages/deploys-overview.adoc b/docs/guides/modules/deploy/pages/deploys-overview.adoc
@@ -301,7 +301,7 @@ Some points to consider when manually configuring an automatically detected depl
 * If you change a component name that was originally autodetected by CircleCI, we create a new component and the history **will not** carry over. If you do not update the component name, the history **will** carry over.
 
 * If your environment integration has an autogenerated name, you can edit the name as follows:
-. In the link:https://circleci.com/app/home[CircleCI web app], select your organization.
+. In the link:https://app.circleci.com[CircleCI web app], select your organization.
 . Select **Deploys** in the sidebar.
 . Select the **Environments** tab.
 . Find your environment and select cog icon image:guides:ROOT:icons/settings.svg[settings icon, role="no-border"] to enter the environment integration settings page.
diff --git a/docs/guides/modules/execution-managed/pages/custom-images.adoc b/docs/guides/modules/execution-managed/pages/custom-images.adoc
@@ -145,7 +145,7 @@ The example uses Docker Hub, but you can use different registries if you prefer.
 [#preparing-the-image-for-the-registry]
 === 8. Prepare the image for the registry
 
-. Log in to Docker Hub with your account and create a new repository on the https://hub.docker.com/add/repository/[add repository] page.
+. Log in to Docker Hub with your account and create a new repository on the Repositories page.
 It is best practice to use a pattern similar to `<project-name>-<container-name>` for a repository name (for example, `cci-demo-docker-primary`).
 
 . Next, rebuild your image using your account and repository name:
@@ -199,7 +199,7 @@ NOTE: This section assumes you have already used Docker login locally.
 
 This section demonstrates how to build a Ruby container to use on CircleCI.
 
-The example starts with the link:https://hub.docker.com/_/ruby/[Ruby 2.1] image. However, instead of using FROM `ruby:2.1` as the base image it describes how the container is built. From the Ruby Docker Hub page, go to the link:https://raw.githubusercontent.com/docker-library/ruby/e32433a12099d96dc5a1b28a011b73af4f17cfff/2.1/Dockerfile10[2.1/Dockerfile].
+The example starts with the link:https://hub.docker.com/_/ruby/[Ruby 2.1] image. However, instead of using FROM `ruby:2.1` as the base image it describes how the container is built. From the Ruby Docker Hub page, go to the 2.1/Dockerfile.
 
 Notice the environment variables that are used to pull in the correct versions.
 
diff --git a/docs/guides/modules/integration/pages/new-relic-integration.adoc b/docs/guides/modules/integration/pages/new-relic-integration.adoc
@@ -13,7 +13,7 @@ The link:https://newrelic.com/instant-observability/circleci[New Relic CircleCI
 
 Complete the following steps to set up a CircleCI webhook to forward your logs to New Relic. For more information, refer to the New Relic CircleCI link:https://docs.newrelic.com/docs/logs/forward-logs/circleci-logs/[installation docs].
 
-. Log in to the link:https://app.circleci.com/projects)[CircleCI web app].
+. Log in to the link:https://app.circleci.com)[CircleCI web app].
 
 . Access one of your CircleCI projects.
 
@@ -27,7 +27,7 @@ Complete the following steps to set up a CircleCI webhook to forward your logs t
 ** **Webhook name**: give your webhook an identifiable name, for example, `New Relic CI Visibility`
 ** **Receiver URL**: Use New Relic's **Logs endpoint**. Use the region you set for your New Relic account.
 +
-Replace `YOUR_LICENSE_KEY` with your New Relic license key, which you can link:https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#manage-license-key)[retrieve from the UI or API].
+Replace `YOUR_LICENSE_KEY` with your New Relic license key, which you can link:https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#manage-license-key[retrieve from the UI or API].
 +
 **US**: `https://log-api.newrelic.com/log/v1?Api-Key=YOUR_LICENSE_KEY`
 +
diff --git a/docs/guides/modules/optimize/pages/artifacts.adoc b/docs/guides/modules/optimize/pages/artifacts.adoc
@@ -181,7 +181,7 @@ curl --silent --request GET --url https://circleci.com/api/v2/workflow/:workflow
   | wget --verbose --header "Circle-Token: $CIRCLE_TOKEN" --no-verbose --input-file -
 ----
 
-You can read more about using CircleCI's API to interact with artifacts in our link:../api/v1/index.html#artifacts[API reference guide].
+You can read more about using CircleCI's API to interact with artifacts in our link:../../api/v1/index.html#artifacts[API reference guide].
 
 [cols="1,2", options="header"]
 |===
diff --git a/docs/guides/modules/optimize/pages/caching.adoc b/docs/guides/modules/optimize/pages/caching.adoc
@@ -335,7 +335,7 @@ During step execution, the templates above are replaced by runtime values and us
 | The number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), also known as POSIX or UNIX epoch. This cache key is a good option if you need to ensure a new cache is always stored for each run.
 
 | `{{ arch }}`
-| Captures OS and CPU (architecture, family, model) information. Useful when caching compiled binaries that depend on OS and CPU architecture, for example, `darwin-amd64-6_58` versus `linux-amd64-6_62`. See xref:server-admin:operator:faq.adoc#cpu-architecture-circleci-support[supported CPU architectures].
+| Captures OS and CPU (architecture, family, model) information. Useful when caching compiled binaries that depend on OS and CPU architecture, for example, `darwin-amd64-6_58` versus `linux-amd64-6_62`. See xref:reference:ROOT:faq.adoc#cpu-architecture-circleci-support[supported CPU architectures].
 |===
 
 [#further-notes-on-using-keys-and-templates]
@@ -455,7 +455,7 @@ If your source code changes frequently, we recommend using fewer, more specific
 
 Even with the narrowest `restore_cache` option (`source-v1-{{ .Branch }}-{{ .Revision }}`), source caching can be greatly beneficial, for example:
 
-* Running repeated builds against the same git revision (for example, with link:../api/v1/index.html#trigger-a-new-build-by-project-preview[API-triggered builds])
+* Running repeated builds against the same git revision (for example, with link:../../api/v2/index.html#tag/Pipeline/operation/triggerPipelineRun[API-triggered builds])
 * When using workflows, where you might otherwise need to `checkout` the same repository once per workflow job.
 
 However, it is worth comparing build times with and without source caching. `git clone` is often faster than `restore_cache`.
diff --git a/docs/guides/modules/optimize/pages/persist-data.adoc b/docs/guides/modules/optimize/pages/persist-data.adoc
@@ -154,9 +154,9 @@ Network charges apply when an organization has runner network egress beyond the
 
 Storage charges apply when you retain artifacts, workspaces, and caches beyond the included storage GB allotment.
 
-You can find out how much network and storage usage is available on your plan by visiting the features section of the link:https://circleci.com/pricing/[Pricing] page. If you would like more details about credit usage, and how to calculate your potential network and storage costs, visit the billing section on the xref:server-admin:operator:faq.adoc#calculate-monthly-storage-and-network-costs[FAQ] page.
+You can find out how much network and storage usage is available on your plan by visiting the features section of the link:https://circleci.com/pricing/[Pricing] page. If you would like more details about credit usage, and how to calculate your potential network and storage costs, visit the billing section on the xref:reference:ROOT:faq.adoc#calculate-monthly-storage-and-network-costs[FAQ] page.
 
-For questions on data usage for the IP ranges feature, visit the xref:server-admin:operator:faq.adoc#calculate-monthly-IP-ranges-costs[FAQ] page.
+For questions on data usage for the IP ranges feature, visit the xref:reference:ROOT:faq.adoc#calculate-monthly-IP-ranges-costs[FAQ] page.
 
 [#reducing-excess-use-of-network-egress-and-storage]
 === Reducing excess use of network egress and storage
diff --git a/docs/guides/modules/orchestrate/pages/workflows.adoc b/docs/guides/modules/orchestrate/pages/workflows.adoc
@@ -899,5 +899,5 @@ Go to menu:Settings[Branches] in GitHub and select btn:[Edit] on the protected b
 [#see-also]
 == See also
 
-* See the xref:server-admin:operator:faq.adoc#workflows[workflows] section of the FAQ.
+* See the xref:reference:ROOT:faq.adoc#workflows[workflows] section of the FAQ.
 * For workflow configuration examples, see the link:https://github.com/CircleCI-Public/circleci-demo-workflows[CircleCI Demo Workflows] page on GitHub.
diff --git a/docs/guides/modules/permissions-authentication/pages/set-up-sso.adoc b/docs/guides/modules/permissions-authentication/pages/set-up-sso.adoc
@@ -22,7 +22,7 @@ To begin setting up a SAML SSO connection in your CircleCI organization, follow
 
 === Configure your Identity Provider (IdP)
 
-Next you will configure your IdP. The steps to do this will vary depending on your IdP. For example, if you are using Okta, refer to link:https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.html[Okta's documentation].
+Next you will configure your IdP. The steps to do this will vary depending on your IdP. For example, if you are using Okta, refer to link:https://help.okta.com/[Okta's documentation].
 
 . Open your IdP and paste the required configuration details (**Setup Parameters** and **Allowed iFrame Origin**) retrieved from CircleCI in the previous section to configure your IdP.
 . Add `https://app.circleci.com` to your IdP's trusted origins for iframe embedding. This is required to validate a user's active SSO session when they are interacting with an SSO organization in CircleCI.
diff --git a/docs/guides/modules/plans-pricing/pages/plan-overview.adoc b/docs/guides/modules/plans-pricing/pages/plan-overview.adoc
@@ -35,7 +35,7 @@ Visit the pages below to learn about the features of CircleCI's plans.
 == Configuring your credit plan
 To set up a Free or Performance Plan, go to **Plan > Plan Overview** in the CircleCI link:https://app.circleci.com/[web application]. From there, select the plan that best fits your needs. To set up a Scale or Server Plan, link:https://circleci.com/talk-to-us/[contact us].
 
-For details on cancelling a Performance Plan, refer to the xref:server-admin:operator:faq.adoc#cancel-performance-plan[Cancel Performance Plan FAQ].
+For details on cancelling a Performance Plan, refer to the xref:reference:ROOT:faq.adoc#cancel-performance-plan[Cancel Performance Plan FAQ].
 
 [#managing-credit-usage]
 == Managing credit usage
diff --git a/docs/guides/modules/plans-pricing/pages/plan-performance.adoc b/docs/guides/modules/plans-pricing/pages/plan-performance.adoc
@@ -46,7 +46,7 @@ The link:https://app.circleci.com/[CircleCI web app] allows for the customizatio
 === Additional support options
 Additional support through SLAs (limited hours and days), and support package add-ons. The Performance Plan also has access to the link:https://discuss.circleci.com/[community forums], link:https://support.circleci.com/hc/en-us[support portal], and our link:https://support.circleci.com/hc/en-us/requests/new[global ticket-based system].
 
-NOTE: For details on cancelling a Performance Plan, refer to the xref:server-admin:operator:faq.adoc#cancel-performance-plan[Cancel Performance Plan FAQ].
+NOTE: For details on cancelling a Performance Plan, refer to the xref:reference:ROOT:faq.adoc#cancel-performance-plan[Cancel Performance Plan FAQ].
 
 [#circleci-features]
 == CircleCI features
diff --git a/docs/guides/modules/security/pages/inject-environment-variables-with-api.adoc b/docs/guides/modules/security/pages/inject-environment-variables-with-api.adoc
@@ -11,14 +11,14 @@ include::ROOT:partial$notes/server-api-examples.adoc[]
 Pipeline parameters can be used to pass variables using the CircleCI API v2.
 
 A pipeline can be triggered with specific parameter values using the API v2
-endpoint to link:https://circleci.com/docs/api/v2/index.html#operation/getPipelineConfigById[trigger a pipeline].
+endpoint to link:../../api/v2/index.html#operation/getPipelineConfigById[trigger a pipeline].
 This can be done by passing a `parameters` key in the JSON packet of the `POST` body.
 
 The example below triggers a pipeline with parameter values for `workingdir` and `image-tag`.
 
 NOTE: In order to pass a parameter when triggering a pipeline via the API, the parameter must be xref:reference:ROOT:reusing-config.adoc#using-the-parameters-declaration[declared in the configuration file].
 
-CAUTION: If your project code is integrated with CircleCI via the GitHub App, GitLab or Bitbucket Data Center, you will need to use the new link:https://circleci.com/docs/api/v2/index.html#tag/Pipeline/operation/triggerPipelineRun[Trigger a new pipeline endpoint] rather than the endpoint used in this example.
+CAUTION: If your project code is integrated with CircleCI via the GitHub App, GitLab or Bitbucket Data Center, you will need to use the new link:../../api/v2/index.html#tag/Pipeline/operation/triggerPipelineRun[Trigger a new pipeline endpoint] rather than the endpoint used in this example.
 
 ```shell
 curl -u ${CIRCLE_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
@@ -71,7 +71,7 @@ export param1="value1"
 export param2="500"
 ```
 
-A POST API call with an empty body will start a new run of the named branch. Refer to the link:../api/v1/index.html#trigger-a-new-job-with-a-branch[Trigger a new job with a branch] section of the API v1 documentation for details.
+A POST API call with an empty body will start a new run of the named branch. Refer to the link:../../api/v1/index.html#trigger-a-new-job-with-a-branch[Trigger a new job with a branch] section of the API v1 documentation for details.
 
 [#best-practices-for-using-build-parameters-with-api-v1]
 === Best practices for using build parameters with API v1
diff --git a/docs/guides/modules/toolkit/pages/api-intro.adoc b/docs/guides/modules/toolkit/pages/api-intro.adoc
@@ -5,8 +5,8 @@
 
 The CircleCI API may be used to make API calls to interact with your pipelines, projects and orgs, including retrieving detailed information about users, jobs, workflows, and pipelines, as well as triggering pipelines. There are currently two supported API versions:
 
-* link:../api/v1/index.html[API v1.1 Reference]
-* link:../api/v2/index.html[API v2 Reference]
+* link:../../api/v1/index.html[API v1.1 Reference]
+* link:../../api/v2/index.html[API v2 Reference]
 
 API v2 includes several powerful features (for example, support for pipelines and pipeline parameters) that are unavailable in API v1.1. It is recommended that CircleCI users migrate their scripts to API v2 stable endpoints as soon as possible.
 
@@ -19,7 +19,7 @@ To get started with the API v2, see the xref:api-developers-guide.adoc[API devel
 
 The CircleCI API v2 release includes several new endpoints, and deprecates some others. The sections below list the endpoints added for this release, in addition to the endpoints that have been removed.
 
-For a complete list of all API v2 endpoints, refer to the https://circleci.com/docs/api/v2/[API v2 Reference Guide], which contains a detailed description of each individual endpoint, as well as information on required and optional parameters, HTTP status and error codes, and code samples you may use in your workflows.
+For a complete list of all API v2 endpoints, refer to the link:../../api/v2/[API v2 Reference Guide], which contains a detailed description of each individual endpoint, as well as information on required and optional parameters, HTTP status and error codes, and code samples you may use in your workflows.
 
 [#deprecated-endpoints]
 === Deprecated endpoints
diff --git a/docs/guides/modules/toolkit/pages/examples-and-guides-overview.adoc b/docs/guides/modules/toolkit/pages/examples-and-guides-overview.adoc
@@ -52,7 +52,7 @@ We have created demo applications in various languages so you can learn by examp
 [#platforms]
 == Platform guides
 
-Use the tutorial associated with your platform to learn about the customization that is possible in a xref:reference:ROOT:configuration-reference[`.circleci/config.yml`].
+Use the tutorial associated with your platform to learn about the customization that is possible in a xref:reference:ROOT:configuration-reference.adoc[`.circleci/config.yml`].
 
 [cols=2*, options="header"]
 |===
diff --git a/docs/reference/modules/ROOT/pages/configuration-reference.adoc b/docs/reference/modules/ROOT/pages/configuration-reference.adoc
@@ -1730,7 +1730,7 @@ During step execution, the templates above will be replaced by runtime values an
 
 While choosing suitable templates for your cache `key`, keep in mind the following:
 
-* Cache saving is not a free operation. See the billing section on the xref:server-admin:operator:faq.adoc#calculate-monthly-storage-and-network-costs[FAQ] page.
+* Cache saving is not a free operation. See the billing section on the xref:reference:ROOT:faq.adoc#calculate-monthly-storage-and-network-costs[FAQ] page.
 * It takes time to upload the cache.
 * Best practice is to have a `key` that generates a new cache only if something actually changed and avoid generating a new one every time a job is run.
 * Given the immutability of caches, it might be helpful to start all your cache keys with a version prefix `+v1-...+`. That way you will be able to regenerate all your caches just by incrementing the version in this prefix.
diff --git a/ui/src/partials/landing.hbs b/ui/src/partials/landing.hbs
@@ -200,7 +200,7 @@
           <a href="{{{relativize '/guides/integration/outbound-webhooks.html'}}}">Outbound webhooks</a>
         </li>
         <li>
-          <a href="{{{relativize '/api/v2.html'}}}">API v2 Reference</a>
+          <a href="{{{relativize '/api/v2/index.html'}}}">API v2 Reference</a>
         </li>
         <li>
           <a href="{{{relativize '/api/v1/index.html'}}}">API v1 Reference</a>

Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ The link:https://newrelic.com/instant-observability/circleci[New Relic CircleCI`
`13`	`13`
`14`	`14`	`Complete the following steps to set up a CircleCI webhook to forward your logs to New Relic. For more information, refer to the New Relic CircleCI link:https://docs.newrelic.com/docs/logs/forward-logs/circleci-logs/[installation docs].`
`15`	`15`
`16`		`-. Log in to the link:https://app.circleci.com/projects)[CircleCI web app].`
	`16`	`+. Log in to the link:https://app.circleci.com)[CircleCI web app].`
`17`	`17`
`18`	`18`	`. Access one of your CircleCI projects.`
`19`	`19`
`@@ -27,7 +27,7 @@ Complete the following steps to set up a CircleCI webhook to forward your logs t`
`27`	`27`	Webhook name**: give your webhook an identifiable name, for example, `New Relic CI Visibility`
`28`	`28`	` Receiver URL: Use New Relic's Logs endpoint**. Use the region you set for your New Relic account.`
`29`	`29`	`+`
`30`		-Replace `YOUR_LICENSE_KEY` with your New Relic license key, which you can link:https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#manage-license-key)[retrieve from the UI or API].
	`30`	+Replace `YOUR_LICENSE_KEY` with your New Relic license key, which you can link:https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#manage-license-key[retrieve from the UI or API].
`31`	`31`	`+`
`32`	`32`	US: `https://log-api.newrelic.com/log/v1?Api-Key=YOUR_LICENSE_KEY`
`33`	`33`	`+`