diff --git a/.htmltest.yml b/.htmltest.yml index 4594e728..ff7abad9 100644 --- a/.htmltest.yml +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index 09dcc2f3..b8bfa8a2 100644 --- a/AGENTS.md +++ b/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 diff --git a/hugo.yaml b/hugo.yaml index 02884df0..0787c917 100644 --- a/hugo.yaml +++ b/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$ diff --git a/themes/docsy-overrides/layouts/_partials/page-meta-links.html b/themes/docsy-overrides/layouts/_partials/page-meta-links.html new file mode 100644 index 00000000..d787fbb5 --- /dev/null +++ b/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 -}} + +
+ {{ 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 -}} + + {{ T "post_view_this" }} + {{ T "post_edit_this" }} + {{ T "post_create_child_page" }} + {{ T "post_create_issue" }} + {{ with $gh_project_repo -}} + {{ $project_issueURL := printf "%s/issues/new" . -}} + {{ T "post_create_project_issue" }} + {{ end -}} + + {{ end -}} + {{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}} + {{ T "print_entire_section" + }} + {{ end }} +
+{{ end -}} \ No newline at end of file