From 5566728ba3c4b06474e9cc6f07cbf2767c4224a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Tue, 10 Nov 2026 16:25:40 +0000 Subject: [PATCH] docs: rank Self-hosted pages lower in search and label them Self-hosted pages often share a Cloud page's title, so searching "slack integration" put the Self-hosted page first. A build hook now sets search.boost 0.5 on every page under chart/, and a CSS rule adds a "Self-hosted" chip to search results that link to chart/ pages. Co-Authored-By: Claude Opus 5.5 --- mkdocs.yml | 2 ++ theme/hooks/search_boost.py | 22 ++++++++++++++++++++++ theme/stylesheets/header.css | 2 ++ 3 files changed, 26 insertions(+) create mode 100644 theme/hooks/search_boost.py diff --git a/mkdocs.yml b/mkdocs.yml index 481ced753b..d35e0d2a84 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,6 +62,8 @@ extra_javascript: # Reserve image space and defer below-the-fold screenshots without a frontend build step. hooks: - "theme/hooks/image_metadata.py" + # Rank Self-hosted pages (docs/chart/) below Cloud pages in search results. + - "theme/hooks/search_boost.py" # Extra variables # https://github.com/rosscdh/mkdocs-markdownextradata-plugin diff --git a/theme/hooks/search_boost.py b/theme/hooks/search_boost.py new file mode 100644 index 0000000000..457ad00a0b --- /dev/null +++ b/theme/hooks/search_boost.py @@ -0,0 +1,22 @@ +"""Rank Codacy Self-hosted pages below Cloud pages in site search. + +Most readers are on Codacy Cloud, but Self-hosted pages often share a Cloud +page's title (for example, "Slack integration"), so they can outrank the page +the reader needs. Material's search plugin reads a per-page boost from +`search.boost` in the page metadata; this sets it for every page under +`chart/` (the Self-hosted section) instead of repeating it in each page's +front matter. A page that sets its own `search.boost` keeps it. +""" + +from __future__ import annotations + +SELF_HOSTED_PREFIX = "chart/" +SELF_HOSTED_BOOST = 0.5 + + +def on_page_markdown(markdown, page, **kwargs): + if page.file.src_uri.startswith(SELF_HOSTED_PREFIX): + search = page.meta.get("search") or {} + search.setdefault("boost", SELF_HOSTED_BOOST) + page.meta["search"] = search + return markdown diff --git a/theme/stylesheets/header.css b/theme/stylesheets/header.css index 1806ecd570..0fc408780c 100644 --- a/theme/stylesheets/header.css +++ b/theme/stylesheets/header.css @@ -85,6 +85,8 @@ body[data-md-color-scheme="codacy-dark"] [data-md-component="palette"] .docs-pal .md-search .md-search-result__link { display: block; color: inherit; border-radius: inherit; } .md-search .md-search-result__article { min-height: 0; padding: .62rem .75rem; } .md-search .md-search-result__article h1, .md-search .md-search-result__article h2 { margin: 0; color: var(--docs-text); font-size: .86rem; font-weight: 600; line-height: 1.4; } +/* Self-hosted pages all live under /chart/; label them so Cloud readers can tell them apart from Cloud pages with similar titles. */ +.md-search .md-search-result__link[href*="/chart/"] .md-search-result__article h1::after { content: "Self-hosted"; display: inline-block; margin-left: .4rem; padding: 0 .35rem; border: 1px solid var(--docs-border); border-radius: var(--docs-radius); background: var(--docs-bg-subtle); color: var(--docs-text-secondary); font-size: .62rem; font-weight: 500; line-height: 1.5; vertical-align: .1em; } .md-search .md-search-result__article > p { display: none; } .md-search .md-search-result__article > h1 + p, .md-search .md-search-result__article > h2 + p { display: -webkit-box; margin: .3rem 0 0; overflow: hidden; color: var(--docs-text-tertiary); font-size: .72rem; line-height: 1.5; -webkit-box-orient: vertical; -webkit-line-clamp: 2; } .md-search .md-search-result__article > ul, .md-search .md-search-result__article > ol { display: none; }