Merge pull request rundeck#1758 from rundeck/search-tags

Add section-based search filtering

Author: fdevans

.docsearch/config.json

@@ -2,14 +2,105 @@
   "index_name": "prod_rundeck_docs",
   "js_render": false,
   "start_urls": [
+    {
+      "url": "https://docs.rundeck.com/(?P<version>.*?)/learning/",
+      "variables": {
+        "version": [
+          "docs",
+          "4.0.x"
+        ]
+      },
+      "tags": ["Learning"]
+    },
+    {
+      "url": "https://docs.rundeck.com/(?P<version>.*?)/manual/",
+      "variables": {
+        "version": [
+          "docs",
+          "4.0.x"
+        ]
+      },
+      "tags": ["User Guide"]
+    },
+    {
+      "url": "https://docs.rundeck.com/(?P<version>.*?)/api/",
+      "variables": {
+        "version": [
+          "docs",
+          "4.0.x"
+        ]
+      },
+      "tags": ["API"]
+    },
+    {
+      "url": "https://docs.rundeck.com/(?P<version>.*?)/administration/",
+      "variables": {
+        "version": [
+          "docs",
+          "4.0.x"
+        ]
+      },
+      "tags": ["Administration"]
+    },
+    {
+      "url": "https://docs.rundeck.com/(?P<version>.*?)/developer/",
+      "variables": {
+        "version": [
+          "docs",
+          "4.0.x"
+        ]
+      },
+      "tags": ["Developer"]
+    },
+    {
+      "url": "https://docs.rundeck.com/(?P<version>.*?)/history/cves/",
+      "variables": {
+        "version": [
+          "docs",
+          "4.0.x"
+        ]
+      },
+      "tags": ["Administration"]
+    },
+    {
+      "url": "https://docs.rundeck.com/(?P<version>.*?)/history/",
+      "variables": {
+        "version": [
+          "docs",
+          "4.0.x"
+        ]
+      },
+      "tags": ["Release Notes"]
+    },
+    {
+      "url": "https://docs.rundeck.com/(?P<version>.*?)/rd-cli/",
+      "variables": {
+        "version": [
+          "docs",
+          "4.0.x"
+        ]
+      },
+      "tags": ["User Guide"]
+    },
+    {
+      "url": "https://docs.rundeck.com/(?P<version>.*?)/upgrading/",
+      "variables": {
+        "version": [
+          "docs",
+          "4.0.x"
+        ]
+      },
+      "tags": ["Administration"]
+    },
     {
       "url": "https://docs.rundeck.com/(?P<version>.*?)/",
       "variables": {
         "version": [
           "docs",
           "4.0.x"
         ]
-      }
+      },
+      "tags": ["General"]
     }
   ],
   "stop_urls": [
@@ -41,7 +132,8 @@
   "custom_settings": {
     "attributesForFaceting": [
       "version",
-      "lang"
+      "lang",
+      "tags"
     ]
   }
 }

.github/copilot-instructions.md

@@ -39,4 +39,18 @@ You are an AI assistant helping maintain the Rundeck documentation site.
 - Code blocks should specify language for proper syntax highlighting
 - Use numbered lists for sequential steps
 - Use bullet points for non-sequential items
-- Tables should have headers and consistent column formatting
+- Tables should have headers and consistent column formatting
+
+## Search Setup
+
+### Architecture
+- **Search Provider**: Algolia DocSearch via `@vuepress/plugin-docsearch`
+- **Index Name**: `prod_rundeck_docs`
+- **Indexing**: Automated via CircleCI using `algolia/docsearch-scraper` Docker image
+- **Configuration Files**:
+  - `.docsearch/config.json` - Algolia scraper configuration (selectors, start URLs, faceting attributes)
+  - `docs/.vuepress/config.ts` - VuePress DocSearch plugin configuration (appId, apiKey, search parameters)
+- **Current Facets**: `version` (filters by docs version like "docs", "4.0.x") and `lang`
+- **Section-Based Filtering**: Uses `tags` attribute to enable filtering by documentation section (learning, manual, api, administration, developer, etc.)
+- **Indexing Strategy**: Tags are applied via URL patterns in `start_urls` to categorize content by documentation section
+- **Custom Implementation**: Section filter checkboxes can be added via custom search UI using Algolia InstantSearch or DocSearch customization

README.md

@@ -96,9 +96,10 @@ git push origin
 ## Documentation Structure
 
 The documentation is organized as follows:
-- `/docs/` - Main documentation content
+- `/docs/` - Main documentation content (published to docs.rundeck.com)
 - `/docs/.vuepress/` - VuePress configuration
 - `/docs/.vuepress/public/assets/img/` - Images Folder
+- `/dev-docs/` - Internal developer documentation (scripts, architecture, workflows)
 
 # How to Create Release Notes
 
@@ -248,7 +249,7 @@ git push
 
 ## SaaS Development Updates Feed
 
-For generating RSS/Atom feeds and markdown pages showing recent PRs deployed to the SaaS platform (but not yet in self-hosted releases), see [PR-FEED-README.md](./PR-FEED-README.md).
+For generating RSS/Atom feeds and markdown pages showing recent PRs deployed to the SaaS platform (but not yet in self-hosted releases), see [dev-docs/PR-FEED-README.md](./dev-docs/PR-FEED-README.md).
 
 This feed automatically tracks changes since the last self-hosted release and is updated after each SaaS deployment:
 

dev-docs/DOCSEARCH_FILTERS_README.md

@@ -0,0 +1,109 @@
+# DocSearch Filters Integration
+
+This guide explains how to integrate the section filtering component into your Rundeck documentation search.
+
+## Components Created
+
+### 1. DocSearchFilters.vue
+- Location: `docs/.vuepress/components/DocSearchFilters.vue`
+- A Vue component that provides a filter button with a dropdown panel
+- Shows section checkboxes (Learning, User Guide, API, Administration, Developer, Release Notes, General)
+- Persists filter selections in localStorage
+- Dispatches custom events when filters change
+
+### 2. docsearch-filters.ts Plugin
+- Location: `docs/.vuepress/plugins/docsearch-filters.ts`
+- Client-side plugin that integrates filters with DocSearch
+- Listens for filter update events and applies them to DocSearch
+- Monitors DocSearch modal for filter restoration
+
+### 3. Client Configuration Updates
+- Updated `docs/.vuepress/client.ts` to initialize the filter integration
+- Imports and calls `initializeDocSearchFilters()` on app startup
+
+## Integration in Layout
+
+The filter button is **automatically injected** into the navbar by the client configuration. No manual component placement is needed.
+
+The `injectDocSearchFiltersIntoNavbar()` function in `client.ts` automatically:
+1. Waits for the DocSearch container to be rendered
+2. Creates a wrapper element next to the search container
+3. Mounts the `DocSearchFilters` component dynamically
+
+This ensures the filter component appears right next to the search button without requiring manual template modifications.
+
+## How It Works
+
+1. **User clicks the filter button** (funnel icon with badge)
+2. **Filter dropdown opens** showing available section tags
+3. **User selects/deselects sections** via checkboxes
+4. **Selections are stored** in localStorage for persistence
+5. **Filter state is dispatched** via custom `docsearch-filters-updated` event
+6. **Plugin intercepts Algolia requests** - The `docsearch-filters.ts` plugin patches `fetch` and `XMLHttpRequest` to intercept all Algolia API calls
+7. **Facet filters are injected** - Selected sections are added to the request's `facetFilters` parameter as OR conditions (e.g., `tags:Learning OR tags:API`)
+8. **Results are filtered by Algolia** - Algolia returns only results matching the selected section tags
+9. **Search input is triggered** - An input event is dispatched to refresh the search results with the new filters applied
+
+## Configuration
+
+### Available Sections
+The component currently supports these sections (from `config.json` tags):
+- Learning
+- User Guide
+- API
+- Administration
+- Developer
+- Release Notes
+- General
+
+To add new sections:
+1. Update `.docsearch/config.json` to add new `start_urls` with tags
+2. Update the `sections` array in `DocSearchFilters.vue`
+
+### VuePress Configuration
+The DocSearch configuration in `docs/.vuepress/config.ts` includes:
+```typescript
+searchParameters: {
+  hitsPerPage: 100,
+  facetFilters: [`version:${setup.base}`],
+  facets: ['tags']
+}
+```
+
+The `facets: ['tags']` tells Algolia to include tags as filterable attributes.
+
+## Styling
+
+The component uses VuePress theme variables for styling:
+- `--c-brand` - Brand color
+- `--c-border` - Border color
+- `--c-text-secondary` - Secondary text color
+- `--c-bg`, `--c-bg-light` - Background colors
+
+It automatically adapts to dark mode using `html.dark` selector.
+
+## Testing
+
+To test the filters:
+
+1. Build/run the docs: `npm run docs:dev`
+2. Click the filter button in the navbar
+3. Select a section (e.g., "Learning")
+4. Perform a search
+5. Results should only show items tagged with the selected section
+6. Refresh the page - filter selections persist via localStorage
+
+## Troubleshooting
+
+### Filters not appearing in results
+- Ensure Algolia index has been re-scraped with new tags
+- Check that `facets: ['tags']` is in the config
+- Verify the section tags match what's in `config.json`
+
+### localStorage not working
+- Browser privacy mode disables localStorage
+- Clear localStorage and refresh if there are issues
+
+### Component not visible
+- Ensure DocSearchFilters component is imported and placed in the layout
+- Check browser console for Vue component registration errors

PR-FEED-README.md dev-docs/PR-FEED-README.mdPR-FEED-README.md renamed to dev-docs/PR-FEED-README.md

@@ -362,7 +362,7 @@ This ensures the exact commits used in the build are compared, guaranteeing accu
 
 ## Related Documentation
 
-- **[README.md](./README.md)** - Main documentation project setup and release notes generation
+- **[README.md](../README.md)** - Main documentation project setup and release notes generation
 - **`notes.mjs`** - Self-hosted release notes generator (uses same shared utilities)
 - **`pr-utils.mjs`** - Shared utility functions used by both scripts
 

dev-docs/README.md

@@ -0,0 +1,76 @@
+# Developer Documentation
+
+This directory contains internal documentation for developers working on the Rundeck documentation project. These guides cover build processes, automation scripts, and architectural decisions.
+
+## Contents
+
+### 📋 [PR-FEED-README.md](./PR-FEED-README.md)
+**SaaS Development Feed Generator**
+
+Comprehensive guide for generating RSS/Atom feeds and markdown pages from recently merged pull requests in Rundeck repositories. This script is run as part of the SaaS release process to communicate updates deployed to Runbook Automation SaaS.
+
+**Key Topics:**
+- Weekly SaaS release workflow
+- Tag-based PR comparison
+- Configuration management
+- Feed generation (RSS 2.0 and Atom 1.0)
+- Integration with release notes process
+
+**Usage:** `npm run pr-feed`
+
+---
+
+### 🔍 [DOCSEARCH_FILTERS_README.md](./DOCSEARCH_FILTERS_README.md)
+**DocSearch Section Filters Integration**
+
+Technical documentation for the custom DocSearch filter component that allows users to filter documentation search results by section (Learning, API, Administration, etc.).
+
+**Key Topics:**
+- Component architecture (Vue + VuePress)
+- Client-side plugin integration
+- Algolia request interception
+- LocalStorage persistence
+- Automatic navbar injection
+
+**Files Covered:**
+- `docs/.vuepress/components/DocSearchFilters.vue`
+- `docs/.vuepress/plugins/docsearch-filters.ts`
+- `docs/.vuepress/client.ts`
+
+---
+
+## Related Documentation
+
+### Main Project Documentation
+- **[README.md](../README.md)** - Main project README with setup, release notes, and workflow instructions
+- **[.github/copilot-instructions.md](../.github/copilot-instructions.md)** - AI assistant instructions for code generation
+
+### Build Scripts
+- **`notes.mjs`** - Self-hosted release notes generator (tag-based)
+- **`pr-feed.mjs`** - SaaS development feed generator
+- **`pr-utils.mjs`** - Shared utility functions
+
+### Configuration Files
+- **`pr-feed-config.json`** - PR feed baseline configuration
+- **`.docsearch/config.json`** - Algolia DocSearch configuration
+- **`docs/.vuepress/config.ts`** - VuePress site configuration
+
+---
+
+## Contributing
+
+When adding new internal documentation:
+
+1. **Place it in this directory** (`dev-docs/`)
+2. **Update this README** with a description and link
+3. **Reference from main README** if it's a key workflow
+4. **Keep it updated** as the implementation changes
+
+---
+
+## Notes
+
+- This directory is for **internal/developer documentation only**
+- User-facing documentation belongs in `/docs/`
+- These files are **not** published to docs.rundeck.com
+- Complements the Copilot instructions in `.github/`