Add ability to publish our docs in markdown format

[yasmewad]

Background

This adds markdown versions of all documentation pages alongside the existing HTML output. AI agents and LLMs can now consume Smithy docs directly at /2.0/markdown/<path>.md without parsing HTML, which is more token-efficient and eliminates the need to navigate through <div> tags and CSS classes to find actual content.

The llms.txt index is updated to point to markdown URLs so agents can programmatically discover all available content. A <link rel="alternate"> tag is added to the landing page so agents parsing smithy.io can find llms.txt without guessing paths.

This also fixes a pre-existing crash in redirects.py where app.warn (deprecated in 1.6, removed in 2.0) caused the build to fail when using any non-HTML builder. Custom node handlers are added for tip, danger, caution, and admonition directives so their content is preserved in the markdown output rather than silently dropped.

Testing

Built locally with Python 3.12. The markdown builder produces 123 files for Smithy 2.0 and 56 for 1.0. Code blocks, tables, cross-references, and links all render correctly. The HTML build continues to work unchanged.

Links

• llmstxt.org spec: the standard for /llms.txt discovery
• sphinx-markdown-builder: the Sphinx extension used
• Sphinx deprecated APIs: app.warn removal reference
• Builds on Add llms.txt generation to docs build #3010 which added llms.txt generation

[github-actions]

This pull request does not contain a staged changelog entry. To create one, use the ./.changes/new-change command. For example:

./.changes/new-change --pull-requests "#3097" --type feature --description "Dev/yasmewad/markdown docs publishing"

Make sure that the description is appropriate for a changelog entry and that the proper feature type is used. See ./.changes/README or run ./.changes/new-change -h for more information.

[yasmewad]

This allows implicit discovery if an LLM or agent comes across the documentation through our HTML pages

[JordonPhillips]

Why not just convert all the source to markdown? Some of our pages already use it. That would make offboarding to some other thing easier

[yasmewad]

Why not just convert all the source to markdown? Some of our pages already use it. That would make offboarding to some other thing easier

Hmm, my intention was to make it additive as a change. Would we lose those !TIP and !IMPORTANT sections if we move away from .rst?

What about we ship this so we get benefit right away for the intention of providing value right now with current conversion and then convert in batches to .md?