Skip to content

Docs linter for app/views

Problem to solve

We link docs and its anchors from the GitLab UI through app/views/* and ee/app/views/* but we do not check them automatically, which can cause dead links and dead anchors when the UI links to docs.

Further details

  • For example, if in a given document in gitlab/doc/* we change a heading from ## Doing X to ## Do Y, the anchor will change from #doing-x to #do-y. If there's a link from app/views/* to #doing-x, the anchor will be dead.
  • If we change the location of a given document, we may be breaking the link from app/views/* and ee/app/views/*, besides all the anchors to that document.

What we do today is to do this manually when contributors remember to do so:

  • Search app/views/* and ee/app/views/* for the old anchor and replace it with the new one.
  • Do the same when changing documentation location. For this, we have a step in an MR description template, but it doesn't guarantee that this has been done all the times.

Examples of occurrence

app/views/admin/application_settings/_ci_cd.html.haml links to a file (help_page_path):

= link_to _('More information'), help_page_path('topics/autodevops/index.md'), target: '_blank'

app/views/admin/application_settings/_account_and_limit.html.haml links to a file (help_page_path) and anchor (anchor:):

= link_to _('More information'), help_page_path('user/permissions', anchor: 'external-users-permissions'), target: '_blank'

Notes

  • When changing anchors, besides affecting links internally, we also break links from blog posts, release posts, and from external resources (people do write a lot about GitLab in their own blogs, StackOverflow, and other forums).
  • When we "get rid of" /help (&693 (closed)), we can use Kramdown custom IDs to preserve anchors despite changing headings.

Proposal

  • Create a linter for checking app/views/* and ee/app/views/* for dead links.
  • Create a linter for checking app/views/* and ee/app/views/* for dead anchors.

Who can address the issue

Docs team + engs

Edited by Marcia Ramos