Click or drag to resize
Fenced Code

This topic details the AMDL syntax and semantics of fenced code blocks.

Function

TBD

Syntax

Two fenced code block syntaxes are defined:

1. Backtick Code Block:

  1. a line consisting of

    1. n ` (backtick) characters, where n ≥ 3, followed by,

    2. optionally, a language value, followed by,

    3. optionally, an attribute enclosure;

  2. fenced code, consisting of any number of lines, where each line

    1. does not start with l ` characters where l ≥ n;

  3. a line starting with m ` characters where m ≥ n.

2. Tilde Code Block:

  1. a line consisting of

    1. n ~ (tilde) characters, where n ≥ 3, followed by,

    2. optionally, a language value, followed by,

    3. optionally, an attribute enclosure;

  2. fenced code, consisting of any number of lines, where each line

    1. does not start with l ~ characters where l ≥ n;

  3. a line starting with m ~ characters where m ≥ n.

Example
AMDL
Copy
``` First example
Backtick code block
```

~~~ Second example
Tilde code block
~~~
Example Output
First example
Copy
Backtick code block
Second example
Copy
Tilde code block
Attributes

Fenced code attributes maybe specified using the following syntax:

{#identifier .class1 .class2 name1="value1" name2="value2" ...}

The following attributes are defined:

identifier

  • a string value used for resolving links to the block. If no value is specified, a unique identifier will be derived from:

    1. the value of the title attribute, or

    2. the value of the language attribute, or

    3. code.

class

  • any of the following:

    • language - equivalent to specifying language="language".

    • command - the content will be rendered as a command (no inner formatting allowed).

    • noRegionMarkers - equivalent to specifying noRegionMarkers="true".

    • numberLines - equivalent to specifying numberLines="true".

    • keepSeeTags - equivalent to specifying keepSeeTags="true".

language

  • one of the following:

    • C

    • C++ or cpp

    • C# or CSharp

    • F# or FSharp

    • JavaScript or js

    • HTML or XML or XSL

    • PowerShell

    • Python

    • SQL

    • VB.NET

    If no value is specified, the trailing content of the block's opening line shall be used.

title

  • a string value to be used as the block's caption. If no value is specified, the value of the language attribute shall be used.

source

  • a string value specifying the path to the file the code block's content should be extracted from. If a value is specified, the code block's contents shall be ignored.

region

  • a string value specifying the name of the region the code block's content should be extracted from. If no value is specified, the entire file contents shall be imported.

noRegionMarkers

  • a Boolean value indicating whether the #region and #endregion tags should be excluded from the extracted content. If no value is specified, the #region and #endregion tags shall be included.

tabSize

  • an integer value specifying the number of spaces that will be used for replacing tab characters in the code block. If 0 or no value is specified, the language's default shall be used.

numberLines

  • a Boolean value indicating whether the lines in the code block should be numbered. If no value is specified, the line numbers shall be excluded.

outlining

  • a Boolean value indicating whether #region and #if blocks should be collapsible. If no value is specified, region outlining shall be disabled.

keepSeeTags

  • a Boolean value indicating whether see tags should be rendered as clickable links. If no value is specified, the see tags shall be rendered as literal text.

Nested Code Blocks

One or more nested code blocks may be included in a fenced code block by using a different delimiter (i.e., tildes if backticks were used in the enclosing block, and vice versa). This allows importing code from multiple sources/regions into a single code block.

Note Note
No nesting beyond a single level is permitted.

Example

AMDL
Copy
```C#
~~~{source="Class1.cs"}
~~~
~~~{source="Class2.cs"}
~~~
```

Example Output

C#
Copy
~~~{source="Class1.cs"}
~~~
~~~{source="Class2.cs"}
~~~
Differences from PM

  1. Nested code blocks are undefined in PM.

  2. Blank lines before or after fenced code block are not mandatory.

  3. The startFrom attribute is unsupported.

  4. Pandoc's Markdown: Fenced Code Blocks refers to tilde code blocks as fenced code blocks, while backtick code blocks are interpreted as a distinct element. In practice, there are no syntactic or semantic differences between PM and AMDL.

amdl2maml Support

Partial, pending parser modification.

Limitations

  1. Attributes are unsupported.

  2. Nested code blocks are unsupported.

See Also