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.

Summary by CodeRabbit

• Documentation
  • Updated configuration documentation with contextual qualifiers to clarify sharing scope and integration-specific settings, making it easier to identify relevant configuration sections.

[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.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6a7c0cb5-9550-4cad-86d0-aa0aa43c42ce

📥 Commits

Reviewing files that changed from the base of the PR and between 35cbf8d and 3b6e7bb.

📒 Files selected for processing (1)

• docs/configuration.md

---

📝 Walkthrough

Walkthrough

Documentation headers updated in configuration.md to include contextual qualifiers like "(Shared)", "(PagerDuty)", "(Slack)", and "(SNS)" to differentiate integration-specific configuration sections and resolve potential anchor link naming conflicts.

Changes

Cohort / File(s)	Summary
Documentation Header Disambiguation docs/configuration.md	Added integration-specific and scope qualifiers to section headers to prevent anchor link conflicts and clarify which configurations apply to specific services or shared contexts.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 Through docs we hop with careful care,
Adding names to headers fair,
No conflicts now will cause dismay,
Just clearer links to light the way! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: disambiguating generic headings to prevent anchor collisions in documentation.
Description check	✅ Passed	The description adequately explains the purpose, references the linked issue #4725, and summarizes the changes made to docs/configuration.md.
Linked Issues check	✅ Passed	The PR directly addresses issue #4725 by disambiguating generic heading names like 'http_config' and 'link_config' with contextual qualifiers to prevent anchor collisions.
Out of Scope Changes check	✅ Passed	All changes are scoped to documentation updates in docs/configuration.md to resolve anchor collision issues, with no unrelated code modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

📝 Coding Plan

• Generate coding plan for human review comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

You can validate your CodeRabbit configuration file in your editor.

If your editor has YAML language server, you can enable auto-completion and validation by adding # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json at the top of your CodeRabbit configuration file.