Section Lists

The section codeblock markup makes it possible for you to add a list of links to pages in a content section with their summary to provide context for those pages.

When used, it inserts a <div> element containing a description list (<dl>) with each page defined as a term (<dt>) with the page’s link and definition (<dd>) with the page’s summary rendered from Markdown. Optionally, the div can include leading rendered Markdown, either defined in the codeblock or pulled from the section page itself.

Syntax #

With Attributes #

```section { [.class [.class]] [#id] }
Markdown Content summarizing section.
```

With Data #

```section
---
class: class
id: id
recurse: false
root: root
use_summary: false
---

Markdown Content summarizing section.
```

Examples #

1. Minimal Example #

Technically, this isn’t the most minimal example. That would actually be:

```section
```

However, this documentation page doesn’t have any children, so that won’t render correctly. Instead, these examples all use the root option to set the section so they’ll actually render something.

Markdown Input

```section
---
root: /modules/platen/markup
---
```

HTML Output

<div class="platen-section">
  <dl>
    <dt>
      <a href="/modules/platen/markup/alerts/">
        Alerts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on adding alerts to your content with a codeblock.
    </dd>
    <dt>
      <a href="/modules/platen/markup/art/">
        Art
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on adding artwork to your content with an image link.
    </dd>
    <dt>
      <a href="/modules/platen/markup/buttons/">
        Buttons
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>button</code> image link markup, which renders an image link as a button.
    </dd>
    <dt>
      <a href="/modules/platen/markup/columns/">
        Columns
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>columns</code> language ID for codeblocks, which enables you to format content in multiple columns on a page.
    </dd>
    <dt>
      <a href="/modules/platen/markup/details/">
        Details
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>details</code> language ID for codeblocks, which adds a details and summary HTML tag to a Markdown page for semantically collapsible content.
    </dd>
    <dt>
      <a href="/modules/platen/markup/itch/">
        Itch Embeds
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>itch</code> image link markup, which embeds an iframe linking to the itch page for a project.
    </dd>
    <dt>
      <a href="/modules/platen/markup/katex/">
        KaTeX Formulas
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on using math markup to include formulas in your text.
    </dd>
    <dt>
      <a href="/modules/platen/markup/mermaid/">
        Mermaid Diagrams
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>mermaid</code> language ID for codeblocks, which renders Mermaid markup on a content page, allowing you to include flowcharts and other diagrams.
    </dd>
    <dt>
      <a href="/modules/platen/markup/section/">
        Section Lists
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>section</code> language ID for codeblocks, which adds a list of links to pages in a content section with their summary to provide context for those pages.
    </dd>
    <dt>
      <a href="/modules/platen/markup/styled_text/">
        Styled Text
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>styled</code> image link markup, which renders an image link&rsquo;s text as a styled span.
    </dd>
    <dt>
      <a href="/modules/platen/markup/subscripts/">
        Subscripts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>sub</code> image link markup, which renders an image link&rsquo;s text as subscript.
    </dd>
    <dt>
      <a href="/modules/platen/markup/superscripts/">
        Superscripts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>sup</code> image link markup, which renders an image link&rsquo;s text as superscript.
    </dd>
    <dt>
      <a href="/modules/platen/markup/tabs/">
        Tabs
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>tabs</code> language ID for codeblocks, which enables you to format content as tabs in a card pane on a page.
    </dd>
</dl>
</div>

Rendered Output

Alerts: Documentation on adding alerts to your content with a codeblock.
Art: Documentation on adding artwork to your content with an image link.
Buttons: Documentation on the button image link markup, which renders an image link as a button.
Columns: Documentation on the columns language ID for codeblocks, which enables you to format content in multiple columns on a page.
Details: Documentation on the details language ID for codeblocks, which adds a details and summary HTML tag to a Markdown page for semantically collapsible content.
Itch Embeds: Documentation on the itch image link markup, which embeds an iframe linking to the itch page for a project.
KaTeX Formulas: Documentation on using math markup to include formulas in your text.
Mermaid Diagrams: Documentation on the mermaid language ID for codeblocks, which renders Mermaid markup on a content page, allowing you to include flowcharts and other diagrams.
Section Lists: Documentation on the section language ID for codeblocks, which adds a list of links to pages in a content section with their summary to provide context for those pages.
Styled Text: Documentation on the styled image link markup, which renders an image link’s text as a styled span.
Subscripts: Documentation on the sub image link markup, which renders an image link’s text as subscript.
Superscripts: Documentation on the sup image link markup, which renders an image link’s text as superscript.
Tabs: Documentation on the tabs language ID for codeblocks, which enables you to format content as tabs in a card pane on a page.

