Repository navigation
add generalizable rfc support for documentation standards - #508
Merged
alee merged 4 commits intoNov 5, 2026
Merged
Conversation
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
The Docker checker and isolated-render workflow affect all site builds, but required container-based compatibility, Hugo rendering, and subpath checks could not be run in this review environment.
No open issues 🎉
What changed in this PR
Adds reusable standards-review layouts to the Hugo/Docsy site, using the OMF ODD documentation proposal as the first application. It separates the current proposal, preserved editions, and earlier working-group drafts.
Changes:
- Publishes the ODD proposal with feedback links, edition history, original downloads, and checksum provenance.
- Adds responsive standards layouts and improves navigation, base-path handling, and image alternative text.
- Adds archive-integrity and rendered-site checks, with container-based validation and retained CI reports.
| File | Description |
|---|---|
PRODUCT.md |
Defines the documentation surface and preservation constraints. |
Makefile |
Adds validation targets and Compose-based isolated rendering. |
layouts/shortcodes/standard-file.html |
Resolves downloads from the selected edition bundle. |
layouts/shortcodes/imgproc.html |
Adds caption-derived or explicit image alternative text. |
layouts/shortcodes/blocks/standard.html |
Resolves internal standard links through Hugo. |
layouts/shortcodes/blocks/feature.html |
Resolves internal feature links through Hugo. |
layouts/partials/render-remote-readme.html |
Preserves a legacy anchor after an upstream heading rename. |
layouts/partials/page-meta-links.html |
Adds standards-specific feedback and source links. |
layouts/docs/standard.html |
Renders proposal status, downloads, archive context, and mobile contents. |
layouts/docs/standard-history.html |
Lists preserved editions and their dates. |
layouts/docs/baseof.html |
Adjusts sidebar visibility for standard pages. |
docs/documentation-standard-page.md |
Documents edition provenance, maintenance, and validation. |
Dockerfile |
Includes a pinned HTML checker for local and CI use. |
content/en/working-groups/standards/drafts/documentation/_index.md |
Preserves the earlier documentation working draft. |
content/en/working-groups/standards/drafts/_index.md |
Introduces the working-draft archive section. |
content/en/working-groups/standards/_index.md |
Links to the current proposal and earlier draft. |
content/en/working-groups/_index.md |
Removes obsolete working-group link fragments. |
content/en/standards/documentation/versions/draft-1/source-draft.txt |
Retains the supplied Markdown source. |
content/en/standards/documentation/versions/draft-1/manifest.json |
Records edition provenance, file sizes, and checksums. |
content/en/standards/documentation/versions/draft-1/index.md |
Publishes the preserved Draft 1 transcription and review context. |
content/en/standards/documentation/versions/_index.md |
Introduces documentation edition history. |
content/en/standards/documentation/_index.md |
Replaces workshop guidance with the current ODD proposal. |
content/en/about/history-events-and-activities.md |
Removes an obsolete working-groups link fragment. |
assets/scss/_styles_project.scss |
Imports standards styles and adjusts mobile branding. |
assets/scss/_standard.scss |
Adds scoped reading, mobile, and print styles. |
AGENTS.md |
Updates commit guidance and edition-validation instructions. |
.htmltest.yml |
Limits blocking HTML checks to internal links. |
.htmltest-external.yml |
Configures separate external-link reporting. |
.gitignore |
Excludes disposable validation reports. |
.github/workflows/run-htmltest.yml |
Integrates validation checks and uploads retained reports. |
.github/scripts/test_standard_archives.py |
Tests archive corruption and incomplete-bundle detection. |
.github/scripts/test_check_site.py |
Tests multi-edition checks and failure diagnostics. |
.github/scripts/render-isolated.sh |
Builds in a disposable workspace and retains diagnostics. |
.github/scripts/check_standard_archives.py |
Verifies edition files against their manifests. |
.github/scripts/check_site.py |
Checks rendered navigation, layout markers, and download integrity. |
.github/scripts/build-site.sh |
Verifies archive integrity before production rendering. |
.dockerignore |
Excludes validation reports from the Docker build context. |
Review effort: Balanced
- link to original review documents and explain feedback and adoption - preserve Draft 1 downloads and attribute the final workshop output - provide version navigation, responsive layouts, and archive checks
- resolve internal URLs under deployment base paths and repair markup - use supported publications data and format-specific image settings
- isolate Node dependencies and reuse Docker layers and Hugo caches - share production rendering and HTML checks across local and CI runs - retain failure reports and check navigation and archived downloads
alee
force-pushed
the
documentation-standards-rfc
branch
from
November 4, 2026 23:58
3cd1d66 to
4902382
Compare
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
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.
archive legacy standards working group WIP text into /working-groups/ for the standards working group, should apply to the rest of the working groups as well
add RFC page styles using the standards working group's documentation standards RFC as the initial use case
Related documentation RFC discussion for feedback