Fences

Fences contain lines that are not parsed for block or inline markup, allowing you to write content without escaping.

Notes

  • A fence begins with an indented line that starts with [[[. The leading indent before the fence delimiter is significant, as if the first line of the contained content had that indent.

  • The line with the opening fence delimiter may have additional content, which is processed as if it were on its own line.

  • A fence ends with a line that contains only ]]], possibly with leading and trailing whitespace.

  • As a special case, if the line containing the fence delimiter ends with ]]], it is a single-line fence. Except for single-line fences, closing fence delimiters must not have content before them.

Examples

Use a fence to avoid having to escape characters:

[code]
  [[[
  [Desktop Entry]
  Name=Help
  Exec=yelp %u
  ]]]

The fence content doesn’t have to be indented as long as the opening delimiter is correctly indented:

[code]
  [[[
[Desktop Entry]
Name=Help
Exec=yelp %u
]]]

Or, use a fence on a single line:

[code]
  [[[[Desktop Entry]]]]
  Name=Help
  Exec=yelp %u

Specification

Fences may appear anywhere block content is expected.

A fence begins with an indented line that starts with [[[. The leading indent before the opening delimiter is taken as the outer indent of the fence. This indentation is significant. The content of the fence is inserted at the same depth as if its lines all had that leading indent.

The line containing the opening fence delimiter may have additional content. If it contains non-whitespace content, then everything after the fence delimiter, including whitespace between the fence delimiter and the non-whitespace content, is taken as the first line of the fence. Otherwise, the line after the opening fence delimiter is the first line.

A fence ends with a line that contains only ]]], possibly with leading or trailing whitespace. The line with the closing fence delimiter does not add any content to the fence.

Additionally, if the line with the opening fence delimiter ends with ]]] and a newline, then that is the closing fence delimiter. The content between the opening and closing delimiters, along with a newline, is taken as a single-line fence. Single-line fences are the only case where there may be other content on the line with the closing fence delimiter.

Lines within the fence do not need to be indented to the outer indent of the fence. The fence itself keeps the content correctly nested. However, the writer may choose to indent the fence content, and the indentation will be trimmed to the trim level, computed as follows:

  • If the fence is a single-line fence, or if the first line of the fence was on the same line as the opening fence delimiter, then the trim level is 0.

  • Otherwise, if the indent level of the first line is less than the outer indent of the fence, then the trim level is the indent level of the first line.

  • Otherwise, the trim level is the outer indent of the fence.

Each line within the fence will have at most the trim level of spaces trimmed from the beginning of the line. Any line with fewer than that number of leading spaces will simply have all leading space removed.

No block or inline parsing is done within a fence. The only syntax that is recognized within a fence is the closing fence marker ]]].

© 2017-2019 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard