Multiple broken anchors

MikeMcC399 commented 8 months ago

Description

When I executed npm run build I expected no broken anchors to be reported.

URL of Issue(s)

https://docs.cypress.io/

Steps to replicate

git clone https://github.com/cypress-io/cypress-documentation
cd cypress-documentation
npm install
npm run build

Additional Information

PR https://github.com/cypress-io/cypress-documentation/pull/5601, merged on Jan 16, 2024, updated Docusaurus from ^2.4.1 to 3.1.1.
Broken anchor link checking is a new feature of docusaurus@3.1.0. This means the broken anchors were previously not detected.

Bad anchor links generally cause reader confusion, as they will typically call up the intended page and then display it at the wrong place, leaving the reader to search and / or scroll for the relevant information.

npm run build log (original state)

```text [INFO] Docusaurus found broken anchors! Please check the pages of your site in the list below, and make sure you don't reference any anchor that does not exist. Note: it's possible to ignore broken anchors with the 'onBrokenAnchors' Docusaurus configuration, and let the build pass. Exhaustive list of all broken anchors found: - Broken anchor on source page path = /api/commands/children: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/closest: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/contains: -> linking to /faq/questions/using-cypress-faq#How-do-I-get-an-element-s-text-contents -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/eq: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/filter: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/find: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/first: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/fixture: -> linking to /guides/references/configuration#Folders-Files - Broken anchor on source page path = /api/commands/focused: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/get: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/intercept: -> linking to /api/commands/intercept#staticResponse-lt-code-gtStaticResponselt-code-gt -> linking to /api/commands/intercept#routeHandler-lt-code-gtFunctionlt-code-gt -> linking to #Request-Response-Modification-with-routeHandler (resolved as: /api/commands/intercept#Request-Response-Modification-with-routeHandler) -> linking to #Aliasing-a-Route (resolved as: /api/commands/intercept#Aliasing-a-Route) -> linking to #aliasing-an-intercepted-route (resolved as: /api/commands/intercept#aliasing-an-intercepted-route) -> linking to #routeHandler-lt-code-gtstring-object-Function-StaticResponselt-code-gt (resolved as: /api/commands/intercept#routeHandler-lt-code-gtstring-object-Function-StaticResponselt-code-gt) -> linking to #Providing-a-stub-response-with-req-reply (resolved as: /api/commands/intercept#Providing-a-stub-response-with-req-reply) -> linking to #Ending-the-response-with-res-send (resolved as: /api/commands/intercept#Ending-the-response-with-res-send) -> linking to #staticResponse-lt-code-gtStaticResponselt-code-gt (resolved as: /api/commands/intercept#staticResponse-lt-code-gtStaticResponselt-code-gt) - Broken anchor on source page path = /api/commands/last: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/next: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/nextall: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/nextuntil: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/not: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/origin: -> linking to /guides/references/trade-offs#Multiple-tabs - Broken anchor on source page path = /api/commands/parent: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/parents: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/parentsuntil: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/prev: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/prevall: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/prevuntil: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/screenshot: -> linking to /guides/references/configuration#Folders-Files - Broken anchor on source page path = /api/commands/selectfile: -> linking to #Actions (resolved as: /api/commands/selectfile#Actions) - Broken anchor on source page path = /api/commands/shadow: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/siblings: -> linking to /guides/core-concepts/introduction-to-cypress#Default-Assertions - Broken anchor on source page path = /api/commands/spread: -> linking to /guides/references/changelog#0-5.9 - Broken anchor on source page path = /api/commands/spy: -> linking to /guides/references/changelog#0-20.0 - Broken anchor on source page path = /api/commands/stub: -> linking to /guides/references/changelog#0-20.0 - Broken anchor on source page path = /api/commands/url: -> linking to /guides/references/best-practices#Setting-a-global-baseUrl - Broken anchor on source page path = /api/commands/visit: -> linking to /guides/references/best-practices#Setting-a-global-baseUrl -> linking to /guides/references/changelog#0-3.3 - Broken anchor on source page path = /api/cypress-api/custom-commands: -> linking to /plugins#custom-commands - Broken anchor on source page path = /api/cypress-api/custom-queries: -> linking to /guides/tooling/typescript-support#Types-for-custom-commands -> linking to /plugins#custom-commands - Broken anchor on source page path = /api/cypress-api/env: -> linking to /guides/guides/environment-variables#Option-5-Plugins - Broken anchor on source page path = /api/cypress-api/require: -> linking to /api/commands/origin#Dependencies-Sharing-Code - Broken anchor on source page path = /api/plugins/preprocessors-api: -> linking to /guides/core-concepts/writing-and-organizing-tests#Test-files - Broken anchor on source page path = /api/table-of-contents: -> linking to /plugins#custom-commands - Broken anchor on source page path = /examples/recipes: -> linking to /plugins#authentication - Broken anchor on source page path = /faq/questions/cloud-faq: -> linking to /guides/continuous-integration/introduction#Examples - Broken anchor on source page path = /faq/questions/using-cypress-faq: -> linking to /guides/guides/web-security#Same-superdomain-per-test -> linking to /plugins#email -> linking to /guides/core-concepts/introduction-to-cypress#Commands-Are-Not-Promises -> linking to /plugins#preprocessors - Broken anchor on source page path = /guides/cloud/getting-started: -> linking to #Identification (resolved as: /guides/cloud/getting-started#Identification) - Broken anchor on source page path = /guides/cloud/integrations/source-control/github: -> linking to /faq/questions/cloud-faq#Im-working-at-a-restrictive-VPN-Which-subdomains-do-I-have-to-allow-on-my-VPN-for-Cypress-Cloud-to-work-properly - Broken anchor on source page path = /guides/cloud/integrations/source-control/gitlab: -> linking to #Commit-statuses (resolved as: /guides/cloud/integrations/source-control/gitlab#Commit-statuses) -> linking to /faq/questions/cloud-faq#Im-working-at-a-restrictive-VPN-Which-subdomains-do-I-have-to-allow-on-my-VPN-for-Cypress-Cloud-to-work-properly - Broken anchor on source page path = /guides/component-testing/angular/examples: -> linking to /guides/component-testing/angular/api#ComponentProperties - Broken anchor on source page path = /guides/core-concepts/cypress-app: -> linking to /guides/core-concepts/testing-types#What-is-End-to-end-Testing - Broken anchor on source page path = /guides/core-concepts/introduction-to-cypress: -> linking to /guides/core-concepts/variables-and-aliases#Routes - Broken anchor on source page path = /guides/core-concepts/retry-ability: -> linking to /guides/references/assertions#BDD-Assertions - Broken anchor on source page path = /guides/core-concepts/writing-and-organizing-tests: -> linking to /guides/references/configuration#Folders-Files -> linking to /guides/guides/environment-variables#Option-2-cypress-env-json -> linking to /guides/references/best-practices#Using-after-or-afterEach-hooks -> linking to /guides/references/configuration##Test-Configuration -> linking to /plugins#preprocessors - Broken anchor on source page path = /guides/end-to-end-testing/amazon-cognito-authentication: -> linking to /guides/end-to-end-testing/amazon-cognito-authentication#Login-with-cy-origin - Broken anchor on source page path = /guides/end-to-end-testing/auth0-authentication: -> linking to #Login-with-cy-origin (resolved as: /guides/end-to-end-testing/auth0-authentication#Login-with-cy-origin) - Broken anchor on source page path = /guides/end-to-end-testing/okta-authentication: -> linking to /guides/end-to-end-testing/okta-authentication#Login-with-cy-origin - Broken anchor on source page path = /guides/end-to-end-testing/protractor-to-cypress: -> linking to /guides/core-concepts/introduction-to-cypress#Commands-Are-Not-Promises -> linking to /guides/continuous-integration/introduction#CircleCI -> linking to /guides/references/best-practices#Having-tests-rely-on-the-state-of-previous-tests - Broken anchor on source page path = /guides/end-to-end-testing/social-authentication: -> linking to /guides/references/best-practices#Challenges-with-Social-Connection-Authentication - Broken anchor on source page path = /guides/guides/command-line: -> linking to #cypress-run-headless (resolved as: /guides/guides/command-line#cypress-run-headless) - Broken anchor on source page path = /guides/guides/cross-origin-testing: -> linking to /guides/guides/web-security#Different-superdomain-per-test-requires-cy-origin-command - Broken anchor on source page path = /guides/guides/module-api: -> linking to /guides/references/configuration#Configuration-file - Broken anchor on source page path = /guides/guides/test-retries: -> linking to /guides/references/experiments#Experimental-Retries - Broken anchor on source page path = /guides/overview/why-cypress: -> linking to /plugins#Visual%20Testing - Broken anchor on source page path = /guides/references/assertions: -> linking to /faq/questions/using-cypress-faq#How-do-I-get-an-element-s-text-contents - Broken anchor on source page path = /guides/references/best-practices: -> linking to /plugins#email - Broken anchor on source page path = /guides/references/changelog: -> linking to /guides/references/changelog#13.6.2 -> linking to #13.3.3 (resolved as: /guides/references/changelog#13.3.3) -> linking to /guides/references/experiments/#Experimental-Flake-Detection-Features -> linking to #13.3.2 (resolved as: /guides/references/changelog#13.3.2) -> linking to /guides/references/migration-guide#test-isolation -> linking to /guides/references/migration-guide#Migrating-to-Cypress-version-11-0 -> linking to /guides/references/migration-guide#React-mountHook-Removed -> linking to /guides/references/migration-guide#React-unmount-Removed -> linking to /guides/references/migration-guide#Vue-mountCallback-Removed -> linking to /guides/references/migration-guide#Vite-Dev-Server-cypress-vite-dev-server -> linking to /guides/references/migration-guide#Angular-Providers-Mounting-Options-Change -> linking to /api/commands/origin#Dependencies-Sharing-Code -> linking to #10.0.0 (resolved as: /guides/references/changelog#10.0.0) -> linking to #10.4.0 (resolved as: /guides/references/changelog#10.4.0) -> linking to /guides/getting-started/installing-cypress#Install-pre-release-version -> linking to /guides/getting-started/installing-cypress#Install-binary -> linking to /guides/getting-started/installing-cypress#Using-a-custom-CA -> linking to /guides/references/configuration#Node-version -> linking to /guides/references/migration-guide#Migrating-cy-route-to-cy-intercept -> linking to #5-8-0 (resolved as: /guides/references/changelog#5-8-0) -> linking to /guides/core-concepts/writing-and-organizing-tests#Run-filtered-specs -> linking to /guides/core-concepts/writing-and-organizing-tests#test-configuration -> linking to /guides/references/experiments#Shadow-DOM -> linking to /guides/guides/command-line#cypress-run-headless -> linking to /guides/references/configuration#Folders-Files -> linking to /guides/guides/debugging#Patch-Cypress -> linking to /guides/tooling/typescript-support#Types-for-custom-commands -> linking to /guides/guides/debugging#Hacking-on-Cypress -> linking to /guides/getting-started/installing-cypress#Opt-out-of-sending-exception-data-to-Cypress -> linking to /guides/getting-started/installing-cypress#Download-URLs -> linking to /guides/guides/module-api#cypress-run -> linking to /guides/getting-started/installing-cypress#Mirroring -> linking to /guides/getting-started/installing-cypress#Advanced -> linking to /guides/references/configuration#Cypress-config -> linking to /guides/getting-started/installing-cypress#Skipping-installation -> linking to /examples/recipes#Form-Interactions -> linking to /guides/references/assertions#TDD-Assertions -> linking to /guides/references/bundled-libraries#Sinon-JS -> linking to /guides/core-concepts/writing-and-organizing-tests#Folder-Structure -> linking to #01711-11162016 (resolved as: /guides/references/changelog#01711-11162016) -> linking to #3.0.0 (resolved as: /guides/references/changelog#3.0.0) -> linking to /api/cypress-api/cookies#Defaults -> linking to /guides/references/configuration#Animations - Broken anchor on source page path = /guides/references/configuration: -> linking to /guides/references/migration-guide#Migrating-to-Cypress-version-10-0 -> linking to /guides/guides/environment-variables#Option-2-cypress-env-json -> linking to /guides/guides/environment-variables#Option-3-CYPRESS - Broken anchor on source page path = /guides/references/error-messages: -> linking to /guides/references/configuration#Folders-Files -> linking to /guides/guides/command-line/#auto-cancel-after-runs -> linking to /guides/continuous-integration/introduction#Examples - Broken anchor on source page path = /guides/references/legacy-configuration: -> linking to /guides/guides/command-line#cypress-open-config-file-lt-config-file-gt -> linking to /guides/references/configuration#Folders-Files -> linking to /guides/guides/environment-variables#Option-2-cypress-env-json -> linking to /guides/guides/environment-variables#Option-3-CYPRESS - Broken anchor on source page path = /guides/references/migration-guide: -> linking to /guides/references/best-practices#Having-tests-rely-on-the-state-of-previous-tests -> linking to #Plugins-file-removed (resolved as: /guides/references/migration-guide#Plugins-file-removed) -> linking to /guides/references/configuration#Folders-Files -> linking to /api/commands/intercept#intercepted-response -> linking to /guides/references/migration-guide##2-Install-component-testing-dependencies -> linking to /guides/references/migration-guide#3-Update-plugins-file-to-use-dev-server-start - Broken anchor on source page path = /guides/tooling/code-coverage: -> linking to /guides/references/configuration#Folders-Files - Broken anchor on source page path = /guides/tooling/IDE-integration: -> linking to /guides/core-concepts/writing-and-organizing-tests#Folder-Structure - Broken anchor on source page path = /guides/tooling/plugins-guide: -> linking to /guides/guides/environment-variables#Option-2-cypress-env-json - Broken anchor on source page path = /guides/tooling/typescript-support: -> linking to /guides/core-concepts/writing-and-organizing-tests#Folder-Structure -> linking to /guides/references/configuration#Folders-Files - Broken anchor on source page path = /guides/tooling/visual-testing: -> linking to /plugins#visual-testing ```

