MyST

5.2. MyST#

last update: Feb 07, 2024

5.2.1. Heading#

# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6
Heading level 1

Heading level 2

Heading level 3

Heading level 4

Heading level 5

Heading level 6

5.2.2. Target headers#

(target)=
### target
...
see [target](target)

target#

… see target

5.2.3. Quote#

> this is a quote

this is a quote

5.2.4. End line#

some text

---
some text.

some text

some text.

5.2.5. Line comment#

% This is a line comment.

5.2.6. Block break#

This is an example of
+++ {"meta": "data"}
a block break

This is an example of

a block break

5.2.7. List#

1. First item
2. Second item
    * First sub-item
    * Second sub-item
      * Third subsub-item

First item
Second item
- First sub-item
- Second sub-item
  - Third subsub-item

5.2.8. Table#

:::{list-table} This table title
:header-rows: 1
:name: example-table

* - Training
  - Validation
* - 0
  - 5
* - 13720
  - 2744
:::

Table 5.1 This table title#
Training	Validation
0	5
13720	2744

5.2.9. admonition#

:::{note} Notes require **no** arguments,
so content can start here.
:::

Note

Notes require no arguments, so content can start here.

:::{warning}
Warning
:::

Warning

:::{tip}
Tip
:::

Tip

:::{caution}
Caution
:::

Caution

:::{attention}
Attention
:::

Attention

:::{danger}
Danger
:::

Danger

:::{error}
Error
:::

Error

:::{hint}
hint
:::

Hint

hint

:::{important}
Important
:::

Important

:::{seealso}
see also
:::

Figure parameters#

The following options are supported:

scale : integer percentage: Uniformly scale the figure. The default is “100” which indicates no scaling. The symbol “%” is optional.
width : length or percentage: You can set the figure width in the following units: “em”, “ex”, “px”,“in” ,“cm”, “mm”, “pt”, “pc”, “%”.
height : length: You can set the figure height in the following units: “em”, “ex”, “px”, “in”, “cm”, “mm”, “pt”, “pc”.
alt : text: Text to be displayed if the figure cannot be displayed or if the reader is using assistive technologies. Generally entails a short description of the figure.
align : “left”, “center”, or “right”: Align the figure left, center, or right. Default alignment is center.
name : text: A unique identifier for your figure that you can use to reference it with {ref} or {numref} roles. Cannot contain spaces or special characters.
figclass : text: Value of the figure’s class attribute which can be used to add custom CSS or JavaScript. Predefined options include:

5.2.10. Math#

This is an example of an inline equation $z=\sqrt{x^2+y^2}$.

This is an example of an inline equation \(z=\sqrt{x^2+y^2}\).

$$z=\sqrt{x^2+y^2}$$ (mylabel)
equation ref: {eq}`mylabel`

(5.1)#\[z=\sqrt{x^2+y^2}\]

equation ref: (5.1)

5.2.11. Executable code#

```{code-cell} ipython3
note = "Python syntax highlighting"
print(note)
```

note = "Python syntax highlighting"
print(note)

Python syntax highlighting

5.2.12. Reference documents#

See {doc}`../basic/alias` for more information.

See Alias for more information.

5.2.13. Toggle#

::::{toggle}
```python
print('hello')
```
::::

print('hello')

5.2.14. Margin#

:::{margin} **My margin title**
Here is my margin content, it is pretty cool!
:::

:::{tip}
:class: margin toggle
This note will be in the margin!
:::

Tip

This note will be in the margin!

```{figure} ../basic/github/img/GitHub-flow.png
---
figclass: margin
alt: My figure text
name: myfig4
---
And here is my figure caption
```

My figure text — Fig. 5.1 And here is my figure caption#

5.2.15. Panel#

https://sphinx-design.readthedocs.io/en/latest/cards.html

```{card}
Panel header 1
^^^
Panel body 1
+++
Panel footer 1
```

Panel header 1

Panel body 1

Panel footer 1

