The manual's own tools

codemode#

Markup that stands in the page as its author wrote it. The body is HTML, and the theme passes it through. It takes no argument and no option.

.. codemode::

   <sds-note tone="info" heading="Written as markup">
     The theme passes this block through as it is.
   </sds-note>

It is the way out, not the way in. The gate checks a directive that draws the element: its options, its names, its twin. Nothing checks the markup here. The Markdown twin prints the block as fenced HTML.

example#

What the author wrote, and under it what it renders as, out of one body.

.. example:: A press, and where it goes

   .. button:: :doc:`/guides-theme/installation`
      :icon: actions-download

.. button:: :doc:`/guides-theme/installation`
   :icon: actions-download

The block a reader copies is the block that ran. A page that prints markup in a code-block and writes it a second time to render it holds two copies of one example. The copy nobody checks is the one the reader takes away. Here the print is the lines the parser got, and the render comes from those same lines, so the two cannot part. specimen below does that for a card, a level up.

The frame has a dashed line, the only one in the system. That is what it is for. A solid one is a box on the page. What is inside this one is not part of the page: a thing shown, at the end of a run of things read. It is .sds-example, and it has no fill either. So a card or a surface in it stands on its real ground, not on a plane the manual put under it.

The options are not in the print, because the parser has taken them off the body by the time the directive sees it.

What an example cannot show is a page. The frame is a box in the column. So a band inside one is the section a band is on a manual page, not the full-bleed ground of a marketing one. That is what the band in The shape of a page is in an example to show.

What follows a band belongs to it only where the page is bands. So a source that opens two of them renders here as two sections with the text loose between them. That one stays a code-block beside prose that says so. :layout: is a field, not a directive, and has nowhere to go in a body.

specimen#

A rendered card, at the size of its drawing.

.. specimen:: guidelines/colors-surfaces.card.html
   :viewport: 700x338
   :title: Surfaces

The frame is an sds-embed, the element in Media, fixed at the viewport above. Where the column is narrower the card scales down whole, and does not reflow into a width nothing measured. Core markup, and what it becomes has the other half of that node: a video, the same directive's opposite, which fills the column instead.

The cards have to be inside the documentation source. The renderer copies an asset a document points at and nothing else. This repository's make guides copies specimens/ into docs/_cards/ before each render and rewrites the stylesheet links inside each card on the way. That directory is a task's output, and git ignores it.