jennifer-shehane commented 7 months ago

We'd accept a PR to fix this

MikeMcC399 commented 7 months ago

@jennifer-shehane

We'd accept a PR to fix this

I'll make a start on this. For ease of reviewing I will submit multiple PRs.

There are also false positives in the list, which will need looking at to see if they can be avoided.

MikeMcC399 commented 7 months ago

All broken anchor links have now been fixed. Thanks to @jennifer-shehane for her patience in merging all the related PRs! 🙂 The errors in anchor links had built up over the years and there was no automatic checking in place until Docusaurus added this functionality recently.

The final npm run build log shows only false positive errors. See https://app.circleci.com/pipelines/github/cypress-io/cypress-documentation/24781/workflows/b04b3717-0762-45f6-9288-dd5b04018435/jobs/62341 > Docs build

> cypress-docusaurus-ts@0.0.0 prebuild
> rm -rf dist && npm run build:plugins

> cypress-docusaurus-ts@0.0.0 build:plugins
> npm --prefix ./plugins/cypressRemarkPlugins run build

> tstojs@1.0.0 prebuild
> rm -rf ./dist

> tstojs@1.0.0 build
> tsc

> cypress-docusaurus-ts@0.0.0 build
> docusaurus build --out-dir dist

[INFO] [en] Creating an optimized production build...
[info] [webpackbar] Compiling Client
[info] [webpackbar] Compiling Server
[success] [webpackbar] Client: Compiled successfully in 1.52m
[success] [webpackbar] Server: Compiled successfully in 1.97m
[INFO] Docusaurus found broken anchors!

