Optimize Articles index navigation and discoverability - #337
Merged
Merged
Conversation
…eed link relative
`publish-docs.yml` runs `tools/validate-doc-metadata.cs` but did not list it
among the `tools/*.cs` path filters, so a change to that validator alone could
not republish the site. `docs-validation.yml` already lists it; add it here too.
The RSS autodiscovery link and the footer subscribe link hard-coded
`/Learning/feed.xml`, which 404s at the `localhost:8080` preview CONTRIBUTING.md
tells contributors to use. Render both with `{{_rel}}feed.xml` instead. Because
`_appFooter` is interpolated as raw HTML and is never re-parsed as a template,
the footer markup moves from `docfx.json` global metadata into the local
`_master.tmpl` override, and the template's header comment records the added
reason for the override.
`validate-doc-metadata.cs` now resolves the autodiscovery href against the
page's own canonical URL, so it still proves every page points at the published
feed while accepting the depth-correct relative form.
Fixes #267
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds docs/articles/2026/your-audit-log-is-not-evidence.md, a standalone article arguing that a log line written after an operation narrates an outcome rather than establishing what was decided. The article works through four failures: the record captures the outcome instead of the decision and its inputs, nothing binds the record to the operation it describes, the record is written after the protected effect, and integrity ends at whatever the log sink provides. It closes with record-focused tests, explicit guidance on when an ordinary structured log is the right answer, and a review checklist. Registers the article in docs/articles/toc.yml and docs/articles/index.md following the existing newest-first ordering and permanent year/slug URL convention. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…into issue_work
Enable and document the desired repository security posture for Learning, including Dependabot security updates, secret scanning, push protection, and an explicit main-branch ruleset. Preserve required documentation, link, sample, and CodeQL checks while requiring squash-only linear history, stale-review dismissal, resolved review threads, and a pull-request-only emergency bypass. Closes #287
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Optimizes
docs/articles/index.mdto improve article discovery and scanability while preserving the existing DocFX-compatible Markdown structure, article URLs, and publication links.The Articles page remains a chronological archive, but now gives readers a faster way to enter the collection by topic before browsing the full year-based list.
Changes
Added a Start by Topic section that routes readers to articles by common interests such as:
Added a clearer Publication Model section covering:
Renamed the chronological section to 2026 Archive for clearer archive semantics.
Preserved all existing:
Kept the Articles and Tutorials Serve Different Jobs comparison intact.
Added a dedicated Contribute an Article section for publishing guidance.
Design Goals
Validation
git apply --checkpassed.git diff --checkpassed.docs/articles/index.mdwas modified.