Skip to content

Simplify internal anchors error presentation

Achilleas Pipinellis requested to merge axil-simplify-internal-anchor-errors into main

What does this MR do and why?

I've been working on splitting some pages, and I've been using the internal anchor test a lot to fix the errors. My eyes hurt each time I look at the job log.

I tried to simplify the error by removing the anchor since it's anyway reported again in the destination output, which I changed to read anchor link. I believe the output is a bit clearer now.

A continuation of #1723.

Screenshots, screen recordings, or links to review app

Before

Issues found!
  (global):
    [ ERROR ] internal_anchors - Broken anchor detected: `#message-error-canceling-statement-due-to-conflict-with-recovery`
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/geo/index.html`
      - destination `replication/troubleshooting/index.html#message-error-canceling-statement-due-to-conflict-with-recovery`
    [ ERROR ] internal_anchors - Broken anchor detected: `#message-log--invalid-cidr-mask-in-address`
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/postgresql/pgbouncer.html`
      - destination `../geo/replication/troubleshooting/index.html#message-log--invalid-cidr-mask-in-address`
    [ ERROR ] internal_anchors - Broken anchor detected: `#message-log--invalid-ip-mask-md5-name-or-service-not-known`
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/postgresql/pgbouncer.html`
      - destination `../geo/replication/troubleshooting/index.html#message-log--invalid-ip-mask-md5-name-or-service-not-known`
    [ ERROR ] internal_anchors - Broken anchor detected: `#resync-and-reverify-individual-components`
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/troubleshooting/gitlab_rails_cheat_sheet.html`
      - destination `../geo/replication/troubleshooting/index.html#resync-and-reverify-individual-components`
    [ ERROR ] internal_anchors - Broken anchor detected: `#fixing-postgresql-database-replication-errors`
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/troubleshooting/postgresql.html`
      - destination `../geo/replication/troubleshooting/index.html#fixing-postgresql-database-replication-errors`

After

Issues found!
  (global):
    [ ERROR ] internal_anchors - Broken anchor detected:
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/geo/index.html`
      - anchor link `replication/troubleshooting/index.html#message-error-canceling-statement-due-to-conflict-with-recovery`
    [ ERROR ] internal_anchors - Broken anchor detected:
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/postgresql/pgbouncer.html`
      - anchor link `../geo/replication/troubleshooting/index.html#message-log--invalid-cidr-mask-in-address`
    [ ERROR ] internal_anchors - Broken anchor detected:
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/postgresql/pgbouncer.html`
      - anchor link `../geo/replication/troubleshooting/index.html#message-log--invalid-ip-mask-md5-name-or-service-not-known`
    [ ERROR ] internal_anchors - Broken anchor detected:
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/troubleshooting/gitlab_rails_cheat_sheet.html`
      - anchor link `../geo/replication/troubleshooting/index.html#resync-and-reverify-individual-components`
    [ ERROR ] internal_anchors - Broken anchor detected:
      - source file `/Users/axil/devel/gitlab/gdk/gitlab-docs/public/ee/administration/troubleshooting/postgresql.html`
      - anchor link `../geo/replication/troubleshooting/index.html#fixing-postgresql-database-replication-errors`

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

  1. Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md.
  2. Check out this branch.
  3. Edit a doc page that contains an anchor link and remove a character from that anchor link.
  4. Run the check and see it fail:
    bundle exec nanoc check internal_anchors

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Achilleas Pipinellis

Merge request reports