5.2.16. Badge#

{bdg}`plain badge`
{bdg-primary}`primary` {bdg-primary-line}`primary-line`
{bdg-secondary}`secondary` {bdg-secondary-line}`secondary-line`
{bdg-success}`success` {bdg-success-line}`success-line`
{bdg-info}`info` {bdg-info-line}`info-line`
{bdg-warning}`warning` {bdg-warning-line}`warning-line`
{bdg-danger}`danger` {bdg-danger-line}`danger-line`
{bdg-light}`light` {bdg-light-line}`light-line`
{bdg-dark}`dark` {bdg-dark-line}`dark-line`

plain badge primary primary-line secondary secondary-line success success-line info info-line warning warning-line danger danger-line light light-line dark dark-line

5.2.17. Definition lists#

Term 1
: Definition

Term 2
: Definition

Term 1: Definition
Term 2: Definition

```{glossary}
Term one
  An indented explanation of term 1

A second term
  An indented explanation of term2
```

Term one#: An indented explanation of term 1
A second term#: An indented explanation of term2

```{epigraph}
Here is a cool quotation.

-- Jo the Jovyan
```

Here is a cool quotation.

—Jo the Jovyan

tabs#

ex1

````{tab-set}
```{tab-item} Tab 1 title
My first tab
```

```{tab-item} Tab 2 title
My second tab with `some code`!
```
````

Tab 1 title

My first tab

Tab 2 title

My second tab with some code!

ex2

`````{tab-set}
````{tab-item} c++

```{code-block} c++

int main(const int argc, const char **argv) {
  return 0;
}
```
````

````{tab-item} python

```{code-block} python

def main():
    return
```
````

````{tab-item} java

```{code-block} java

class Main {
    public static void main(String[] args) {
    }
}
```
````

````{tab-item} julia

```{code-block} julia

function main()
end
```
````

````{tab-item} fortran

```{code-block} fortran

PROGRAM main
END PROGRAM main
```
````
`````

c++

int main(const int argc, const char **argv) {
  return 0;
}

python

def main():
    return

java

class Main {
    public static void main(String[] args) {
    }
}

julia

function main()
end

fortran

PROGRAM main
END PROGRAM main

5.2.18. key#

To use a substitution, first add front-matter content to the top of a page like so:

---
substitutions:
  image: |
    ```{image} ../basic/github/img/GitHub-flow.png
    :alt: image
    :width: 200px
    ```
---

and use like this: {{image}}

Define substitutions for your whole book#

You can also define book-level substitution variables with the following configuration:

parse:
  myst_substitutions:
    key0: global-value

global value: global-value

Formatting substitutions#

The original key1: I’m a substitution I’m a substitution

