Extensions

This section describes various Markdown features that are less common, such as footnotes, and in some cases Markdown features that are specific to the UCC web site.

Footnotes

Footnotes can also be added to pages:

Batteries[^bats] included.

[^bats]: Batteries not actually included.

Multiple references can be made to the same footnote[^bats]. Using short, unique names is preferable to numbers; they are replaced by numbers in the resulting page, and are automatically ordered correctly.

Divisions

A custom syntax allows <div> elements containing Markdown to be used:

::: .my-css-class
Paragraph one.

- One.
- Two.
:::

The .my-css-class becomes a CSS class and can be referenced in a stylesheet (described in the next section) to style the block:

.my-css-class
{
  transform: rotate(10deg);
}
.my-other-class
{
  transform: rotate(-20deg);
}

Nesting is possible:

::: .my-css-class
Paragraph one.

::: .my-other-class
Paragraph two.
:::

:::

Custom Styles

To define a custom stylesheet, add a @style directive giving the URL of the stylesheet. For example, if you have:

• /services/lart.ucc, and,
• /services/lart.css

You can reference the style with:

@style lart.css

If you have multiple stylesheets, place each on a different @style line:

@style golden-lart.css
@style ../lart-section.css

It's best to keep styles close to the .ucc files they're used by, instead of cluttering up a single styles directory with files that are only used by a sub-section of the site.

Directives

To set some options on .ucc files, Kondo also supports directives such as:

@title My Document
@plugin convert-to-pig-latin

# Hello, world!

This is a new document!

The directive parser is quite simple, and to avoid having to parse every line in large documents it expects that all directives are at the top of the file, with a blank line following the last directive to indicate the start of Markdown. Directives in the middle of a document are ignored, and will end up being visible.

Including Other Files

Sometimes you might want to publish some file that normally lives elsewhere in /services, or in some other filesystem the web server typically has mounted. You can do this with:

@body /home/other/committee/agenda.md

The file will need read permissions for at least the webmasters group, and since the file can be anywhere on the file system, care should be taken not to expose files that may in the future contain anything sensitive.

If you happen to be using @html, the included file will also need to be HTML.

Also, only one @body directive is supported, and all but the last one seen will be ignored.

If the file needs some processing or formatting before inclusion, use the plugin system described in the next section.