[DOCS]: Add Github Pages workflow#47
Merged
Merged
Conversation
spencrr
force-pushed
the
spencrr/github-pages
branch
from
90b044b to
51f90d9
Compare
4 tasks
nina-msft
approved these changes
May 19, 2026
spencrr
added a commit
that referenced
this pull request
May 19, 2026
## Description Builds on #47 to upgrade the mkdocs-material site from "functional" to "launch-ready" ahead of going public at `microsoft.github.io/RAMPART`. ### Site identity & metadata - **NEW SVG: Site logo + favicon** wired to **`docs/images/RAMPART.svg`**. - **Centered hero logo** on the home page - replaces inline `<div style>` with a CSS class (`.hero-logo` in `custom.css`) for theming consistency. - **`copyright`** footer added; Material "Made with…" attribution suppressed (`extra.generator: false`) - Microsoft OSS convention. - **`extra.social`** GitHub link in footer. - **Per-page `description` frontmatter** on all section landing pages and `index.md` for better SEO and richer search snippets. - **404 page** (`docs/404.md`) with branded copy + search; GitHub Pages serves it automatically for missing paths. ### Navigation & UX - **Header tabs** for top-level sections (`navigation.tabs` + `tabs.sticky`). - **Breadcrumbs** (`navigation.path`) on every non-root page. - **Instant SPA-style nav** + progress bar (`navigation.instant`, `navigation.instant.progress`). - **Prev/next page footer** on every page (`navigation.footer`). - **Scroll-tracking URLs** for deep-linkable headings (`navigation.tracking`). - **Edit-this-page** pencil that opens the GitHub source ### Search - `search.suggest` (inline autocomplete), `search.highlight` (highlight matches on landed page), `search.share` (share-this-query button). ### Content authoring features - **Code annotations** (`content.code.annotate`) - numbered callouts in the Quickstart Step 2 adapter/session example and the Authoring Tests session example, replacing post-block bullet lists. Big pedagogical win. - **Line numbers** + click-to-select (`content.code.select` + optin for `linenums="1"`) on long reference implementations. - **Collapsible details** (`pymdownx.details`) - `_FileInjection` reference implementation tucked into a `??? note` block to keep the surrounding tutorial scannable. - **Platform tabs** (`pymdownx.tabbed` + `content.tabs.link`) with `Linux / macOS` and `Windows (PowerShell)` for venv activation and ad-hoc env-var setting. Tab labels match exactly so selection syncs site-wide. - **Task lists** (`pymdownx.tasklist`) - release-readiness pre-flight in `release-process.md` now renders as checkboxes; the PR-template checklist on `pull-requests.md` picks up the styling automatically. - **Acronym tooltips** (`abbr` + `pymdownx.snippets` + `content.tooltips`) - site-wide definitions for RAMPART/security-specific acronyms (XPIA, PyRIT, CVE, OG, OIDC, OWASP, SemVer, PyPA, gRPC, SUT). Defined once in `docs/_includes/abbreviations.md`; auto-appended to every page. ### Build hardening - **Strict validation block** - `omitted_files`, `absolute_links`, `anchors` configured at `warn` (fatal under `--strict`); `unrecognized_links` at `info` to stage warnings without blocking until the corpus is fully cleaned. - **`not_in_nav`** for `404.md`; **`exclude_docs`** for `_includes/` and `_overrides/` so they don't appear in nav, search, or build output. ### Theme overrides - New `docs/_overrides/main.html` with an **announce banner** ("RAMPART is in alpha - APIs may change before 1.0") + `announce.dismiss` feature. The banner re-appears for everyone when we change its content, so flipping to a "1.0 stable" message after launch is one-line. - `theme.custom_dir: docs/_overrides` enables the override. ### Plugins added - **`privacy`** - inlines all external assets (Roboto + Roboto Mono fonts, Material icons, Twemoji SVGs) at build time. Deployed site makes zero third-party network calls. - **`git-revision-date-localized`** - adds "Last update: 2 days ago" ## Follow-ups (intentionally out of scope) - **Social cards plugin** (`mkdocs-material[imaging]` + Cairo system deps) - adds rich OpenGraph preview images. Deferred to a separate PR to keep this one focused; nothing here blocks adding it later. - **Custom hero landing page** (`overrides/home.html` with CTA buttons + a feature grid) - bigger lift; better as its own "launch polish" PR. ## Checklist - [x] `pre-commit run --all-files` passes - [x] Tests added or updated for changes - N/A, docs-only - [x] Documentation updated - [x] `uv run mkdocs serve --strict` compiles
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
2 participants
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.
Description
Adds build + publish github workflow for docs.
Breaking changes
None
Checklist
pre-commit run --all-filespasses