From 1c25ac1fb04c6347cb26914d110a1afe907527cf Mon Sep 17 00:00:00 2001
From: Julian Pawlowski <jpawlowski@users.noreply.github.com>
Date: Tue, 7 Apr 2026 14:01:37 +0000
Subject: [PATCH] feat(docs): improve Giscus comment UX for maintainer clarity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Switched Giscus mapping from 'pathname' to 'og:title' with strict=1.
Discussions are now titled after the readable page title (e.g.
'Chart Examples | Tibber Prices Integration') instead of the URL path,
making them immediately identifiable in the GitHub Discussions list.

Added a small hint above every comment box pointing users to open
a dedicated Discussion on GitHub for new questions/ideas, so
page-specific comments don't accumulate unrelated threads.

Note: Existing Discussion #94 (pathname-mapped) will no longer appear
on chart-examples — a new og:title-mapped discussion will be created
on the next comment. #94 remains visible on GitHub.

Impact: Maintainer can identify discussion origin at a glance.
Users are guided toward proper Discussion threads for new topics.
---
 docs/user/src/components/GiscusComponent.tsx |  4 ++--
 docs/user/src/theme/DocItem/Footer/index.tsx | 15 +++++++++++++++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/docs/user/src/components/GiscusComponent.tsx b/docs/user/src/components/GiscusComponent.tsx
index 41f8e18..f3a88a5 100644
--- a/docs/user/src/components/GiscusComponent.tsx
+++ b/docs/user/src/components/GiscusComponent.tsx
@@ -11,8 +11,8 @@ export default function GiscusComponent() {
       repoId="R_kgDOObwUag"
       category="General"
       categoryId="DIC_kwDOObwUas4CzVw_"
-      mapping="pathname"
-      strict="0"
+      mapping="og:title"
+      strict="1"
       reactionsEnabled="1"
       emitMetadata="0"
       inputPosition="top"
diff --git a/docs/user/src/theme/DocItem/Footer/index.tsx b/docs/user/src/theme/DocItem/Footer/index.tsx
index 1a3052f..0e36812 100644
--- a/docs/user/src/theme/DocItem/Footer/index.tsx
+++ b/docs/user/src/theme/DocItem/Footer/index.tsx
@@ -14,6 +14,21 @@ export default function DocItemFooterWrapper(props) {
       <DocItemFooter {...props} />
       {enableComments && (
         <div style={{ marginTop: '3rem' }}>
+          <p style={{
+            fontSize: '0.85rem',
+            color: 'var(--ifm-color-emphasis-600)',
+            marginBottom: '0.75rem',
+          }}>
+            💬 <strong>Comments are page-specific.</strong> For a new question or idea,{' '}
+            <a
+              href="https://github.com/jpawlowski/hass.tibber_prices/discussions/new/choose"
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              open a dedicated Discussion on GitHub
+            </a>{' '}
+            so it gets its own thread and proper visibility.
+          </p>
           <GiscusComponent />
         </div>
       )}