Skip to content

Commit

Permalink
fix: use consistent markup in examples (#1373)
Browse files Browse the repository at this point in the history 
* fix: check the tab representation

* fix: check the tab representation

* correct setup for markdown files

* correct setup for markdown files

* theme-element

* docs: edit extending

* refactor: typo

* docs: ligh-dark page

* fix: static_assets

* use captions

* add metadata key

* typo

* typo

* fix: no need for raw in myst
  • Loading branch information
@12rambau
12rambau authored Jul 3, 2023
1 parent a53a3b1 commit 00c3575
Show file tree
Hide file tree
Showing 5 changed files with 242 additions and 55 deletions.
11 changes: 11 additions & 0 deletions docs/community/topics/page-metadata.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`:

Expand Down
96 changes: 78 additions & 18 deletions docs/user_guide/extending.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
========================
Expand Down Expand Up @@ -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
---------------------------------
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
114 changes: 89 additions & 25 deletions docs/user_guide/light-dark.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.
21 changes: 11 additions & 10 deletions docs/user_guide/static_assets.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -140,4 +139,6 @@ Some text
## A bigger title
Some other text
```
````
`````
``````
Loading

0 comments on commit 00c3575

Please sign in to comment.