Fix: Disable edit links for unreleased versions

.htmltest.yml

@@ -9,8 +9,7 @@ IgnoreURLs:
   - ^/docs/latest(/?|/architecture/)$
   - /livereload.js # cSpell:disable-line
   - ^https://www.jaegertracing.io/js/lunr
-  # Ignore Docsy-generated GitHub links for now
-  - ^https?://github\.com/.*?/.*?/(new|edit)/ # view-page, edit-source etc
+
   # Valid URL, whether canonical (before reorg) or not (and handled via a redirect)
   - ^/docs/1.[6-9]\d/sampling/
   # Valid URLs, but servers yield 403 or similar errors

AGENTS.md

@@ -19,6 +19,10 @@ Before making changes, familiarize yourself with:
 The CONTRIBUTING.md file contains all necessary information for setting up,
 building, linting, and making changes to the documentation.
 
+**For human-centric guidelines** such as DCO (Developer Certificate of Origin)
+signing, PR etiquette, and community interaction, refer to [CONTRIBUTING.md](CONTRIBUTING.md)
+and the [general contributing guidelines](https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING_GUIDELINES.md).
+
 ## Agentic Workflow Tips
 
 ### Repository Structure
@@ -41,6 +45,79 @@ efficiently:
 - **Deployment**: Netlify automatically deploys from the `main` branch
 - **Preview**: Netlify creates preview deployments for PRs
 