2. Recursive Section #

This example renders the list of pages for the Platen’s markup recursively, adding a nested description list for each folder, like the KaTeX markup folder.

Markdown Input

```section
---
root:    /modules/platen/markup
recurse: true
---
```

HTML Output

<div class="platen-section">
  <dl>
    <dt>
      <a href="/modules/platen/markup/alerts/">
        Alerts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on adding alerts to your content with a codeblock.
    </dd>
    <dt>
      <a href="/modules/platen/markup/art/">
        Art
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on adding artwork to your content with an image link.
    </dd>
    <dt>
      <a href="/modules/platen/markup/buttons/">
        Buttons
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>button</code> image link markup, which renders an image link as a button.
    </dd>
    <dt>
      <a href="/modules/platen/markup/columns/">
        Columns
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>columns</code> language ID for codeblocks, which enables you to format content in multiple columns on a page.
    </dd>
    <dt>
      <a href="/modules/platen/markup/details/">
        Details
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>details</code> language ID for codeblocks, which adds a details and summary HTML tag to a Markdown page for semantically collapsible content.
    </dd>
    <dt>
      <a href="/modules/platen/markup/itch/">
        Itch Embeds
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>itch</code> image link markup, which embeds an iframe linking to the itch page for a project.
    </dd>
    <dt>
      <a href="/modules/platen/markup/katex/">
        KaTeX Formulas
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on using math markup to include formulas in your text.
      <dl>
        <dt>
          <a href="/modules/platen/markup/katex/block/">
            Block KaTeX
          </a>
        </dt>
        <dd class="markdown-inner">
          Documentation on the <code>katex</code> language ID for codeblocks, which renders math markup on a content page, allowing you to include formulas and other advanced representations.
        </dd>
        <dt>
          <a href="/modules/platen/markup/katex/inline/">
            Inline KaTeX
          </a>
        </dt>
        <dd class="markdown-inner">
          Documentation on the <code>katex</code> image link markup, which renders math markup in the alt text of an image link on a content page, allowing you to include formulas and other advanced representations.
        </dd>
      </dl>
    </dd>
    <dt>
      <a href="/modules/platen/markup/mermaid/">
        Mermaid Diagrams
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>mermaid</code> language ID for codeblocks, which renders Mermaid markup on a content page, allowing you to include flowcharts and other diagrams.
    </dd>
    <dt>
      <a href="/modules/platen/markup/section/">
        Section Lists
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>section</code> language ID for codeblocks, which adds a list of links to pages in a content section with their summary to provide context for those pages.
    </dd>
    <dt>
      <a href="/modules/platen/markup/styled_text/">
        Styled Text
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>styled</code> image link markup, which renders an image link&rsquo;s text as a styled span.
    </dd>
    <dt>
      <a href="/modules/platen/markup/subscripts/">
        Subscripts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>sub</code> image link markup, which renders an image link&rsquo;s text as subscript.
    </dd>
    <dt>
      <a href="/modules/platen/markup/superscripts/">
        Superscripts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>sup</code> image link markup, which renders an image link&rsquo;s text as superscript.
    </dd>
    <dt>
      <a href="/modules/platen/markup/tabs/">
        Tabs
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>tabs</code> language ID for codeblocks, which enables you to format content as tabs in a card pane on a page.
    </dd>
</dl>
</div>

Rendered Output

Alerts

Documentation on adding alerts to your content with a codeblock.

Art

Documentation on adding artwork to your content with an image link.

Buttons

Documentation on the button image link markup, which renders an image link as a button.

Columns

Documentation on the columns language ID for codeblocks, which enables you to format content in multiple columns on a page.

Details

Documentation on the details language ID for codeblocks, which adds a details and summary HTML tag to a Markdown page for semantically collapsible content.

Itch Embeds

