Skip to content

Conversation

@JordonPhillips
Copy link
Contributor

This adds the myst-parser plugin plugin to the sphinx docs configuration. myst is a markdown flavor that extends commonmark with the ability to call sphinx directives and roles, like so:

.. directivename:: arguments
   :key1: val1
   :key2: val2

   This is
   directive content
```{directivename} arguments
:key1: val1
:key2: val2

This is
directive content
```

Smithy's own doc traits are in commonmark format so I think it makes sense to add this here. I've not attempted to re-write any existing docs as I think that would be a waste of time. With the plugin installed, both rst and markdown are supported simultaneously, differentiated based on the file extension.

I also ran the black formatter on conf.py as part of this.


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

This updates the doc build to allow pages to be written in markdown
using myst-parser, a markdown flavor that extends commonmark with
the ability to reference sphinx roles and directives.
@JordonPhillips JordonPhillips requested a review from a team as a code owner November 18, 2025 15:43
@JordonPhillips JordonPhillips added the no-changelog-needed This PR doesn't require a changelog entry, so the changelog automation tool should not run on it. label Nov 18, 2025
@smithy-lang smithy-lang deleted a comment from github-actions bot Nov 18, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-changelog-needed This PR doesn't require a changelog entry, so the changelog automation tool should not run on it.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants