diff --git a/docs/community/topics/page-metadata.md b/docs/community/topics/page-metadata.md
index 952380fdb..ef07d95ac 100644
--- a/docs/community/topics/page-metadata.md
+++ b/docs/community/topics/page-metadata.md
@@ -7,9 +7,20 @@ This is [similar to how the TOML language defines nested configuration](https://
 
 For example, to remove the secondary sidebar, we use a page metadata key like this:
 
+`````{tab-set}
+````{tab-item} rst
 ```rst
 :html_theme.sidebar_secondary.remove: true
 ```
+````
+````{tab-item} markdown
+```md
+---
+html_theme.sidebar_secondary.remove: true
+---
+```
+````
+`````
 
 Note how the period naturally separates nested sections, and looks very similar to what we'd expect if we put this in a Python dictionary in `conf.py`:
 
diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst
index 1e98f29e3..050679bee 100644
--- a/docs/user_guide/extending.rst
+++ b/docs/user_guide/extending.rst
@@ -35,6 +35,16 @@ Then add the ``dropdown`` class to any admonition directive (shown here on a ``n
             :code: rst
             :class: highlight-rst
 
+    .. tab-item:: markdown
+
+        .. code-block:: md
+
+            ```{note}
+            :class: dropdown
+
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+            ```
+
 
 Custom admonition styles
 ========================
@@ -65,6 +75,14 @@ The title is specified on the same line as the ``.. admonition::`` directive:
             :code: rst
             :class: highlight-rst
 
+    .. tab-item:: markdown
+
+        .. code-block:: md
+
+            ```{admonition} Custom title!
+
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+            ```
 
 Styling with semantic color names
 ---------------------------------
@@ -90,6 +108,16 @@ Note that it updates both the color and the icon. See :doc:`./styling` for a lis
             :code: rst
             :class: highlight-rst
 
+    .. tab-item:: markdown
+
+        .. code-block:: md
+
+            ```{admonition} Custom title with "warning" style
+            :class: warning
+
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+            ```
+
 This theme defines classes for `the standard docutils admonition types <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`__ (``attention``, ``caution``, etc) and additionally supports ``seealso`` and ``todo`` admonitions (see :doc:`../examples/kitchen-sink/admonitions` for a demo of all built-in admonition styles).
 
 Customizing the color
@@ -117,13 +145,23 @@ Be sure to use the same color for ``border-color`` and ``color`` and a different
             :code: rst
             :class: highlight-rst
 
-    .. tab-item:: css
+    .. tab-item:: markdown
+
+        .. code-block:: md
 
-        .. include:: ../_static/custom.css
-            :start-after: begin-custom-color
-            :end-before: /* end-custom-color
-            :code: css
-            :class: highlight-css
+            ```{admonition} Admonition with custom "olive" color
+            :class: admonition-olive
+
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+            ```
+
+And add the following to your ``custom.css`` file:
+
+.. include:: ../_static/custom.css
+    :start-after: begin-custom-color
+    :end-before: /* end-custom-color
+    :code: css
+    :class: highlight-css
 
 
 Using a custom icon
@@ -148,13 +186,23 @@ Customizing the icon uses a similar process to customizing the color: create a n
             :code: rst
             :class: highlight-rst
 
-    .. tab-item:: css
+    .. tab-item:: markdown
+
+        .. code-block:: md
+
+            ```{admonition} Check out my custom icon
+            :class: admonition-icon
+
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+            ```
 
-        .. include:: ../_static/custom.css
-            :start-after: begin-custom-icon
-            :end-before: /* end-custom-icon
-            :code: css
-            :class: highlight-css
+And add the following css to your ``custom.css`` file:
+
+.. include:: ../_static/custom.css
+    :start-after: begin-custom-icon
+    :end-before: /* end-custom-icon
+    :code: css
+    :class: highlight-css
 
 
 Combining all three customizations
@@ -179,10 +227,22 @@ Here we demonstrate an admonition with a custom icon, color, and title (and also
             :code: rst
             :class: highlight-rst
 
-    .. tab-item:: css
+    .. tab-item:: markdown
+
+        .. code-block:: md
+
+            ````{admonition} YouTube
+            :class: dropdown admonition-youtube
+
+            ```{youtube} dQw4w9WgXcQ
+            ```
+
+            ````
+
+And add the following css to your custom.css file:
 
-        .. include:: ../_static/custom.css
-            :start-after: begin-custom-youtube
-            :end-before: /* end-custom-youtube
-            :code: css
-            :class: highlight-css
+.. include:: ../_static/custom.css
+    :start-after: begin-custom-youtube
+    :end-before: /* end-custom-youtube
+    :code: css
+    :class: highlight-css
diff --git a/docs/user_guide/light-dark.rst b/docs/user_guide/light-dark.rst
index bfb6ea88f..a3813af5b 100644
--- a/docs/user_guide/light-dark.rst
+++ b/docs/user_guide/light-dark.rst
@@ -86,13 +86,29 @@ These are:
 For example, the following page content defines two images, each of which uses a different one of the classes above.
 Change the theme and a new image should be displayed.
 
-.. code-block:: rst
+.. tab-set::
 
-    .. image:: https://source.unsplash.com/200x200/daily?cute+cat
-        :class: only-dark
+    .. tab-item:: rst
 
-    .. image:: https://source.unsplash.com/200x200/daily?cute+dog
-        :class: only-light
+        .. code-block:: rst
+
+            .. image:: https://source.unsplash.com/200x200/daily?cute+cat
+                :class: only-dark
+
+            .. image:: https://source.unsplash.com/200x200/daily?cute+dog
+                :class: only-light
+
+    .. tab-item:: markdown
+
+        .. code-block:: md
+
+            ```{image} https://source.unsplash.com/200x200/daily?cute+cat
+            :class: only-dark
+            ```
+
+            ```{image} https://source.unsplash.com/200x200/daily?cute+dog
+            :class: only-light
+            ```
 
 .. image:: https://source.unsplash.com/200x200/daily?cute+cat
     :class: only-dark
@@ -115,20 +131,45 @@ theme-agnostic.
 For example, here's an image without adding this helper class.
 Change to the dark theme and a grey background will be present.
 
-.. code-block:: rst
+.. tab-set::
+
+    .. tab-item:: rst
+
+        .. code-block:: rst
+
+            .. image:: https://source.unsplash.com/200x200/daily?cute+cat
+                :class: p-2
+
+    .. tab-item:: markdown
+
+        .. code-block:: md
+
+            ```{image} https://source.unsplash.com/200x200/daily?cute+cat
+            :class: p-2
+            ```
 
-    .. image:: https://source.unsplash.com/200x200/daily?cute+cat
-        :class: p-2
 
 .. image:: https://source.unsplash.com/200x200/daily?cute+cat
     :class: p-2
 
 Here's the same image with this class added:
 
-.. code-block:: rst
+.. tab-set::
 
-    .. image:: https://source.unsplash.com/200x200/daily?cute+cat
-        :class: dark-light p-2
+    .. tab-item:: rst
+
+        .. code-block:: rst
+
+            .. image:: https://source.unsplash.com/200x200/daily?cute+cat
+                :class: dark-light
+
+    .. tab-item:: markdown
+
+        .. code-block:: md
+
+            ```{image} https://source.unsplash.com/200x200/daily?cute+cat
+            :class: dark-light p-2
+            ```
 
 .. image:: https://source.unsplash.com/200x200/daily?cute+cat
     :class: dark-light p-2
@@ -140,23 +181,46 @@ You can define a JavaScript event hook that will run your code any time the them
 This is useful if you need to change elements of your page that cannot be defined by CSS rules.
 For example, to change an image source (e.g., logo) whenever the ``data-theme`` changes, a snippet like this can be used:
 
-.. code-block:: rst
+.. tab-set::
+
+    .. tab-item:: rst
+
+        .. code-block:: rst
+
+            .. raw:: html
+
+                <script type="text/javascript">
+                var observer = new MutationObserver(function(mutations) {
+                    const dark = document.documentElement.dataset.theme == 'dark';
+                    document.getElementsByClassName('mainlogo')[0].src = dark ? '_static/my_logo_dark.svg' : "_static/my_logo_light.svg";
+                })
+                observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
+                </script>
+                <link rel="preload" href="_static/my_logo_dark.svg" as="image">
+
+            .. image:: _static/my_logo_light.svg
+                :alt: My Logo
+                :class: logo, mainlogo
+                :align: center
+
+    .. tab-item:: markdown
 
-  .. raw:: html
+        .. code-block:: md
 
-    <script type="text/javascript">
-      var observer = new MutationObserver(function(mutations) {
-        const dark = document.documentElement.dataset.theme == 'dark';
-        document.getElementsByClassName('mainlogo')[0].src = dark ? '_static/my_logo_dark.svg' : "_static/my_logo_light.svg";
-      })
-      observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
-    </script>
-    <link rel="preload" href="_static/my_logo_dark.svg" as="image">
+            <script type="text/javascript">
+            var observer = new MutationObserver(function(mutations) {
+                const dark = document.documentElement.dataset.theme == 'dark';
+                document.getElementsByClassName('mainlogo')[0].src = dark ? '_static/my_logo_dark.svg' : "_static/my_logo_light.svg";
+            })
+            observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
+            </script>
+            <link rel="preload" href="_static/my_logo_dark.svg" as="image">
 
-  .. image:: _static/my_logo_light.svg
-     :alt: My Logo
-     :class: logo, mainlogo
-     :align: center
+            ```{image} _static/my_logo_light.svg
+            :alt: My Logo
+            :class: logo, mainlogo
+            :align: center
+            ```
 
 The JavaScript reacts to ``data-theme`` changes to alter ``img``, and the ``link`` is used to preload the dark image.
 See the `MutationObserver documentation <https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver>`_ for more information.
diff --git a/docs/user_guide/static_assets.md b/docs/user_guide/static_assets.md
index 2611bd27e..1780a14c4 100644
--- a/docs/user_guide/static_assets.md
+++ b/docs/user_guide/static_assets.md
@@ -103,9 +103,11 @@ def setup(app):
 ## Add it directly to the page content
 
 Finally, you can add CSS or JS directly to a page's content.
-If you're using reStructuredText or MyST Markdown, you can use the `raw` directive:
+If you're using either the raw directive (reStructuredText) or pure html (MyST Markdown).
 
-```{code-block} rst
+``````{tab-set}
+`````{tab-item} rst
+````{code-block} rst
 :caption: some_page_in_my_site.rst
 .. raw:: html
 
@@ -118,13 +120,10 @@ If you're using reStructuredText or MyST Markdown, you can use the `raw` directi
    <script>
    console.log("hi!")
    </script>
-```
-
-If you're using MyST Markdown, you may also directly include any HTML / style / script blocks in your content without using a directive.
-
-For example:
-
-```{code-block} md
+````
+`````
+`````{tab-item} markdown
+````{code-block} md
 :caption: other_page_in_my_site.md
 # My title
 
@@ -140,4 +139,6 @@ Some text
 ## A bigger title
 
 Some other text
-```
+````
+`````
+``````
diff --git a/docs/user_guide/theme-elements.md b/docs/user_guide/theme-elements.md
index b7faad4f5..7933292b2 100644
--- a/docs/user_guide/theme-elements.md
+++ b/docs/user_guide/theme-elements.md
@@ -60,6 +60,16 @@ print("A regular code block")
 You can also provide captions with code blocks, which will be displayed right above the code.
 For example, the following code:
 
+``````{tab-set}
+`````{tab-item} rst
+````rst
+.. code-block:: python
+    :caption: python.py
+
+    print("A code block with a caption.")
+````
+`````
+`````{tab-item} markdown
 ````md
 ```{code-block} python
 :caption: python.py
@@ -67,6 +77,8 @@ For example, the following code:
 print("A code block with a caption.")
 ```
 ````
+`````
+``````
 
 results in:
 
@@ -79,6 +91,19 @@ print("A code block with a caption.")
 You can also display line numbers.
 For example, the following code:
 
+``````{tab-set}
+`````{tab-item} rst
+````rst
+..  code-block:: python
+    :caption: python.py
+    :linenos:
+
+    print("A code block with a caption and line numbers.")
+    print("A code block with a caption and line numbers.")
+    print("A code block with a caption and line numbers.")
+````
+`````
+`````{tab-item} markdown
 ````md
 ```{code-block} python
 :caption: python.py
@@ -89,6 +114,8 @@ print("A code block with a caption and line numbers.")
 print("A code block with a caption and line numbers.")
 ```
 ````
+`````
+``````
 
 results in:
 
@@ -105,14 +132,26 @@ print("A code block with a caption and line numbers.")
 
 When used directly, the `code` role just displays the text without syntax highlighting, as a literal. As mentioned in the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#inline-code-highlighting) you can also enable syntax highlighting by defining a custom role. It will then use the same highlighter as in the `code-block` directive.
 
-```{code-block} rst
-
+``````{tab-set}
+`````{tab-item} rst
+````rst
 .. role:: python(code)
    :language: python
 
 In Python you can :python:`import sphinx`.
+````
+`````
+`````{tab-item} markdown
+````md
+```{role} python(code)
+:language: python
 ```
 
+In Python you can {python}`import sphinx`.
+````
+`````
+``````
+
 ```{role} python(code)
 :language: python
 ```
@@ -143,12 +182,24 @@ For example, on the right are an "admonition sidebar" and a traditional Sphinx s
 To make an admonition behave like a sidebar, add the `sidebar` class to its list of classes.
 The admonition sidebar in this section was created with the following Markdown:
 
+``````{tab-set}
+`````{tab-item} rst
+````rst
+.. admonition:: A sidebar admonition!
+    :class: sidebar note
+
+    Some sidebar content.
+````
+`````
+`````{tab-item} markdown
 ````md
 ```{admonition} A sidebar admonition!
 :class: sidebar note
 Some sidebar content.
 ```
 ````
+`````
+``````
 
 ## Footnotes