+{{ end }}
\ No newline at end of file
diff --git a/DEVELOPER.md b/DEVELOPER.md
index 1063cea3e29d..fb70241743e9 100644
--- a/DEVELOPER.md
+++ b/DEVELOPER.md
@@ -473,18 +473,28 @@ Follow these steps to preview documentation changes locally using a Hugo server:
npm ci
```
-1. **Start the Server:**
+1. **Generate Search Index & Start the Server:** Because the Pagefind search engine requires physical files to build its index, `hugo server` (which runs purely in memory) will not display search results by default. To test the search bar locally, build the physical site once (using the development environment to avoid triggering production analytics), generate the index into the static folder, and then start the server:
```bash
+ hugo --environment development
+ npx pagefind --site public --output-path static/pagefind
hugo server
```
+ *(Note: The `static/pagefind/` directory is git-ignored to prevent committing local search indexes).*
### Previewing Documentation on Pull Requests
+Documentation preview links are automatically generated and commented on your pull request when working from a branch within the main repository.
+
+**For external contributors (forks):**
+For security reasons, automated deployment previews are disabled for pull requests originating from external forks for the cloudflare deployments. To review your documentation changes, please follow the [Running a Local Hugo Server](#running-a-local-hugo-server) instructions to build and view the site on your local machine before requesting a review.
+
### Document Versioning Setup
The documentation uses a dynamic versioning system that outputs standard HTML sites alongside AI-optimized plain text files (`llms.txt` and `llms-full.txt`).
+**Search Indexing:** All deployment workflows automatically execute `npx pagefind --site public` to generate a version-scoped search index specific to that deployment's base URL.
+
There are 6 GHA workflows we use to achieve document versioning (each deployment scenario has one workflow for GitHub Pages and one for Cloudflare Pages):
1. **Deploy In-development docs:**
diff --git a/GEMINI.md b/GEMINI.md
index b1a045eabe8c..5966fab51d9a 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -57,13 +57,15 @@ This file (symlinked as `CLAUDE.md` and `AGENTS.md`) provides context and guidel
1. Navigate to `.hugo` directory: `cd .hugo`
2. Install dependencies: `npm ci`
-3. Start server: `hugo server`
+3. **Generate Search Index:** Because Pagefind requires physical files, `hugo server` alone will not populate the search bar. Build the local index first (using the development environment to block analytics) by running:
+ `hugo --environment development && npx pagefind --site public --output-path static/pagefind`
+4. Start server: `hugo server`
### Versioning Workflows
Documentation builds automatically generate standard HTML alongside AI-friendly text files (`llms.txt` and `llms-full.txt`).
-There are 6 workflows in total, handling parallel deployments to both GitHub Pages and Cloudflare Pages.
+There are 6 workflows in total, handling parallel deployments to both GitHub Pages and Cloudflare Pages. **All deployment workflows automatically execute `npx pagefind --site public` to generate version-scoped search indexes.**
1. **Deploy In-development docs**: Commits merged to `main` deploy to the `/dev/` path. Automatically defaults to version `Dev`.
2. **Deploy Versioned Docs**: New GitHub releases deploy to `//` and the root path. The release tag is automatically injected into the build as the documentation version. *(Note: Developers must manually add the new version to the `[[params.versions]]` dropdown array in `hugo.toml` prior to merging a release PR).*