Information Boxes
Contents
Information Boxes¶
Jupyter Book implements a wealth of admonition boxes.
Warning
```{warning}
content
```
Syntax for warnings.
Note
```{note}
content
```
Syntax for notes.
Tip
```{tip}
content
```
Syntax for tips.
See also
```{seealso}
content
```
Syntax for see alsos.
You can customise these admonitions by using the generic admonition block
with a desired class (specified via the :class: parameter) and
a custom title, for example
My Custom Title
```{admonition} My Custom Title
:class: tip
content
```
A tip-based admonition with a custom title.
However, these blocks cannot be tagged and referenced by their title.
To address these shortcoming, the sphinx_prolog.infobox extension module
implements custom Information Boxes.
See also
See the Jupyter Book documentation for more details about the available admonition boxes. Other box types – such as Caution, Attention, Danger and Error – are also available.
Setup¶
To enable the sphinx_prolog.infobox extension module in your Jupyter Book,
include its name in your _config.yml file under the sphinx.extra_extensions
key.
sphinx:
extra_extensions:
# Load sphinx-prolog <https://github.com/simply-logical/sphinx-prolog>
- sphinx_prolog.infobox
See also
See the Usage section of the sphinx-prolog Extension page for more details.
Usage¶
An Information Box is inserted with an admonition-like syntax using the
infobox keyword and it has one required parameter – :title: –
used to provide its title.
A Custom Information Box¶
```{infobox}
:title: The Information Box Title
The Information Box content.
```
Assign a Title¶
Each Information Box requires a title, which is provided via the
:title: parameter – see the example above.
By hovering your mouse over the title section of an Information Box
(the blue-coloured bar at the top), a hyper-link marker (¶) will be revealed
to the right of the title text.
By clicking it you will get a link pointing directly to this Information Box.
Tag and Reference¶
In addition to the external links provided under the hyper-link markers (¶),
the Information Boxes can be easily tagged and referenced within the book.
To tag a box place your tag string directly after the box opening statement,
e.g., ```{infobox} ibox:my-tag.
The Information Box tags must be prefixed with ibox:.
Another Custom Information Box¶
```{infobox} ibox:my-tag
:title: The Title of Another Information Box
The content of another Information Box.
```
You can then reference your tagged Information Boxes anywhere in your book.
This is achieved with the {ref}`ibox:my-tag` syntax.
In the built book such command will be replaced with a title of the
referenced Information Box hyper-linked to its location.
For example, referencing the first Information Box gives A Custom Information Box,
and the second produces Another Custom Information Box.
If you prefer to assign a custom text to your hyper-link, there is a syntax for
that as well: {ref}`Custom Text <ibox:my-tag>`.
For example, the first Information Box can be referenced as
Custom Reference to the First Box.
See also
For more information, see the referencing overview available in the Jupyter Book documentation.
See also
For more information about the Information Box module see its technical documentation.