substitutions:
  repo_url: [my repo url](https://github.com/executablebooks/jupyter-book)

5.2.19. Footnotes#

This is a footnote[^mylabel].
[^mylabel]: My footnote text.

This is a footnote[1].

5.2.20. Custom <div> blocks#

:::{div} my-class
**Some content.**
:::

Some content.

5.2.21. Check for missing references#

You can check for missing references when building a Jupyter Book. To do so, use the following options:

jupyter-book build -W -n --keep-going docs/

5.2.22. Layout#

full-width

:::{note}
:class: full-width
Here's a note that will take the full width
:::

Note

Here’s a note that will take the full width

5.2.23. Proofs, Theorems, and Algorithms#

This is not currently a default package in jupyter-book as is a relatively new package.

pip install sphinx-proof

It needs to be enabled through the _config.yml after installation.

sphinx:
  extra_extensions:
    - sphinx_proof

https://sphinx-proof.readthedocs.io/en/latest/syntax.html

Example#

:::{prf:theorem} My theorem
:nonumber:

This is my theorem.
:::

Theorem (My theorem)

This is my theorem.

:::{prf:proof} My proof

This is my proof.
:::

Proof. My proof

This is my proof.

:::{prf:remark} My remark
:nonumber:

This is my remark.
:::

Remark (My remark)

This is my remark.

5.3. Build and publish outputs#

5.3.1. Generate a badge for your book#

Additionally, you can generate a badge directly from shields.io. Here’s the URL to auto-generate the badge above, using a base64-encoded version of the Jupyter Book logo. Feel free to modify this as you wish!

5.3.2. Build a PDF using LaTeX#

Book Style PDF#

To build a PDF of your project using LaTeX, use the following command:

jupyter-book build mybookname/ --builder pdflatex [--individualpages]

or
jb build mybookname/ --builder pdflatex [--individualpages]

Note

If you would just like to generate the latex file you may use:

jb build mybookname/ --builder latex

5.3.3. Check external links in your book#

If you’d like to make sure that the links outside of your book are valid, run the Sphinx link checker with Jupyter Book. This will check each of your external links and ensure that they resolve.

Note that you must ensure each link is the right target, the link checker will only ensure that it resolves. To run the link checker, use the following command:

jupyter-book build mybookname/ --builder linkcheck

It will print the status of each link in your book so that you may resolve any incorrect links later on.

5.3.4. Configuring to Improve Accessibility#

Declaring the primary language used in your book assists screen reader and browser translation tools.

Language can be configured by providing the appropriate language code to the language option, under sphinx configuration in your _config.yml file:

sphinx:
  config:
    language: en

5.3.5. Defining TeX macros#

You can add LaTeX macros for the whole book by defining them under the Macros option of the TeX block. For example, the following macros have been pre-defined in the Sphinx configuration

sphinx:
  config                    :             # key-value pairs to directly over-ride the Sphinx configuration
    mathjax_path            : https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
                                          # By default MathJax version 2 is currently used.
                                          # If you are using a lot of math, you may want to try using version 3
                                          # , which claims to improve load speeds by 60 - 80%:
    mathjax3_config:
      loader:                             # If you want to use physics package, you need to load it and add it to the packages list below.
        load                : ['[tex]/physics']
      tex:
        packages            : { '[+]': ['physics'] }
        macros:
          "N": "\\mathbb{N}"
          "floor": ["\\lfloor#1\\rfloor", 1]
          "bmat" : ["\\left[\\begin{array}"]
          "emat" : ["\\end{array}\\right]"]

You can also define TeX macros for a specific file by introducing them at the beginning of the file under a math directive. For example

```latex
\newcommand\N{\mathbb{N}}
\newcommand\floor[1]{\lfloor#1\rfloor}
\newcommand{\bmat}{\left[\begin{array}}
\newcommand{\emat}{\end{array}\right]}
```

5.4. Reference#

Jupyter Book

MyST

Contents

5.2. MyST#

5.2.1. Heading#

Heading level 1

Heading level 2

Heading level 3

Heading level 4

Heading level 5

Heading level 6

5.2.2. Target headers#

target#

5.2.3. Quote#

5.2.4. End line#

5.2.5. Line comment#

5.2.6. Block break#

5.2.7. List#

5.2.8. Table#

5.2.9. admonition#

Figure parameters#

5.2.10. Math#

5.2.11. Executable code#

5.2.12. Reference documents#

5.2.13. Toggle#

5.2.14. Margin#

5.2.15. Panel#

5.2.16. Badge#

dropdown#

5.2.17. Definition lists#

tabs#

5.2.18. key#

Define substitutions for your whole book#

Formatting substitutions#

5.2.19. Footnotes#

5.2.20. Custom <div> blocks#

5.2.21. Check for missing references#

5.2.22. Layout#

5.2.23. Proofs, Theorems, and Algorithms#

Example#

5.3. Build and publish outputs#

5.3.1. Generate a badge for your book#

5.3.2. Build a PDF using LaTeX#

Book Style PDF#

5.3.3. Check external links in your book#

5.3.4. Configuring to Improve Accessibility#

5.3.5. Defining TeX macros#

5.4. Reference#