Skip to content

Extensions

Jump to bottom Edit New page
TPaschalis edited this page Apr 15, 2019 · 3 revisions

In addition to the standard markdown syntax, this package implements some extensions, which add additional functionality.

There are both Markdown extensions, which control how Markdown input is parsed into an AST, and HTML extensions, which control how the AST is written to HTML.

These extensions are used by passing arguments to Run(input []byte, opts ...Option) []byte. Invoking Run(input) with no options uses the common extensions, defined in the package constants.

For Markdown extensions, the Option-generating functions WithExtensions(e Extensions) and WithNoExtensions() can be used.

HTML extensions, by contrast, are slightly more complex. The Option can be generated with something like:

blackfriday.WithRenderer(blackfriday.NewHTMLRenderer(
    blackfriday.HTMLRendererParameters{
        Flags: blackfriday.CommonHTMLFlags,
    }))

This page is a work in progress and incomplete; refer to the documentation for more information.

Markdown Extensions

  • Intra-word emphasis supression (NoIntraEmphasis). The _ character is commonly used inside words when discussing code, so having markdown interpret it as an emphasis command is usually the wrong thing. Blackfriday lets you treat all emphasis markers as normal characters when they occur inside a word.

  • Tables (Tables). Tables can be created by drawing them in the input using a simple syntax:

    Name    | Age
--------|------
Bob     | 27
Alice   | 23

  • Fenced code blocks (FencedCode). In addition to the normal 4-space indentation to mark code blocks, you can explicitly mark them and supply a language (to make syntax highlighting simple). Just mark it like this:

    ``` go
func getTrue() bool {
    return true
}
```

    You can use 3 or more backticks to mark the beginning of the block, and the same number to mark the end of the block.

    To preserve classes of fenced code blocks while using the bluemonday HTML sanitizer, use the following policy:

    p := bluemonday.UGCPolicy()
p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code")
html := p.SanitizeBytes(unsafe)

  • Autolinking (Autolink). Blackfriday can find URLs that have not been explicitly marked as links and turn them into links.

  • Strikethrough (Strikethrough). Use two tildes (~~) to mark text that should be crossed out.

  • Hard line breaks (HardLineBreak). With this extension enabled (it is off by default in the MarkdownBasic and MarkdownCommon convenience functions), newlines in the input translate into line breaks in the output.

  • Footnotes (Footnotes). A marker in the text that will become a superscript number; a footnote definition that will be placed in a list of footnotes at the end of the document. A footnote looks like this:

    This is a footnote.[^1]

[^1]: the footnote text.

  • Pandoc-style titleblock (Titleblock). Allows specifying document metadata in a Pandoc-style titleblock. i.e. (quoting the Pandoc documentation) “if the file begins with a title block”

    % title
% author(s) (separated by semicolons)
% date

    “it will be parsed as bibliographic information, not regular text.”

  • Custom heading IDs (HeadingIDs). Allows specifying the ID of a header (in HTML this is rendered as something like <h1 id="custom-id-here">Header text</h1>) with {#id}. These can be automatically generated with AutoHeadingIDs.

  • Definition lists (DefinitionLists). A simple definition list is made of a single-line term followed by a colon and the definition for that term.

    Cat
: Fluffy animal everyone likes

Internet
: Vector of transmission for pictures of cats

    Terms must be separated from the previous definition by a blank line.

HTML Extensions

  • Table of contents (TOC). Generates a table of contents as a <nav> containing nested <ul>s. Each <li> contains an intra-page link to the relevant header.

    # Scope
# The Hugo process
## Front matter
### Site-wide config
### TOML, YAML, or JSON?
## Markdown rendering
# Layouts
## The layout process
### Lookup order
## Dynamic templates; functions and variables
### Building blocks
### Partial templates
## Data templates
# Deploying
# Why this guide
## Use-case

    would render a TOC of

    <nav>
<ul>
    <li><a href="#toc_0">Scope</a></li>
    <li><a href="#toc_1">The Hugo process</a>
        <ul>
            <li><a href="#toc_2">Front matter</a>
                <ul>
                    <li><a href="#toc_3">Site-wide config</a></li>
                    <li><a href="#toc_4">TOML, YAML, or JSON?</a></li>
                </ul>
            </li>
            <li><a href="#toc_5">Markdown rendering</a></li>
        </ul>
    </li>
    <li><a href="#toc_6">Layouts</a>
        <ul>
            <li><a href="#toc_7">The layout process</a>
                <ul>
                    <li><a href="#toc_8">Lookup order</a></li>
                </ul>
            </li>
            <li><a href="#toc_9">Dynamic templates; functions and variables</a>
                <ul>
                    <li><a href="#toc_10">Building blocks</a></li>
                    <li><a href="#toc_11">Partial templates</a></li>
                </ul>
            </li>
            <li><a href="#toc_12">Data templates</a></li>
        </ul>
    </li>
    <li><a href="#toc_13">Deploying</a></li>
    <li><a href="#toc_14">Why this guide</a>
        <ul>
            <li><a href="#toc_15">Use-case</a></li>
        </ul>
    </li>
</ul>
</nav>

    (Indentation added for clarity.)

    Which would render as (roughly)

    • Scope
    • The Hugo process
      • Front matter
        • Site-wide config
        • TOML, YAML, or JSON?
      • Markdown rendering
    • Layouts
      • The layout process
        • Lookup order
      • Dynamic templates; functions and variables
        • Building blocks
        • Partial templates
      • Data templates
    • Deploying
    • Why this guide
      • Use-case

  • FootnoteReturnLinks (FootnoteReturnLinks). Generate links at the end of footnotes to return to the source.

Smartypants extensions

SmartyPants is a module created by John Gruber “that easily translates plain ASCII punctuation characters into ‘smart’ typographic punctuation HTML entities.” Its functionality has been largely replicated in Blackfriday.

  • Smart quotes (Smartypants). Smartypants-style punctuation substitution is supported, turning normal double- and single-quote marks into curly quotes, etc.

  • LaTeX-style dash parsing (SmartypantsLatexDashes) is an additional option, where -- is translated into &ndash;, and --- is translated into &mdash;. This differs from most smartypants processors, which turn a single hyphen into an ndash and a double hyphen into an mdash.

  • Smart fractions (SmartypantsFractions), where anything that looks like a fraction is translated into suitable HTML (instead of just a few special cases like most smartypant processors). For example, 4/5 becomes <sup>4</sup>&frasl;<sub>5</sub>, which renders as 4⁄5.

Add a custom footer
Add a custom sidebar
Clone this wiki locally