diff --git a/docs/customization.rst b/docs/customization.rst index 0dc72b84..12996591 100644 --- a/docs/customization.rst +++ b/docs/customization.rst @@ -107,6 +107,39 @@ Each metadata is evaluated as a :rst:`:key: value` pair. .. seealso:: Using comments requires extra steps. See `Adding a comment system`_ instructions. + +.. themeconf:: search-boost + + If specified, boosts the current page's search index entries by a factor given. + Without specifying this, all search entries are ranked at a boost factor of 1. + + .. md-tab-set:: + + .. md-tab-item:: :si-icon:`material/arrow-up-circle` Rank up + + .. code-block:: rst + + :search-boost: 1 + + .. md-tab-item:: :si-icon:`material/arrow-down-circle` Rank down + + .. code-block:: rst + + :search-boost: 0.5 + + .. seealso:: + Review advice from `mkdocs-material theme's search boost metadata + `_. + +.. themeconf:: search-exclude + + If specified, excludes the current page from the search index. + + .. code-block:: rst + :caption: Exclude current page from search index + + :search-exclude: + Configuration Options ===================== diff --git a/sphinx_immaterial/search.py b/sphinx_immaterial/search.py index ed697d6a..f8aff65f 100644 --- a/sphinx_immaterial/search.py +++ b/sphinx_immaterial/search.py @@ -2,6 +2,7 @@ import multiprocessing import pathlib +from typing import Dict, Any, cast import docutils.nodes import jinja2.sandbox @@ -69,15 +70,25 @@ def _html_page_context( if content is None: # Special page like `genindex`, exclude from search index. return + + page_meta: Dict[str, str] = context.get("meta") or {} + meta: Dict[str, Any] = {"tags": []} + # TODO: When tags are supported, they need to be appended to `meta["tags"]` + if "search-exclude" in page_meta: + meta["exclude"] = True + if "search-boost" in page_meta: + meta["boost"] = page_meta["search-boost"] + indexer = _make_indexer(app) url = app.builder.get_target_uri(pagename) + page_ctx = cast(Dict[str, Any], context.get("page")) indexer.add_entry_from_context( _Page( content=content, - title=context["page"]["title"], - meta={}, + title=page_ctx["title"], + meta={"search": meta}, url=url, - toc=context["page"]["toc"], + toc=page_ctx["toc"], ) ) queue = getattr(app, _SEARCH_QUEUE_KEY)