Documentation on the itch image link markup, which embeds an iframe linking to the itch page for a project.

KaTeX Formulas

Documentation on using math markup to include formulas in your text.

Block KaTeX: Documentation on the katex language ID for codeblocks, which renders math markup on a content page, allowing you to include formulas and other advanced representations.
Inline KaTeX: Documentation on the katex image link markup, which renders math markup in the alt text of an image link on a content page, allowing you to include formulas and other advanced representations.

Mermaid Diagrams

Documentation on the mermaid language ID for codeblocks, which renders Mermaid markup on a content page, allowing you to include flowcharts and other diagrams.

Section Lists

Documentation on the section language ID for codeblocks, which adds a list of links to pages in a content section with their summary to provide context for those pages.

Styled Text

Documentation on the styled image link markup, which renders an image link’s text as a styled span.

Subscripts

Documentation on the sub image link markup, which renders an image link’s text as subscript.

Superscripts

Documentation on the sup image link markup, which renders an image link’s text as superscript.

Tabs

Documentation on the tabs language ID for codeblocks, which enables you to format content as tabs in a card pane on a page.

3. With Section’s Summary as Lead #

This example renders the list of pages for this section, adding the section’s own summary as leading text before the list of child pages.

Markdown Input

```section
---
root:        /modules/platen/markup
use_summary: true
---
```

HTML Output

<div class="platen-section">  <p>Documentation on the special markup Platen uses.</p>
  <dl>
    <dt>
      <a href="/modules/platen/markup/alerts/">
        Alerts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on adding alerts to your content with a codeblock.
    </dd>
    <dt>
      <a href="/modules/platen/markup/art/">
        Art
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on adding artwork to your content with an image link.
    </dd>
    <dt>
      <a href="/modules/platen/markup/buttons/">
        Buttons
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>button</code> image link markup, which renders an image link as a button.
    </dd>
    <dt>
      <a href="/modules/platen/markup/columns/">
        Columns
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>columns</code> language ID for codeblocks, which enables you to format content in multiple columns on a page.
    </dd>
    <dt>
      <a href="/modules/platen/markup/details/">
        Details
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>details</code> language ID for codeblocks, which adds a details and summary HTML tag to a Markdown page for semantically collapsible content.
    </dd>
    <dt>
      <a href="/modules/platen/markup/itch/">
        Itch Embeds
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>itch</code> image link markup, which embeds an iframe linking to the itch page for a project.
    </dd>
    <dt>
      <a href="/modules/platen/markup/katex/">
        KaTeX Formulas
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on using math markup to include formulas in your text.
    </dd>
    <dt>
      <a href="/modules/platen/markup/mermaid/">
        Mermaid Diagrams
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>mermaid</code> language ID for codeblocks, which renders Mermaid markup on a content page, allowing you to include flowcharts and other diagrams.
    </dd>
    <dt>
      <a href="/modules/platen/markup/section/">
        Section Lists
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>section</code> language ID for codeblocks, which adds a list of links to pages in a content section with their summary to provide context for those pages.
    </dd>
    <dt>
      <a href="/modules/platen/markup/styled_text/">
        Styled Text
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>styled</code> image link markup, which renders an image link&rsquo;s text as a styled span.
    </dd>
    <dt>
      <a href="/modules/platen/markup/subscripts/">
        Subscripts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>sub</code> image link markup, which renders an image link&rsquo;s text as subscript.
    </dd>
    <dt>
      <a href="/modules/platen/markup/superscripts/">
        Superscripts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>sup</code> image link markup, which renders an image link&rsquo;s text as superscript.
    </dd>
    <dt>
      <a href="/modules/platen/markup/tabs/">
        Tabs
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>tabs</code> language ID for codeblocks, which enables you to format content as tabs in a card pane on a page.
    </dd>
</dl>
</div>

Rendered Output

Documentation on the special markup Platen uses.

