Layout components¶

The sphinx-design extension adds layout components to a page: grids of cards, cards, dropdowns, tabs and buttons. ubCode renders them natively, with nothing to install, in the editor preview and in its html and pdf builds; its html build writes the same sd-* classes a sphinx-design build does. Its badge roles are with the other roles, in Badges. How ubCode’s components look and behave differently from a sphinx-design build is in the sphinx-design differences.

Grids¶

A grid lays its items out in columns. Its argument gives the number of columns, either one number for every screen width or four, for extra-small, small, medium and large screens. Each item is a grid-item, or a grid-item-card, which is a card filling its column. :gutter: sets the space between the items, from 0 to 5. An :octicon: role draws one of the icons sphinx-design ships, here in a card title.

reStructuredText

Grids

.. grid:: 1 2 2 2
   :gutter: 2

   .. grid-item-card:: :octicon:`book` Read

      Read the specification first.

   .. grid-item-card:: :octicon:`pencil` Write

      Then write the requirement.

   .. grid-item::

      A plain item, with no card around it.

Read

Read the specification first.

Write

Then write the requirement.

A plain item, with no card around it.

MyST

`````{grid} 1 2 2 2
:gutter: 2

````{grid-item-card} Read
{octicon}`book` Read the specification first.
````

````{grid-item-card} Write
{octicon}`pencil` Then write the requirement.
````

````{grid-item}
A plain item, with no card around it.
````
`````

The MyST form renders live in the MyST grids.

ubCode reads a card’s title as reStructuredText on a MyST page too, where a sphinx-design build reads it as MyST, so the MyST form keeps its icons out of the titles.

Cards¶

A card is a box with an optional title (its argument), a body, and a footer after a line of exactly three + and a blank line. :link: makes the whole card a link: to a URL, or with :link-type: (ref, doc or any) to a label or a page. :shadow: (none, sm, md or lg) and :width: (25%, 50%, 75%, 100% or auto) shape it.

reStructuredText

Cards

.. card:: Layout components
   :link: authoring:design
   :link-type: ref
   :shadow: md

   The whole card links to the top of this page.

   +++

   A footer, after the line of three plus signs.

Layout components

The whole card links to the top of this page.

A footer, after the line of three plus signs.

Layout components

MyST

````{card} Layout components
:link: authoring:design
:link-type: ref
:shadow: md

The whole card links to the top of this page.

+++

A footer, after the line of three plus signs.
````

The MyST form renders live in the MyST cards.

A card header, which sphinx-design writes after a line of ^^^, is not read by ubCode yet, and ubCode’s own card-header directive is not one a Sphinx build knows (see the sphinx-design differences).

Dropdowns¶

A dropdown is a titled box that the reader opens and closes. :open: starts it open, :color: colours its title bar with one of the colour names the badge roles take (info, warning, …), and :icon: puts an octicon before the title.

reStructuredText

Dropdowns

.. dropdown:: Before you begin
   :open:
   :color: info
   :icon: info

   Check that the project builds.

.. dropdown:: Closed until the reader opens it

   Further detail.

MyST

```{dropdown} Before you begin
:open:
:color: info
:icon: info

Check that the project builds.
```

```{dropdown} Closed until the reader opens it
Further detail.
```

The MyST form renders live in the MyST dropdowns.

Note

A page in the PDF cannot fold, so ubc build pdf prints every dropdown open.

Tabs¶

A tab-set holds tab-item directives, each one a tab whose argument is its label. :selected: chooses the tab shown first. Tabs with the same :sync: key, in sets with the same :sync-group:, are chosen together: the reader’s choice in one set selects the same tab in the others, as it does for the reStructuredText and MyST tabs of this reference.

reStructuredText

Tabs

.. tab-set::
   :sync-group: ex-design-os

   .. tab-item:: Linux
      :sync: linux

      Install with ``apt``.

   .. tab-item:: Windows
      :sync: windows
      :selected:

      Install with ``winget``.

Linux

Install with apt.

Windows

Install with winget.

MyST

`````{tab-set}
:sync-group: ex-design-os

````{tab-item} Linux
:sync: linux

Install with `apt`.
````

````{tab-item} Windows
:sync: windows
:selected:

Install with `winget`.
````
`````

The MyST form renders live in the MyST tabs.

Note

A page in the PDF cannot switch tabs, so ubc build pdf prints every tab, one after another, under its label.

The other tab options, and how ubCode switches tabs, are in Tabs.

Buttons¶

button-link is a link to a URL drawn as a button, and button-ref a link to a label (or, with :ref-type: doc, a page). The body is the button’s text. :color: colours it, :outline: draws only its outline, and :expand: stretches it across the column.

reStructuredText

Buttons

.. button-link:: https://sphinx-design.readthedocs.io
   :color: primary

   The sphinx-design documentation

.. button-ref:: authoring:design
   :ref-type: ref
   :color: secondary
   :outline:

   Back to the top of this page

The sphinx-design documentation

Back to the top of this page

MyST

```{button-link} https://sphinx-design.readthedocs.io
:color: primary

The sphinx-design documentation
```

```{button-ref} authoring:design
:ref-type: ref
:color: secondary
:outline:

Back to the top of this page
```

The MyST form renders live in the MyST buttons.

Plain blocks with design classes¶

div wraps its body in a block whose classes are its argument, for sphinx-design’s utility classes, such as sd-text-center or sd-border-1.

reStructuredText

Plain blocks with design classes

.. div:: sd-text-center sd-border-1 sd-p-2

   A centred paragraph in a bordered block.

A centred paragraph in a bordered block.

MyST

```{div} sd-text-center sd-border-1 sd-p-2
A centred paragraph in a bordered block.
```

The MyST form renders live in the MyST plain blocks.