docs: Enable Material capabilities for the published user documentation

[nh-exa]

Description

The published documentation ran a near-stock Material theme: no Markdown extensions were configured and no theme features were enabled. Code and CLI examples had no copy control, headings had no linkable anchors, and readers on an older documentation version got no indication that a newer one exists.

This enables the Material capabilities that close those gaps. It is configuration only, with no page content or prose changes, so the commits can be cherry-picked onto maintained release branches independently of content work.

Related Issue

SPOT-32682

Type of Change

• docs: Documentation update

Changes Made

Three commits, each independently buildable and each touching a distinct region of user-docs/mkdocs.yml:

• Markdown extensions (admonition, attr_list, md_in_html, toc permalinks, pymdownx.details/emoji/highlight/inlinehilite/snippets/superfences/tabbed) give syntax highlighting and heading anchors now, and make callouts, collapsible blocks, content tabs, code annotations, and snippet includes available to later content work.
• 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) add the copy button on every code block, instant navigation, back-to-top, previous and next links, and a table of contents that follows the reading position.
• Outdated-version banner via theme.custom_dir and user-docs/overrides/main.html, filling Material's outdated block. Material keeps it hidden and reveals it when mike reports that the reader is not on the current version.

Out of scope by design: page content and prose, an "edit this page" action, all mkdocs plugins, and sidebar navigation layout.

• 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.
• task docs-check (lint, tests, mkdocs build --strict) passes. task lint passes in full, and task fmt leaves the tree unchanged. task all was not run because its integration tests provision real deployments and nothing outside the documentation site changed.
• All 15 features reach the runtime config in the built site, with the clipboard translations present. Material injects the copy button client-side, so it is deliberately absent from static HTML.
• Code blocks render with the language-* highlight wrapper, __span line spans, and __codelineno anchors that the clipboard and annotation runtime targets.
• The outdated banner renders inside data-md-component="outdated" with the link to the current version.
• Rendered page text was diffed against a build of main across all 19 pages. Prose is identical except on the two pages described below.

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

This fixes two pages that were silently broken. cloud/aws.md and cloud/azure.md indented six fenced blocks by three spaces inside ordered lists. Stock fenced_code does not recognize those fences, so main currently publishes them as inline text with a literal bash in front of the command and no code block at all. The same indentation also split each ordered list into separate lists, restarting step numbering at 1.

Both symptoms are now addressed. The configuration commits make pymdownx.superfences recognize the fences, and the final content commit re-indents them to four spaces so they attach to their list items. The AWS setup steps render as one continuous list of 3, and the Azure steps as one list of 5, each with its command nested inside the step it belongs to.

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.

announce.dismiss takes effect only once an announcement bar is added. It is included so that the override file introduced here is ready for one.