Search tags

The documentation includes a custom search scorer that can boost specific pages for particular search queries. Authors can control this by adding a search-tags directive to any RST page.

Usage

Place the directive anywhere in the page (typically near the top, after the title):

.. search-tags::
   :primary: mirror, mirrors
   :secondary: component, optic

Both options accept a comma-separated list of keywords:

primary:: Large score boost. Use this when the page is the main resource for a topic. For example, the mirror component page should have :primary: mirror, mirrors.
secondary:: Moderate score boost. Use this when the page is relevant but not the primary resource. For example, the Kat script syntax page could list many component names as secondary tags so that it appears in results but below the dedicated component pages.

Both options are optional — you can use just :primary: or just :secondary:.

The directive produces no visible output in the rendered page.

How it works

During the Sphinx build the search_tags extension (docs/source/_ext/search_tags.py) collects all tags and writes them to _static/search_tags.js.
The custom search scorer (_static/search_scores.js) reads this data and compares the user’s query against the tags.
Matching pages receive a score boost that pushes them higher in the search results.

Because the tags live inside the RST source files, they automatically follow the page when the documentation is restructured.

Tips

Keep the tags short, use single words or two-word phrases.
Include common spelling variants (e.g. mirror, mirrors).
Only add tags to pages that genuinely should be boosted because they are a good result for the keyword.