+### Testing and Verifying Changes
+
+Before submitting a PR, verify your changes locally:
+
+#### 1. Setup (First Time Only)
+
+```bash
+npm install
+```
+
+This installs all dependencies including the required Hugo version.
+
+#### 2. Run the Site Locally
+
+```bash
+make develop
+# or
+npm run serve
+```
+
+This starts a local server at [localhost:1313](http://localhost:1313) with hot
+reload. Verify your changes render correctly in the browser.
+
+#### 3. Build the Site
+
+```bash
+npm run build
+```
+
+Ensure the build completes without errors before submitting a PR.
+
+#### 4. Run All Checks
+
+Run these commands to verify CI will pass:
+
+```bash
+npm run check:format      # Check code formatting
+npm run check:spelling    # Run spellcheck
+npm run check:links:internal  # Check internal links (faster)
+npm run check:filenames   # Check filename conventions
+```
+
+For comprehensive link checking (including external links):
+
+```bash
+npm run check:links:all   # Check all links (slower, builds site first)
+```
+
+#### 5. Fix Common Issues
+
+```bash
+npm run fix:format        # Auto-fix formatting issues
+npm run fix:filenames     # Convert underscores to hyphens in filenames
+npm run fix               # Run both fixes
+```
+
+### Spellchecking
+
+The repository uses [cspell](https://cspell.org/) for spellchecking. Configuration
+is in `.cspell.yml` with custom dictionaries in the `.cspell/` directory.
+
+If the spellchecker flags a legitimate word (technical term, proper noun, etc.):
+
+1. **For general technical terms**: Add to `.cspell/project-words.txt`
+2. **For people's names**: Add to `.cspell/project-names-src.txt`
+
+**Important rules for `project-words.txt`:**
+
+- Words must be sorted alphabetically (case-insensitive)
+- One word per line
+- The file is case-sensitive, so add the exact casing needed
+- Run `sort -c --ignore-case .cspell/project-words.txt` to verify sorting
+
 ### Troubleshooting
 
 #### Link Checker Issues
@@ -61,11 +138,24 @@ Common issues:
 
 #### Filename Violations
 
-If CI complains about filename conventions:
+Run `npm run fix:filenames` to auto-fix.
 
-```bash
-npm run fix:filenames
-```
+#### Spellcheck Failures
+
+1. Review the flagged words in the output
+2. If the word is misspelled, fix it in the content
+3. If the word is legitimate, add it to the appropriate dictionary file
+4. Ensure `project-words.txt` remains sorted alphabetically
+
+### Documentation Versioning
+
+When making documentation changes:
+
+- **New features/changes**: Edit files in `content/docs/v2/_dev/` (for next release)
+- **Fixes for current version**: Apply to both `_dev/` and the most recent version
+  directory (e.g., `content/docs/v2/2.x/`) so changes appear immediately on the
+  live site
+- **Backporting**: Update older version directories if the fix applies to them
 
 ### Additional Resources
 

hugo.yaml

@@ -156,3 +156,13 @@ module:
       target: assets/icons/logo.svg
     - source: static/img/hero-background.jpg
       target: content/hero-background.jpg
+
+security:
+  funcs:
+    getenv:
+      # Defaults
+      - ^HUGO_
+      - ^CI$
+      # Whitelist for PR link checking
+      - ^GITHUB_SHA$
+      - ^HEAD$

themes/docsy-overrides/layouts/_partials/page-meta-links.html

@@ -0,0 +1,57 @@
+{{ if .File -}}
+{{ $path := strings.TrimPrefix (add hugo.WorkingDir "/") $.File.Filename -}}
+{{ $gh_repo := $.Param "github_repo" -}}
+{{ $gh_url := $.Param "github_url" -}}
+{{ $gh_subdir := $.Param "github_subdir" | default "" -}}
+{{ $gh_project_repo := $.Param "github_project_repo" -}}
+{{ $gh_branch := $.Param "github_branch" | default "main" -}}
+{{/* Use GITHUB_SHA (Actions) or HEAD (Netlify) if in CI, to link to the correct commit/branch for new files */}}
+{{ if os.Getenv "CI" -}}
+{{ $gh_branch = os.Getenv "GITHUB_SHA" | default (os.Getenv "HEAD") | default $gh_branch -}}
+{{ end -}}
+
+<div class="td-page-meta ms-2 pb-1 pt-2 mb-0">
+  {{ if $gh_repo -}}
+
+  {{/* Adjust $path based on path_base_for_github_subdir */ -}}
+  {{ $ghs_base := $.Param "path_base_for_github_subdir" -}}
+  {{ $ghs_rename := "" -}}
+  {{ if reflect.IsMap $ghs_base -}}
+  {{ $ghs_rename = $ghs_base.to -}}
+  {{ $ghs_base = $ghs_base.from -}}
+  {{ end -}}
+  {{ with $ghs_base -}}
+  {{ $path = replaceRE . $ghs_rename $path -}}
+  {{ end -}}
+
+  {{ $gh_repo_path := printf "%s/%s/%s" $gh_branch $gh_subdir $path -}}
+  {{ $gh_repo_path = replaceRE "//+" "/" $gh_repo_path -}}
+
+  {{ $viewURL := printf "%s/tree/%s" $gh_repo $gh_repo_path -}}
+  {{ $editURL := printf "%s/edit/%s" $gh_repo $gh_repo_path -}}
+  {{ $issuesURL := printf "%s/issues/new?title=%s" $gh_repo (safeURL $.Title ) -}}
+  {{ $newPageStub := resources.Get "stubs/new-page-template.md" -}}
+  {{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}}
+  {{ $newPageURL := printf "%s/new/%s?%s" $gh_repo (path.Dir $gh_repo_path) $newPageQS -}}
+
+  <a href="{{ $viewURL }}" class="td-page-meta--view td-page-meta__view" target="_blank" rel="noopener"><i
+      class="fa-solid fa-file-lines fa-fw"></i> {{ T "post_view_this" }}</a>
+  <a href="{{ $editURL }}" class="td-page-meta--edit td-page-meta__edit" target="_blank" rel="noopener"><i
+      class="fa-solid fa-pen-to-square fa-fw"></i> {{ T "post_edit_this" }}</a>
+  <a href="{{ $newPageURL }}" class="td-page-meta--child td-page-meta__child" target="_blank" rel="noopener"><i
+      class="fa-solid fa-pen-to-square fa-fw"></i> {{ T "post_create_child_page" }}</a>
+  <a href="{{ $issuesURL }}" class="td-page-meta--issue td-page-meta__issue" target="_blank" rel="noopener"><i
+      class="fa-solid fa-list-check fa-fw"></i> {{ T "post_create_issue" }}</a>
+  {{ with $gh_project_repo -}}
+  {{ $project_issueURL := printf "%s/issues/new" . -}}
+  <a href="{{ $project_issueURL }}" class="td-page-meta--project td-page-meta__project-issue" target="_blank"
+    rel="noopener"><i class="fa-solid fa-list-check fa-fw"></i> {{ T "post_create_project_issue" }}</a>
+  {{ end -}}
+
+  {{ end -}}
+  {{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}}
+  <a id="print" href="{{ .RelPermalink | safeURL }}"><i class="fa-solid fa-print fa-fw"></i> {{ T "print_entire_section"
+    }}</a>
+  {{ end }}
+</div>
+{{ end -}}