diff options
Diffstat (limited to 'docs/extensions/fenced_code_blocks.md')
| -rw-r--r-- | docs/extensions/fenced_code_blocks.md | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/docs/extensions/fenced_code_blocks.md b/docs/extensions/fenced_code_blocks.md new file mode 100644 index 0000000..fc5c9ca --- /dev/null +++ b/docs/extensions/fenced_code_blocks.md @@ -0,0 +1,269 @@ +title: Fenced Code Blocks Extension + +# 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][php] and popularized by +[GitHub Flavored Markdown][gfm]. + +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. + +````md +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. + +````md +~~~ +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. + +`````md +```` +``` +```` +````` + +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. + +````md +``` + +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. + +````md +* A list item. + +``` +not part of the list +``` +```` + +!!! warning + + Fenced Code Blocks are only supported at the document root level. Therefore, they cannot be nested inside lists or + blockquotes. If you need to nest fenced code blocks, you may want to try the third party extension [SuperFences] + instead. + +### 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. + +````md +``` { 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`). + +````md +``` { .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: + +````md +``` html +<p>HTML Document</p> +``` +```` + +Either of the above examples will output the following HTML: + +```html +<pre><code class="language-html"><p>HTML Document</p> +</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][html5] (see the second "example" in the +Specification). While `language` is the default prefix, the prefix may be overridden using the +[`lang_prefix`](#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. + +````md +``` { .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: + +```html +<pre class="foo bar"><code class="language-html"><p>HTML Document</p> +</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. + +````md +``` { #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: + +```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. + +````md +``` { #example .lang .foo .bar } +A linkable code block +``` +```` + +#### Key/Value Pairs + +If the `fenced_code` and [`attr_list`][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). + +````md +``` { .lang #example style="color: #333; background: #f8f8f8;" } +A code block with inline styles. Fancy! +``` +```` + +The above example will output the following HTML: + +```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`][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. + +````md +``` { .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`][HTMLFormatter] except for the `full` option, +as well as any options accepted by the relevant [lexer][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`. + +!!! note + + The `fenced_code` extension does not alter the output provided by Pygments. Therefore, only options which Pygments + provides can be utilized. As Pygments does not currently provide a way to define an ID, any ID defined in an + attribute list will be ignored when syntax highlighting is enabled. Additionally, any key/value pairs which are not Pygments options will be ignored, regardless of whether the `attr_list` extension is enabled. + +##### Enabling Syntax Highlighting + +To enable syntax highlighting, the [`codehilite`][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. + +!!! seealso "See Also" + + You will need to properly install and setup Pygments for syntax highlighting to work. See the `codehilite` + extension's [documentation][setup] for details. + +## 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`**{#lang_prefix}: + The prefix prepended to the language class assigned to the HTML `<code>` tag. Default: `language-`. + +A trivial example: + +```python +markdown.markdown(some_text, extensions=['fenced_code']) +``` + +[php]: http://www.michelf.com/projects/php-markdown/extra/#fenced-code-blocks +[gfm]: https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks +[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ +[html5]: https://html.spec.whatwg.org/#the-code-element +[attr_list]: ./attr_list.md +[codehilite]: ./code_hilite.md +[Pygments]: http://pygments.org/ +[HTMLFormatter]: https://pygments.org/docs/formatters/#HtmlFormatter +[lexer]: https://pygments.org/docs/lexers/ +[PHP lexer's]: https://pygments.org/docs/lexers/#lexers-for-php-and-related-languages +[setup]: ./code_hilite.md#setup +[Extensions]: ./index.md +[Library Reference]: ../reference.md#extensions |