Fenced Code Blocks¶

Summary¶

The Fenced Code Blocks extension adds a secondary way to define code blocks, which overcomes a few limitations of indented code blocks.

This extension is included in the standard Markdown library.

Syntax¶

Fenced Code Blocks are defined using the syntax originally established in PHP Markdown Extra and popularized by GitHub Flavored Markdown.

Fenced code blocks begin with three or more backticks (```) or tildes (~~~) on a line by themselves and end with a matching set of backticks or tildes on a line by themselves. The closing set must contain the same number and type of characters as the opening set. It is recommended that a blank line be placed before and after the code block.

A paragraph before the code block.

```
a one-line code block
```

A paragraph after the code block.

While backticks seem to be more popular among users, tildes may be used as well.

~~~
a one-line code block
~~~

To include a set of backticks (or tildes) within a code block, use a different number of backticks for the deliminators.

````
```
````

Fenced code blocks can have a blank line as the first and/or last line of the code block and those lines will be preserved.

```

a three-line code block

```

Unlike indented code blocks, a fenced code block can immediately follow a list item without becoming part of the list.

* A list item.

```
not part of the list
```

Attributes¶

Various attributes may be defined on a per-code-block basis by defining them immediately following the opening deliminator. The attributes should be wrapped in curly braces {} and be on the same line as the deliminator. It is generally best to separate the attribute list from the deliminator with a space. Attributes within the list must be separated by a space.

``` { attributes go here }
a code block with attributes
```

How those attributes will affect the output will depend on various factors as described below.

Language¶

The language of the code within a code block can be specified for use by syntax highlighters, etc. The language should be prefixed with a dot and not contain any whitespace (.language-name).

``` { .html }
<p>HTML Document</p>
```

So long as the language is the only option specified, the curly brackets and/or the dot may be excluded:

``` html
<p>HTML Document</p>
```

Either of the above examples will output the following HTML:

<pre><code class="language-html">&lt;p&gt;HTML Document&lt;/p&gt;
</code></pre>

Note that the language name has been prefixed with language- and it has been assigned to the class attribute on the <code> tag, which is the format suggested by the HTML 5 Specification (see the second “example” in the Specification). While language is the default prefix, the prefix may be overridden using the lang_prefix configuration option.

Classes¶

In addition to the language, additional classes may be defined by prefixing them with a dot, just like the language.

``` { .html .foo .bar }
<p>HTML Document</p>
```

When defining multiple classes, only the first class will be used as the “language” for the code block. All others are assigned to the <pre> tag unaltered. Additionally, the curly braces and dot are required for all classes, including the language class if more than one class is defined.

The above example will output the following HTML:

<pre class="foo bar"><code class="language-html">&lt;p&gt;HTML Document&lt;/p&gt;
</code></pre>

ID¶

An id can be defined for a code block, which would allow a link to point directly to the code block using a URL hash. IDs must be prefixed with a hash character (#) and only contain characters permitted in HTML id attributes.

``` { #example }
A linkable code block
```

The id attribute is assigned to the <pre> tag of the output. The above example will output the following HTML:

<pre id="example"><code>A linkable code block
</code></pre>

From elsewhere within the same document, one could link to the code block with [link](#example).

IDs may be defined along with the language, other classes, or any other supported attributes. The order of items does not matter.

``` { #example .lang .foo .bar }
A linkable code block
```

Key/Value Pairs¶

If the fenced_code and attr_list extensions are both enabled, then key/value pairs can be defined in the attribute list. So long as code highlighting is not enabled (see below), the key/value pairs will be assigned as attributes on the <code> tag in the output. Key/value pairs must be defined using the syntax documented for the attr_list extension (for example, values with whitespace must be wrapped in quotes).

``` { .lang #example style="color: #333; background: #f8f8f8;" }
A code block with inline styles. Fancy!
```

The above example will output the following HTML:

<pre id="example"><code class="language-lang"  style="color: #333; background: #f8f8f8;">A code block with inline styles. Fancy!
</code></pre>

If the attr_list extension is not enabled, then the key/value pairs will be ignored.

Syntax Highlighting¶

If the fenced_code extension and syntax highlighting are both enabled, then the codehilite extension will be used for syntax highlighting the contents of the code block. The language defined in the attribute list will be passed to codehilite to ensure that the correct language is used. If no language is specified and language guessing is not disabled for the codehilite extension, then the language will be guessed.

The codehilite extension uses the Pygments engine to do syntax highlighting. Any valid Pygments options can be defined as key/value pairs in the attribute list and will be passed on to Pygments.

``` { .lang linenos=true linenostart=42 hl_lines="43-44 50" title="An Example Code Block" }`
A truncated code block...
```

Valid options include any option accepted by Pygments’ HTMLFormatter except for the full option, as well as any options accepted by the relevant lexer (each language has its own lexer). While most lexers don’t have options that are all that useful in this context, there are a few important exceptions. For example, the PHP lexer’s startinline option eliminates the need to start each code fragment with <?php.

Enabling Syntax Highlighting¶

To enable syntax highlighting, the codehilite extension must be enabled and the codehilite extension’s use_pygments option must be set to True (the default).

Alternatively, so long as the codehilite extension is enabled, you can override a global use_pygments=False option for an individual code block by including use_pygments=true in the attribute list. While the use_pygments key/value pair will not be included in the output, all other attributes will behave as they would if syntax highlighting was enabled only for that code block.

Conversely, to disable syntax highlighting on an individual code block, include use_pygments=false in the attribute list. While the use_pygments key/value pair will not be included in the output, all other attributes will behave as they would if syntax highlighting was disabled for that code block regardless of any global setting.

Usage¶

See Extensions for general extension usage. Use fenced_code as the name of the extension.

See the Library Reference for information about configuring extensions.

The following option is provided to configure the output:

• lang_prefix: The prefix prepended to the language class assigned to the HTML <code> tag. Default: language-.

A trivial example:

markdown.markdown(some_text, extensions=['fenced_code'])