Alerts: Documentation on adding alerts to your content with a codeblock.
Art: Documentation on adding artwork to your content with an image link.
Buttons: Documentation on the button image link markup, which renders an image link as a button.
Columns: Documentation on the columns language ID for codeblocks, which enables you to format content in multiple columns on a page.
Details: Documentation on the details language ID for codeblocks, which adds a details and summary HTML tag to a Markdown page for semantically collapsible content.
Itch Embeds: Documentation on the itch image link markup, which embeds an iframe linking to the itch page for a project.
KaTeX Formulas: Documentation on using math markup to include formulas in your text.
Mermaid Diagrams: Documentation on the mermaid language ID for codeblocks, which renders Mermaid markup on a content page, allowing you to include flowcharts and other diagrams.
Section Lists: Documentation on the section language ID for codeblocks, which adds a list of links to pages in a content section with their summary to provide context for those pages.
Styled Text: Documentation on the styled image link markup, which renders an image link’s text as a styled span.
Subscripts: Documentation on the sub image link markup, which renders an image link’s text as subscript.
Superscripts: Documentation on the sup image link markup, which renders an image link’s text as superscript.
Tabs: Documentation on the tabs language ID for codeblocks, which enables you to format content as tabs in a card pane on a page.

4. With Custom Summary as Lead #

This example renders the list of pages for this section, adding the Markdown defined after the options block as leading text before the list of child pages.

Markdown Input

```section
---
root: /modules/platen/markup
---

The Markdown render hooks enable you to write more normal Markdown to
render HTML that Markdown doesn't directly support, like columns and
tabs.
```

HTML Output

<div class="platen-section">
  <dl>
    <dt>
      <a href="/modules/platen/markup/alerts/">
        Alerts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on adding alerts to your content with a codeblock.
    </dd>
    <dt>
      <a href="/modules/platen/markup/art/">
        Art
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on adding artwork to your content with an image link.
    </dd>
    <dt>
      <a href="/modules/platen/markup/buttons/">
        Buttons
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>button</code> image link markup, which renders an image link as a button.
    </dd>
    <dt>
      <a href="/modules/platen/markup/columns/">
        Columns
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>columns</code> language ID for codeblocks, which enables you to format content in multiple columns on a page.
    </dd>
    <dt>
      <a href="/modules/platen/markup/details/">
        Details
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>details</code> language ID for codeblocks, which adds a details and summary HTML tag to a Markdown page for semantically collapsible content.
    </dd>
    <dt>
      <a href="/modules/platen/markup/itch/">
        Itch Embeds
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>itch</code> image link markup, which embeds an iframe linking to the itch page for a project.
    </dd>
    <dt>
      <a href="/modules/platen/markup/katex/">
        KaTeX Formulas
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on using math markup to include formulas in your text.
    </dd>
    <dt>
      <a href="/modules/platen/markup/mermaid/">
        Mermaid Diagrams
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>mermaid</code> language ID for codeblocks, which renders Mermaid markup on a content page, allowing you to include flowcharts and other diagrams.
    </dd>
    <dt>
      <a href="/modules/platen/markup/section/">
        Section Lists
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>section</code> language ID for codeblocks, which adds a list of links to pages in a content section with their summary to provide context for those pages.
    </dd>
    <dt>
      <a href="/modules/platen/markup/styled_text/">
        Styled Text
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>styled</code> image link markup, which renders an image link&rsquo;s text as a styled span.
    </dd>
    <dt>
      <a href="/modules/platen/markup/subscripts/">
        Subscripts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>sub</code> image link markup, which renders an image link&rsquo;s text as subscript.
    </dd>
    <dt>
      <a href="/modules/platen/markup/superscripts/">
        Superscripts
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>sup</code> image link markup, which renders an image link&rsquo;s text as superscript.
    </dd>
    <dt>
      <a href="/modules/platen/markup/tabs/">
        Tabs
      </a>
    </dt>
    <dd class="markdown-inner">
      Documentation on the <code>tabs</code> language ID for codeblocks, which enables you to format content as tabs in a card pane on a page.
    </dd>
</dl>
</div>

Rendered Output

