From 2b648d5d7c17a5f47a066d436a54a22df717a552 Mon Sep 17 00:00:00 2001
From: Frank Niessink <frank@niessink.com>
Date: Tue, 18 Feb 2025 16:45:41 +0100
Subject: [PATCH] Fix documentation links.

Links to documentation on Read the Docs for subjects, metrics, or sources with hyphens in their name wouldn't scroll to the right location.

Fixes #10843.
---
 components/frontend/src/utils.jsx      |  2 +-
 components/frontend/src/utils.test.jsx | 16 ++++++++++++++++
 docs/src/changelog.md                  |  6 ++++++
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/components/frontend/src/utils.jsx b/components/frontend/src/utils.jsx
index f730f7bee8..e509c82de3 100644
--- a/components/frontend/src/utils.jsx
+++ b/components/frontend/src/utils.jsx
@@ -421,7 +421,7 @@ export function dropdownOptions(options) {
 
 export function referenceDocumentationURL(name) {
     // Return a URL to the documentation for the metric/subject/source name
-    const slug = `${name?.toLowerCase().replaceAll(" ", "-").replaceAll(/[()/]/g, "")}`
+    const slug = `${name?.toLowerCase().replaceAll(" ", "-").replaceAll("_", "-").replaceAll(/[()/]/g, "")}`
     return `${DOCUMENTATION_URL}/reference.html#${slug}`
 }
 
diff --git a/components/frontend/src/utils.test.jsx b/components/frontend/src/utils.test.jsx
index 98ff1e62a0..a625459563 100644
--- a/components/frontend/src/utils.test.jsx
+++ b/components/frontend/src/utils.test.jsx
@@ -1,6 +1,7 @@
 import { EDIT_ENTITY_PERMISSION, EDIT_REPORT_PERMISSION } from "./context/Permissions"
 import { defaultDesiredResponseTimes } from "./defaults"
 import {
+    DOCUMENTATION_URL,
     addCounts,
     capitalize,
     getMetricResponseDeadline,
@@ -19,6 +20,7 @@ import {
     niceNumber,
     nrMetricsInReport,
     nrMetricsInReports,
+    referenceDocumentationURL,
     scaledNumber,
     sortWithLocaleCompare,
     sum,
@@ -514,3 +516,17 @@ it("returns whether a metric's measurement is outdated", () => {
     // A metric with an outdated measurement is outdated:
     expect(isMeasurementOutdated({ latest_measurement: { outdated: true } })).toBe(true)
 })
+
+it("returns the reference documentation URL", () => {
+    const url = `${DOCUMENTATION_URL}/reference.html`
+    // Simple name
+    expect(referenceDocumentationURL("name")).toBe(`${url}#name`)
+    // Name with spaces
+    expect(referenceDocumentationURL("name with space")).toBe(`${url}#name-with-space`)
+    // Name with underscores
+    expect(referenceDocumentationURL("name_with_underscore")).toBe(`${url}#name-with-underscore`)
+    // Name with brackets
+    expect(referenceDocumentationURL("(bracketed)")).toBe(`${url}#bracketed`)
+    // Name with forward slash
+    expect(referenceDocumentationURL("forward/slash")).toBe(`${url}#forwardslash`)
+})
diff --git a/docs/src/changelog.md b/docs/src/changelog.md
index 78e4617b2d..071a98eb40 100644
--- a/docs/src/changelog.md
+++ b/docs/src/changelog.md
@@ -12,6 +12,12 @@ If your currently installed *Quality-time* version is not the latest version, pl
 
 <!-- The line "## <square-bracket>Unreleased</square-bracket>" is replaced by the release/release.py script with the new release version and release date. -->
 
+### [Unreleased]
+
+### Fixed
+
+- Links to documentation on Read the Docs for subjects, metrics, or sources with hyphens in their name wouldn't scroll to the right location. Fixes [#10843](https://github.com/ICTU/quality-time/issues/10843).
+
 ## v5.25.0 - 2025-02-14
 
 ### Added