Elements

Elements#

Document metadata#

.. metadata::#

This directive allows adding document metadata to a page. The content of the directive is a YAML document which is converted to a Python dict and merged into the document metadata.

In addition to Sphinx-specific metadata fields, the following top-level keys are interpreted.

date

The date to use in headers and footers when printing. Defaults to the current date.

exec

A map of per-language configuration for client-side code execution.

exec:
  python:
    packages: [sqlite3]

mathjax

A map of MathJax configuration overrides.

output: The default output processor (chtml, svg). The default is svg.

mermaid

A map of config properties for mermaid diagrams.

page-break-avoid

A level or list of levels of sections in which page breaks should be avoided.

page-break-force

A level or list of levels of sections after which a page break should be forced.

print-styles

A CSS stylesheet URL to use when printing. Relative URLs are resolved relative to the _static directory. The following print stylesheets are provided:

tdoc/print.css
- Header, left: The value of the subject metadata.
- Header, right: The first-level title of the document.
- Footer, left: The site author.
- Footer, center: The page number and the total number of pages.
- Footer, right: The value of the date metadata.
tdoc/print-exam.css
- Header, left: The value of the subject metadata.
- Header, center: The first-level title of the document.
- Header, right: The value of the date metadata.
- Footer, left: The site author.
- Footer, center: The page number and the total number of pages.

scripts

A list of scripts to reference from the page header through <script> elements. The list items can be either strings (the URL of the script) or maps. For maps, the src key specifies the URL of the script, and other keys are added to the <script> element. Relative URLs are resolved relative to the _static directory.

scripts:
  - classic-script.js
  - src: module-script.js
    type: module
  - https://code.jquery.com/jquery-3.7.1.min.js

styles

A list of CSS stylesheets to reference from the page header through <link> elements. The list items can be either strings (the URL of the stylesheet) or maps. For maps, the src key specifies the URL of the stylesheet, and other keys are added to the <link> element. Relative URLs are resolved relative to the _static directory.

styles:
  - custom-styles.css
  - src: print-styles.css
    media: print
  - https://example.com/styles.css

subject

The subject covered by the document. This may be used by print stylesheets in headers or footers.

versions

A map overriding the versions of JavaScript dependencies on a page. The keys are dependency identifiers and the values can be either version numbers or full URLs. See deps.py for the list of dependencies and their default version.

versions:
  polyscript: 0.17.30
  pyodide: https://cdn.jsdelivr.net/pyodide/v0.27.7/full

Default directive options#

.. defaults:: directive#

This directive sets default options for a directive type for the current document, starting from the current location. All directives of the given type that follow the defaults block take their default option values from that block. Options that are specified in the directive itself override the default.

A document can contain multiple defaults blocks for the same directive type. Each occurrence replaces the previous one, i.e. they don't combine.

```{exec} python
# Use the directive's default options
```

```{defaults} exec
:when: load
:class: hidden
```

```{exec} python
# Use ':when: load' and ':class: hidden'
```

```{exec} python
:when: click
# Use ':when: click' and ':class: hidden'
```

```{defaults} exec
:when: never
```

```{exec} python
# Use ':when: never' and no :class:
```

Solution#

.. solution:: [title]#

This directive adds an admonition of type solution. The title defaults to "Solution", and the body is collapsed by default. The solution can be toggled by clicking on the title bar. Holding Ctrl while clicking toggles all admonitions on the page.

The solutions: key in the document metadata controls how solutions are displayed.

show (default): Solutions are shown on the page.
hide: Solutions are hidden when the page loads. They can be shown or hidden with the / button in the navbar.
dynamic: Solutions are hidden by default, but can be made visible to everyone in real-time by members of the group solutions:show using the / button.

Options

:class: name [name...] (IDs)#: A space-separated list of CSS classes to add to the admonition. The default is note dropdown.

:name: name (ID)#: A reference target for the admonition.

:expand:#: When set, the admonition is expanded by default.

:show:#: When set, the admonition is always shown, even if solutions are hidden or removed.

IFrame#

.. iframe:: url#

This directive adds an <iframe> element loading the given URL.

Options

:allow: directive; [directive; ...]#

The permission policy for the <iframe> (supported directives). The default is:

autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture;
  screen-wake-lock; web-share

:class: name [name...] (IDs)#: A space-separated list of CSS classes to add to the <iframe>.

:credentialful:#: Indicate that the <iframe> should not be loaded in credentialless mode. The default is credentialless mode.

:referrerpolicy: value#: Indicate the referrer to send when fetching the <iframe> source (supported values).

:sandbox: token [token ...]#: Control the restrictions applied to the content embedded in the <iframe> (supported tokens).

:style: property: value; [property: value; ...]#: CSS styles to apply to the <iframe>, e.g. width: 80%;.

:title: text#: A concise description of the content of the <iframe>, typically used by assistive technologies.

.. youtube:: id#: This directive adds an <iframe> element loading a YouTube video. The argument is the ID of the video, e.g. aVwxzDHniEw. All the options of iframe are supported.

Table#

.. flex-table::#

This directive defines an HTML <table> using a more flexible syntax than Markdown tables or other table directives. In particular, it allows assigning CSS classes to individual rows and cells, and allows cells to span multiple rows and / or columns. The directive content defines the content of the table, using the following syntax:

Each line of the directive content defines a row.
Each cell in a row starts with a | character.
A row can optionally start with attributes that are applied to the row. In addition to classes and identifiers, the following attributes are recognized:
- t: Determines if the row is a header row (h) or a body row (b). Consecutive header rows are grouped in a <thead>, while body rows are grouped in a <tbody>. Rows that don't specify a type use the type of the previous row. The default for the first row is b.
The content of a cell can optionally start with attributes that are applied to the cell. In addition to classes and identifiers, the following attributes are recognized:
- cols: Sets the colspan attribute of the cell tag.
- rows: Sets the rowspan attribute of the cell tag.
- t: Determines if the cell is a heading cell (h) or a data cell (d). Heading cells are rendered as <th>, and data cells are rendered as <td>. Cells that don't specify a type default to h in header rows and d in body rows.
The cell content is parsed as inline markup, i.e. it can include styling, inline math, etc. | characters within the cell content must be escaped as \|.

```{flex-table}
{t=h}|Name|Age|Shoe size
{t=b}|{t=h}Joe|23|43
     |{t=h}Jack|18|41
     |{t=h}Jim|{cols=2}unknown
```

Tables have no styling by default, but the following classes are set up in the stylesheet and can be used in the :class: option.

grid: Formats the table as a grid, using a 1px solid border on all cells. The following classes can be set on table cells:
- .l: Aligns the cell content to the left.
- .r: Aligns the cell content to the right.
function-table: Formats the table as a function value and / or sign table. The following classes can be set on table cells:
- .l: Aligns the cell content to the left.
- .r: Aligns the cell content to the right.
- .g: Applies a grey background to the cell. Typically used where the function is undefined.
- .w: Sets min-width: 5rem on the cell.

Options

:class: name [name...] (IDs)#: A space-separated list of CSS classes to add to the <table>.

:name: name (ID)#: A reference target for the table.

Elements

Contents

Elements#

Document metadata#

Default directive options#

Solution#

IFrame#

Table#