docs: disambiguate generic headings to prevent anchor collisions

[mihir-dixit2k27]

Description

Renames generic headings (like http_config, link_config) to include their context (e.g., (Shared), (PagerDuty)) to prevent URL anchor collisions.

Issue

Fixes #4725

Changes

• docs/configuration.md: Disambiguated shared and integration-specific headings.

[SoloJacobs]

It looks a bit off to me tbh, but works as intended I suppose:

Sadly, I haven't figured out a way to render the real documentation yet.

[mihir-dixit2k27]

Thanks for the reviews and approvals, @ultrotter and @SoloJacobs!

I agree it slightly changes the visual flow. The main goal here was to resolve the anchor collision issue in a minimal and consistent way so deep-linking works reliably across the page.

If there’s a preferred alternative formatting that achieves the same result, I’m happy to adjust. Otherwise, I’ll defer to your judgment.

[siavashs]

I think this is a simple approach to fix it.
The docs generator should handle these properly in the first place so maybe we can fix that later on.

Potentially we can fix this inprometheus/docs:

// Replace sequences of non-word characters with single dashes. Remove
// extra dashes at the beginning or end.
//
// Example: <http_config> => "http_config"
function generateAnchor(text: string) {
  return text.replace(/\W+/g, "-").replace(/^-+|-+$/g, "");
}

One option could be adding a unique random suffix to each anchor, then there will be no collisions.

[siavashs]

@mihir-dixit2k27 check my comment above about an alternative fix for this.

[mihir-dixit2k27]

Thanks for the approval and for the suggestion, @siavashs!

I agree that ideally this should be handled at the docs generator level, and improving anchor generation in prometheus/docs would be a cleaner long-term solution.

For this PR, I aimed to keep the change minimal and scoped to resolving the immediate anchor collision issue.

I’m happy to open a follow-up issue to explore improving the anchor generation logic separately.