Skip to content

docs: Enable Material capabilities for the published 2.2 user documentation - #375

Merged
nh-exa merged 4 commits into
release/v2.2from
nh.docs-material-features-v2.2_SPOT-32682
Sep 15, 2026
Merged

nh-exa merged 4 commits into
release/v2.2from
nh.docs-material-features-v2.2_SPOT-32682

Conversation

@nh-exa

@nh-exa nh-exa commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Description

Cherry-pick of #374 onto the 2.2 release line, so the published 2.2 documentation offers the same capabilities as main. The three commits are identical to those on #374 and applied without conflicts.

Configuration only, by design: this aligns the release line with main in theme and features, not content. After this change user-docs/mkdocs.yml differs from main only in the pre-existing nav entry for Virtual schemas, and user-docs/overrides/main.html is byte-identical.

Related Issue

SPOT-32682

Type of Change

  • docs: Documentation update

Changes Made

  • Markdown extensions: admonition, attr_list, md_in_html, toc permalinks, and the pymdownx set (details, emoji, highlight, inlinehilite, snippets, superfences, tabbed).

  • Theme features: content.code.copy/select/annotate, content.tooltips, navigation.instant plus prefetch/progress, navigation.tracking/top/footer, toc.follow, search.suggest/highlight/share, announce.dismiss.

  • Outdated-version banner via theme.custom_dir and user-docs/overrides/main.html.

  • A separate content commit re-indents six fenced blocks in cloud/aws.md and cloud/azure.md from three spaces to four, so they attach to their list items. See the notes below.

Testing

  • All existing tests pass (task all)
  • Added new tests for new functionality
  • Manually tested the changes

Test Details

  • The AWS and Azure setup sections now render as a single <ol> each (3 and 5 steps), with the code blocks nested inside their list items.
  • This branch predates the task docs-* targets, so the checks were run the way its CI does: mkdocs build --strict passes, the 41 documentation tooling tests pass, and ruff check is clean.
  • All 15 features reach the runtime config in the built 2.2 site.
  • user-docs/uv.lock on this branch independently pins mkdocs-material 9.7.7, the same version main resolves to, so every enabled feature is supported here.

Checklist

  • Code follows the project's coding guidelines
  • Ran task fmt and task lint
  • Updated documentation (if applicable) - user-docs/ for user-facing changes, doc/ for contributor-facing changes
  • Updated CHANGELOG.md for user-facing changes, including examples for new features when useful
  • Added/updated tests
  • All tests pass locally
  • Commit messages follow Conventional Commits format

Additional Notes

The 2.2 documentation carried the same latent defect as main: cloud/aws.md and cloud/azure.md indented six fenced blocks by three spaces inside ordered lists, which stock fenced_code does not recognize. Those pages published the commands as inline text with a literal bash in front and no code block at all, and the same indentation split each ordered list so step numbering restarted at 1.

Both symptoms are fixed here, matching #374 commit for commit. The built 2.2 AWS page now renders one continuous list of 3 steps with 2 real code blocks and no stray bash, and the Azure page one list of 5 steps.

The content commit is kept separate from the three configuration commits so the two concerns can be cherry-picked independently.

No CHANGELOG.md entry: this changes documentation-site presentation, not launcher behavior.

@nh-exa
nh-exa requested a review from a team September 15, 2026 10:45
@nh-exa
nh-exa merged commit 0514243 into release/v2.2 Sep 15, 2026
1 check passed
@nh-exa
nh-exa deleted the nh.docs-material-features-v2.2_SPOT-32682 branch September 15, 2026 10:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant