Markdown

Sections

Sections add complex elements — paragraphs, callouts, visuals — to novem markdown. This page explains the grammar and the spacing, border and colour parameters common to all sections.

AI assisted, human approved — novem uses AI to review and keep our documentation up to date.

Available in: documents and e-mails.

Sections build on the grammar introduced in the novem markdown overview. There are two fundamental kinds:

  • Single statement sections
  • Multi statement sections

The single statement section consists of a single statement and its parameters.

{{ section_type     # section open and type
  param: one        # parameters
  param: two        #
}}                  # section close

This is mostly used for things that embed other resources — visualisations, images, author blocks.

Multi statement sections consist of an opening statement followed by a closing statement later in the document. The closing statement is the same as the open statement but with a leading slash / and no parameters.

{{ section_type         # section open and type
  param: one            # parameters
  param: two            #
}}                      # closing the top, but opening the
                        # the multi section

Other text and markdown # section content
supplied by the user.
* list
* item

{{ /section_type  }}    # closing multi section tag

This is used for wrapping longer-form content — paragraphs, callouts, preview text.

Nesting sections inside each other is not supported in e-mails.

If a section needs no parameters (using the defaults), the open and close statements can be written on single lines:

{{ section_type }}
content
{{ /section_type }}

See the preview section for an example of this.

Single statement sections also support an inline syntax with comma-separated parameters on one line:

{{ vis ref: /u/demo/p/chart, width: 80%, align: left }}

All novem sections support a few common parameters for spacing, borders and colours.

Use generic padding (p) and margin (m) controls on any section. The syntax is similar to the plot table padding: a directional indicator and a magnitude between 0 and 5.

 l  -- add left padding to section
 r  -- add right padding to section
 t  -- add top padding to section
 b  -- add bottom padding to section

 x  -- add left and rigth padding to section
 y  -- add top and bottom padding to section

 a  -- add paddings to sides of the section

To supply multiple values use yaml array notation.

Add a magnitude 2 padding around a paragraph.

{{ paragraph
  padding: a2
}}

Paragraph text

{{ /paragraph }}

Add an inner padding of 3, a margin of 2 at the top and bottom along with a 1 wide top border of color gray-500 for a paragraph. Also using short forms where possible.

{{ para
  p: a3
  m: y2
  b: t1 gray-500
}}

Paragraph text

{{ /para }}

Add a padding of 1 to the left and 4 to the right.

{{ para
  p: [l1, r4]
}}

Paragraph text

{{ /para }}

The border grammar is very similar to the spacing controls above: the parameters are border, borders or b along with a direction, size and optional color code.

Add a border all around a paragraph, the inverse color will be used by default.

{{ para
  b: a1
}}

Paragraph text

{{ /para }}

Add a paragraph with red left border and green right border.

{{ para
  b: [l1 red, r1 green]
}}

Paragraph text

{{ /para }}

Foreground and background colors are supported on all sections via foreground (fg) and background (bg). Like all novem colors you can either specify a named novem color or an explicit hex code.

If you want to specifically set a dark mode variant then two colors can be supplied instead.

A paragraph with a light background with darker text and a solid outer border.

{{ para
  b: a1 inverse
  bg: gray-300
  fg: gray-800
}}

Paragraph text

{{ /para }}
Next
Paragraph