Enable check-anchors

[jonathanlukas]

Description

This PR enables the check-anchors option

closes #3433

When should this change go live?

• This change is not yet live and should not be merged until {ADD_DATE} (apply hold label or convert to draft PR)?
• There is no urgency with this change.
• This change or page is part of a marketing blog, conference talk, or something else on a schedule.
• This functionality is already available but undocumented.
• This is a bug fix or security concern.

PR Checklist

• I have added changes to the relevant /versioned_docs directory, or they are not for an already released version.
• I have added changes to the main /docs directory (aka /next/), or they are not for future versions.
• My changes require an Engineering review, and I've assigned an engineering manager or tech lead as a reviewer, or my changes do not require an Engineering review.
• My changes require a technical writer review, and I've assigned @christinaausley as a reviewer, or my changes do not require a technical writer review.

[akeller]

I'm doing a timeboxed investigation here for the anchor link errors.

This PR only adjusts the GHA, not the local build.

Tabs are not linkable as headings

Error: bad anchors:
docs/self-managed/zeebe-deployment/exporters/elasticsearch-exporter#authentication
docs/self-managed/zeebe-deployment/exporters/elasticsearch-exporter#bulk
docs/self-managed/zeebe-deployment/exporters/elasticsearch-exporter#index
docs/self-managed/zeebe-deployment/exporters/elasticsearch-exporter#retention

Some are due to converting sectioned content into tabbed content. Docusaurus tabs do a good job of presenting tabbed content; however, "This feature does not provide an anchor link - the browser will not scroll to the tab." In this case, I would choose to remove them and add text to refer to the table immediately below.

Headers renamed (examples - setup vs set-up, drop "platform")

Error: bad anchors:
optimize/self-managed/optimize-deployment/plugins/plugin-system#setup-your-environment

There are about 65 instances of this example alone (setup vs. set-up).

I have #3445 in draft addressing some of the points above, but I need to pivot to other time sensitive and critical work. If I have more time today I'll revisit.

[akeller]

FYI @christinaausley ☝️ see my comment above. When we do renaming and restructuring, we'll need to consider the anchor links as well. Once this check is enabled in our build process, it will be easier to see.

[akeller]

@conceptualshark have you run into any issues with anchors as you are working through Self-Managed docs? I'm trying to decide what to do with this PR.

[conceptualshark]

@akeller There's no small amount of them, mostly relating to linking to or between tabbed content. Would you like me to break out a task to address anchors throughout SM, similar to how the others sections have been approached?

[conceptualshark]

If tackling the amount of broken anchor links is too much to account for right now, we could always include this as a manual workflow to check before a release (as with external links). After a few rounds of this, we could implement --check-anchors into the automated workflows when there's fewer errors (and resolving them is more routine).

[akeller]

@akeller There's no small amount of them, mostly relating to linking to or between tabbed content. Would you like me to break out a task to address anchors throughout SM, similar to how the others sections have been approached?

Yes, basically approach this with "best effort" for your area so we can keep discussing as a team how we want to handle tabs.

[christinaausley]

Perhaps we should bring this to a tech writers sync or team meeting? CC @camunda/tech-writers