ros2 · 3di-techx · Apr 27, 2026 · Apr 27, 2026 · May 1, 2026 · May 4, 2026
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -78,6 +78,15 @@ jobs:
       - name: Build the docs
         run: make html
 
+
+      - name: Setup Node.js (Pagefind)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Index HTML with Pagefind
+        run: make pagefind
+
       - name: Upload document artifacts
         uses: actions/upload-artifact@v4
         id: artifact-upload-step
@@ -147,3 +156,12 @@ jobs:
 
       - name: Build the docs
         run: make multiversion
+
+
+      - name: Setup Node.js (Pagefind)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Index HTML with Pagefind
+        run: make pagefind
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,7 @@ _build/
 __pycache__
 ros2doc/
 .DS_Store
+
+# Downloaded at HTML build time for browser-side package lists (large).
+source/_static/rosdistro_cache/*.yaml.gz
+.env
diff --git a/Makefile b/Makefile
@@ -23,9 +23,26 @@ multiversion: Makefile
 	@echo "<html><head><meta http-equiv=\"refresh\" content=\"0; url=lyrical/index.html\" /></head></html>" > build/html/index.html
 	$(PYTHON) make_sitemapindex.py
 
+# Pagefind static search index (requires Node.js / npx). Run after html or multiversion.
+PAGEFIND_VERSION ?= 1.5.2
+pagefind:
+	npx -y pagefind@$(PAGEFIND_VERSION) --site "$(OUT)/html"
+
+
+# Convenience: Sphinx build + Pagefind index (does not replace plain html / multiversion).
+html-search:
+	$(MAKE) html
+	$(MAKE) pagefind
+
+multiversion-search: multiversion
+	$(MAKE) pagefind	
+
 %: Makefile
 	@$(BUILD) -M $@ "$(SOURCE)" "$(OUT)" $(OPTS)
 
+enhance:
+	git diff --name-only --diff-filter=d HEAD | xargs -r $(PYTHON) tools/enhance_topics.py
+
 lint:
 	./sphinx-lint-with-ros source
 
@@ -66,4 +83,4 @@ linkcheck:
 serve:
 	sphinx-autobuild --host $(LIVE_HOST) --port $(LIVE_PORT) -c . $(SOURCE) $(OUT)/html
 
-.PHONY: help Makefile multiversion test test-tools linkcheck serve lint spellcheck check-dictionaries sort-dictionaries
+.PHONY: help Makefile multiversion pagefind test test-tools linkcheck serve lint spellcheck check-dictionaries sort-dictionaries
diff --git a/README.md b/README.md
@@ -92,6 +92,24 @@ To test building the multisite version deployed to the website use:
 
 **NB:** This will ignore local workspace changes and build from the branches.
 
+### Pagefind search index
+
+After `make html` or `make multiversion`, run [Pagefind](https://pagefind.app/) so the built HTML under `build/html` is indexed and `build/html/pagefind/` is written (search bundle and Component UI assets). From the repo root:
+
+`make pagefind`
+
+Or use convenience targets that run Sphinx and Pagefind in one step:
+
+- `make html-search` — `make html` then `make pagefind`
+- `make multiversion-search` — `make multiversion` then `make pagefind`
+
+Plain `make html` and `make multiversion` do **not** run Pagefind (Node.js is only required when you index search).
+
+This requires **Node.js** (for `npx`). Pin the CLI with `PAGEFIND_VERSION` in the Makefile if needed.
+
+The production [Jenkins doc job](https://build.ros.org/job/doc_ros2doc) should run the same `pagefind` step on `build/html` after Sphinx so deployed pages include the search bundle.
+
+
 ### Note for Windows (WSL) Users
 
 When building the documentation on windows using WSL, it is recommended to clone and work with this repository inside the Linux filesystem (for example, under `/home/<user>/`) rather than under `/mnt/c`.

diff --git a/conf.py b/conf.py
@@ -89,8 +89,41 @@
     'sphinx_adopters',
     'sphinxcontrib.googleanalytics',
     'sphinxcontrib.mermaid',
+    'ros_related_packages',
+    'ros_related_articles',
+    'short_description',
+    'pagefind_meta',
+    'showmeta',
 ]
 
+# pagefind search index configuration.
+
+pagefind_merge_enabled = False
+pagefind_merge_package_pkgs = []
+pagefind_merge_index_base = 'https://docs.ros.org'
+pagefind_merge_index_overrides = {}
+pagefind_merge_filter_per_pkg = None
+pagefind_merge_index_weight_per_pkg = None
+
+# Pagefind search UI (modal + /search.html): result metadata lines and facet sidebar.
+# Dict keys = .. meta:: field names; values = display labels.
+# Order here is facet dropdown order and result-meta line order (allowlist).
+# Only listed keys are indexed as facets; keys must exist on at least one page in the build.
+# Other meta (e.g. description, keywords) stays SEO-only and does not appear in the facet sidebar.
+
+pagefind_result_meta_order = {
+    'product': 'Product',
+    'distribution': 'Distribution',
+    'area': 'Area',
+    'capability': 'Capability',
+    'community': 'Community',
+    'installation': 'Installation',
+    'framework': 'Framework',
+    'tool': 'Tools',
+    'contentType': 'Content type',
+    'experience': 'Level',
+}
+
 # Intersphinx mapping
 
 intersphinx_mapping = {
@@ -192,6 +225,7 @@
     'DISTRO_UBUNTU_DEB_PLATFORM': distro_ubuntu_deb_platform['rolling'],
     'DISTRO_ARM_STATUS_SUFFIX': distro_arm_status_suffix.get('rolling', 'unv8'),
     'REPOS_FILE_BRANCH': 'rolling',
+    'PRODUCT': 'ROS 2',
 }
 
 html_favicon = 'favicon.ico'
@@ -205,8 +239,52 @@
 html_sourcelink_suffix = ''
 
 # Relative to html_static_path
-html_css_files = ['custom.css', 'adopters.css']
-html_js_files = ['adopters.js']
+html_css_files = ['custom.css', 'adopters.css', 'pagefind-docsearch.css']
+html_js_files = [
+    ('vendor/pako.min.js', {'defer': ''}),
+    ('vendor/js-yaml.min.js', {'defer': ''}),
+    'adopters.js',
+    'related_packages.js',
+]
+
+# Runtime proxy endpoint for freshest rosdistro cache data (same-origin).
+# Default matches production: /api/rosdistro-cache/{distro}-cache.yaml.gz
+# Override with ROS_RELATED_PACKAGES_PROXY_URL; set to empty string to disable
+# proxy and use bundled _static fallback only.
+# Local testing: python tools/serve_docs_with_proxy.py (serves build/html + /api/).
+def _normalize_ros_related_packages_proxy_url(raw: str) -> str:
+    """Return a browser-safe proxy template.
+
+    On Windows, GNU make / MSYS (common even when the terminal is PowerShell) can
+    rewrite ``/api/...`` into ``C:/Program Files/Git/api/...``. Recover the
+    intended same-origin path when that happens.
+    """
+    value = (raw or '').strip()
+    if not value:
+        return ''
+
+    normalized = value.replace('\\', '/')
+    marker = '/api/rosdistro-cache/'
+    idx = normalized.find(marker)
+    if idx != -1:
+        return normalized[idx:]
+
+    if normalized.startswith('api/rosdistro-cache/'):
+        return '/' + normalized
+
+    return value
+
+
+_DEFAULT_ROS_RELATED_PACKAGES_PROXY_URL = (
+    '/api/rosdistro-cache/{distro}-cache.yaml.gz'
+)
+
+ros_related_packages_proxy_url = _normalize_ros_related_packages_proxy_url(
+    os.environ.get(
+        'ROS_RELATED_PACKAGES_PROXY_URL',
+        _DEFAULT_ROS_RELATED_PACKAGES_PROXY_URL,
+    )
+)
 
 # -- Options for HTMLHelp output ------------------------------------------
 

diff --git a/constraints.txt b/constraints.txt
@@ -11,11 +11,13 @@ imagesize==1.4.1
 iniconfig==2.1.0
 Jinja2==3.1.6
 MarkupSafe==3.0.3
+openai==2.33.0
 packaging==25.0
 pluggy==1.6.0
 polib==1.2.0
 Pygments==2.19.2
 pytest==8.4.2
+python-dotenv==1.1.0
 PyYAML==6.0.3
 regex==2025.9.18
 requests==2.32.5
@@ -39,4 +41,6 @@ sphinxcontrib-mermaid==1.0.0
 sphinxcontrib-qthelp==2.0.0
 sphinxcontrib-serializinghtml==2.0.0
 stevedore==5.5.0
+tenacity==9.1.4
+timeout-decorator==0.5.0
 urllib3==2.5.0
diff --git a/plugins/meta_util.py b/plugins/meta_util.py
@@ -0,0 +1,70 @@
+# Copyright 2026 Open Robotics — shared helpers for ``.. meta::`` / Pagefind
+"""
+Collect every ``.. meta::`` field from the doctree, sanitize keys, and expand
+``{MACRO}`` placeholders using the Sphinx ``macros`` config (longest keys first).
+
+Sphinx / the HTML theme may also emit plain ``<meta>`` tags for the same fields.
+The Pagefind extension emits additional tags with ``data-pagefind-filter`` and may
+split comma-separated values into multiple tags for faceted search.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional
+
+from docutils import nodes
+
+# HTML ``<meta name="...">`` names should be conservative; allow common patterns.
+_META_NAME_RE = re.compile(r'^[A-Za-z0-9_.:-]+$')
+
+
+def sanitize_meta_key(raw: str) -> Optional[str]:
+    s = str(raw).strip()
+    if not s or not _META_NAME_RE.match(s):
+        return None
+    return s
+
+
+def all_doctree_meta(doctree: Optional[nodes.document]) -> Dict[str, str]:
+    """Return last-wins mapping of every ``nodes.meta`` ``name``/``property`` → ``content``."""
+    if doctree is None:
+        return {}
+
+    out: Dict[str, str] = {}
+    for meta in doctree.findall(nodes.meta):
+        if meta.get('http-equiv'):
+            continue
+        content = meta.get('content')
+        if not content:
+            continue
+        key: Optional[str] = None
+        name = meta.get('name')
+        if name:
+            key = sanitize_meta_key(str(name))
+        else:
+            prop = meta.get('property')
+            if prop:
+                key = sanitize_meta_key(str(prop))
+        if not key:
+            continue
+        out[key] = str(content).strip()
+    return out
+
+
+def expand_meta_macros(text: str, macros: Dict[str, str]) -> str:
+    """Expand ``{KEY}`` placeholders; longer macro names first to avoid partial matches."""
+    result = text
+    for key, value in sorted(macros.items(), key=lambda kv: len(kv[0]), reverse=True):
+        result = result.replace(f'{{{key}}}', value)
+    return result
+
+
+def expand_all_meta_values(meta: Dict[str, str], macros: Dict[str, str]) -> Dict[str, str]:
+    """Apply ``expand_meta_macros`` to every meta value."""
+    return {k: expand_meta_macros(v, macros) for k, v in meta.items()}
+
+
+def split_meta_values(value: str) -> List[str]:
+    """Return comma-separated metadata values as individual Pagefind values."""
+    return [part.strip() for part in value.split(',') if part.strip()]