Please check the pages of your site in the list below, and make sure you don't reference any anchor that does not exist.
Note: it's possible to ignore broken anchors with the 'onBrokenAnchors' Docusaurus configuration, and let the build pass.

Exhaustive list of all broken anchors found:
- Broken anchor on source page path = /api/cypress-api/custom-commands:
   -> linking to /plugins#custom-commands
- Broken anchor on source page path = /api/cypress-api/custom-queries:
   -> linking to /plugins#custom-commands
- Broken anchor on source page path = /api/table-of-contents:
   -> linking to /plugins#custom-commands
- Broken anchor on source page path = /examples/recipes:
   -> linking to /plugins#authentication
- Broken anchor on source page path = /faq/questions/using-cypress-faq:
   -> linking to /plugins#email
   -> linking to /plugins#preprocessors
- Broken anchor on source page path = /guides/core-concepts/writing-and-organizing-tests:
   -> linking to /plugins#preprocessors
- Broken anchor on source page path = /guides/overview/why-cypress:
   -> linking to /plugins#visual-testing
- Broken anchor on source page path = /guides/references/best-practices:
   -> linking to /plugins#email
- Broken anchor on source page path = /guides/tooling/visual-testing:
   -> linking to /plugins#visual-testing

[SUCCESS] Generated static files in "dist".
[INFO] Use `npm run serve` command to test your build locally.

MikeMcC399 commented 7 months ago

The remaining false positive broken anchor link reports (see above https://github.com/cypress-io/cypress-documentation/issues/5630#issuecomment-1964250967) are transferred to a new issue #5720

jennifer-shehane commented 7 months ago

@MikeMcC399 Thank you! That was a lot of fixes.

MikeMcC399 commented 7 months ago

@jennifer-shehane

Thank you! That was a lot of fixes.

You're welcome! 🙂

cypress-io / cypress-documentation