Alerts: Documentation on adding alerts to your content with a codeblock.
Art: Documentation on adding artwork to your content with an image link.
Buttons: Documentation on the button image link markup, which renders an image link as a button.
Columns: Documentation on the columns language ID for codeblocks, which enables you to format content in multiple columns on a page.
Details: Documentation on the details language ID for codeblocks, which adds a details and summary HTML tag to a Markdown page for semantically collapsible content.
Itch Embeds: Documentation on the itch image link markup, which embeds an iframe linking to the itch page for a project.
KaTeX Formulas: Documentation on using math markup to include formulas in your text.
Mermaid Diagrams: Documentation on the mermaid language ID for codeblocks, which renders Mermaid markup on a content page, allowing you to include flowcharts and other diagrams.
Section Lists: Documentation on the section language ID for codeblocks, which adds a list of links to pages in a content section with their summary to provide context for those pages.
Styled Text: Documentation on the styled image link markup, which renders an image link’s text as a styled span.
Subscripts: Documentation on the sub image link markup, which renders an image link’s text as subscript.
Superscripts: Documentation on the sup image link markup, which renders an image link’s text as superscript.
Tabs: Documentation on the tabs language ID for codeblocks, which enables you to format content as tabs in a card pane on a page.

Attributes #

`class` #

Specify a string for the class attribute of the containing <div>. By default, it has no class. For more information about styling the list, see Styling.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

`id` #

Specify an ID to use for the containing <div>. With an ID, it’s easier to link to the section list. By default, it has no ID.

Specify the ID as a bare string without any spaces and with a # prefix, like #my-id

Required: false
Type: String

YAML Options #

`class` #

Specify a string for the class attribute of the containing div element. By default, it has no class. For more information about styling the list, see Styling.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

`id` #

Specify an ID to use for the containing <div>. With an ID, it’s easier to link to the section list. By default, it has no ID.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

`root` #

Specify a URL to a page for use as the section root. If that page has children, Platen renders a description list linking to and describing those pages. By default, Platen uses the current page as the section root.

If this value doesn’t have a leading slash (/), Platen treats the URL as relative to the current page. For example, from page https://platen.io/foo, Platen would look for a value bar/baz as https://platen.io/foo/bar/baz but would look for /bar/baz as https://platen.io/bar/baz.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

`recurse` #

Specify whether the list should recurse for child pages, adding nested description lists for any child pages that have their own children. The default value is false.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

`use_summary` #

Specify whether you want to use the section page’s own summary as lead copy for the section’s rendered block. If the definition for the code block includes any text after the options block, this option is ignored.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

Definition #

Specify the text you want to include as lead copy in the div before the description list. You can include any valid Markdown, including other codeblocks. To use nested codeblocks, you must have more backticks (`) in the fence for the section codeblock than any of the nested codeblocks.

Styling #

By default, the containing div has the platen-section class. The only styling applied to the list is to ensure that nested description lists (<dl> elements) are indented.

This style is applied from assets/styles/markdown/_section.scss.

You can use the following selectors to control how the elements are rendered.

The Section Container #

div.platen-section {
  // CSS for the whole container
}

Use this selector to contain all other selectors to ensure your styles apply to the HTML rendered from this markup and don’t affect anything else.

To target a specific class of your own, add it to this selector. For example, to style sections with the deprecated class:

div.platen-section.deprecated {
  // All CSS in this block applies only to sections with the
  // 'deprecated' class. You can overwrite or extend the default
  // styling this way.
}

Description List #

div.platen-section {
  > dl {
    // CSS for the top-level list
  }
  dl {
    // CSS for both the top-level and nested lists
  }

  dd dl {
      // CSS for only the nested lists
  }
}

Use the > dl selector to target the top-level list specifically. Use the dl selector to target all description lists in the section container. Use the dd dl selector to target nested description lists only.

Terms #

div.platen-section {
  dt {
    // CSS for terms in both the top-level and nested lists
    a {
      // CSS for the links in terms
    }
  }
}

Use the dt selector to target the terms in the description lists. Use the a selector nested inside the dt selector to target the links inside the terms.

Definitions #

div.platen-section {
  dd {
    // CSS for definitions in both the top-level and nested lists.
  }
}

Use the dd selector to target the definitions in the description lists.

Syntax #

With Attributes #

With Data #

Examples #

1. Minimal Example #

2. Recursive Section #

3. With Section’s Summary as Lead #

4. With Custom Summary as Lead #

Attributes #

class #

id #

YAML Options #

class #

id #

root #

recurse #

use_summary #

Definition #

Styling #

The Section Container #

Description List #

Terms #

Definitions #

`class` #

`id` #

`class` #

`id` #

`root` #

`recurse` #

`use_summary` #