Example components - Markdown¶
Here is an example page containing the components of designed into this Sphinx theme.
This text is part of the first header, but you should only use the first header once
per page! All text on this page is written in Markdown, and rendered by the
myst-parser package (MyST).
You should see me in the sidebar in the On this page section.
Heading 2¶
Here is some text under Heading 2. You should see me in the sidebar in the
On this page section.
Heading 3¶
Here is some text under Heading 3. You should see me in the sidebar in the
On this page section.
Heading 4¶
Here is some text under Heading 4. You should see me in the sidebar in the
On this page section.
Heading 5¶
Here is some text under Heading 5. You should see me in the sidebar in the
On this page section.
Heading 6¶
Here is some text under Heading 6. You should see me in the sidebar in the
On this page section.
Adding mathematics¶
To render mathematics in Sphinx, you need to have the Sphinx MathJax extension enabled. There are two allowed formats; dollar, and amsmath.
Dollar syntax¶
Inline mathematics can be written as $e=mc^{2}$, which is rendered as \(e=mc^{2}\). For
block mathematics, wrap your mathematics block with $$. For example:
$$
e=mc^{2}
$$
becomes:
You can also label block mathematics by adding parenthesis after the closing $$ and
reference it like:
$$
e=mc^{2}
$$ (eqn:example)
This is the equation for mass-energy equivalence {eq}`eqn:example`.
to give:
This is the equation for mass-energy equivalence (1).
amsmath syntax¶
This example is taken directly from the documentation for MyST. If you
write the following block of amsmath:
\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}
\begin{align}
a_{11}& =b_{11}&
a_{12}& =b_{12}\\
a_{21}& =b_{21}&
a_{22}& =b_{22}+c_{22}
\end{align}
this will be rendered as:
Adding tables¶
Tables are rendered using standard Markdown table styles, so this:
| Column 1 | Column 2 |
| :--------------------------- | ----------------------------: |
| This column is left-aligned. | This column is right-aligned. |
becomes the following rendered output in the Sphinx documentation:
Column 1 |
Column 2 |
|---|---|
This column is left-aligned. |
This column is right-aligned. |
Note only left- and right-aligned columns are supported, according to the GOV.UK Design system.
Including images¶
To include images, you can use either Markdown, reStructuredText (ReST), or pure HTML.
We have a GOV.UK logo image at ../_static/images/govuk-logo.png, and a duplicate
image at ../_static/images/govuk-logo-duplicate.png that we will use in all the
following examples; the duplicate image helps this website meet accessibility standards.
Markdown¶
To include the image in Markdown, add the following text:
to include the image with the alt text GOV.UK logo, like so:
Note you are limited in image configuration using Markdown.
reStructured Text¶
To include the image in ReST, add the following text:
```{image} ../_static/images/govuk-logo.png
:alt: GOV.UK logo
:width: 200px
```
to include the image with the alt text GOV.UK logo at a set width of 200 pixels, like
so:
Note this ReST syntax will not render in Markdown viewers such as GitHub - use HTML instead.
HTML¶
To include the image in HTML, add the following text:
<img src="../_static/images/govuk-logo-duplicate.png" alt="GOV.UK logo - duplicate" width="200px">
to include the image with the alt text GOV.UK logo at a set width of 200 pixels, like
so:
GOV.UK Design System components¶
Some GOV.UK Design System components are incorporated into this theme.
Warning¶
To add a warning, add the following code to your Markdown file:
```{warning}
A warning.
```
which produces: