Supported Content Formats

Markdown is the main content format and comes in two flavours: The excellent Blackfriday project (name your files *.md or set markup = "markdown" in front matter) or its fork Mmark (name your files *.mmark or set markup = "mmark" in front matter), both very fast markdown engines written in Go.

For Emacs users, go-org provides built-in native support for Org-mode (name your files *.org or set markup = "org" in front matter)

But in many situations, plain HTML is what you want. Just name your files with .html or .htm extension inside your content folder. Note that if you want your HTML files to have a layout, they need front matter. It can be empty, but it has to be there:

---
title: "This is a content file in HTML"
---

<div>
  <h1>Hello, Hugo!</h1>
</div>

Configure BlackFriday Markdown Rendering

You can configure multiple aspects of Blackfriday as shown in the following list. See the docs on Configuration for the full list of explicit directions you can give to Hugo when rendering your site.

Blackfriday Options

taskLists: default: true
Blackfriday flag:
Purpose: false turns off GitHub-style automatic task/TODO list generation.
smartypants: default: true
Blackfriday flag: HTML_USE_SMARTYPANTS
Purpose: false disables smart punctuation substitutions, including smart quotes, smart dashes, smart fractions, etc. If true, it may be fine-tuned with the angledQuotes, fractions, smartDashes, and latexDashes flags (see below).
smartypantsQuotesNBSP: default: false
Blackfriday flag: HTML_SMARTYPANTS_QUOTES_NBSP
Purpose: true enables French style Guillemets with non-breaking space inside the quotes.
angledQuotes: default: false
Blackfriday flag: HTML_SMARTYPANTS_ANGLED_QUOTES
Purpose: true enables smart, angled double quotes. Example: “Hugo” renders to «Hugo» instead of “Hugo”.
fractions: default: true
Blackfriday flag: HTML_SMARTYPANTS_FRACTIONS
Purpose: false disables smart fractions.
Example: 5/12 renders to ⁵⁄₁₂(<sup>5</sup>&frasl;<sub>12</sub>).
Caveat: Even with fractions = false, Blackfriday still converts 1/2, 1/4, and 3/4 respectively to ½ (½), ¼ (¼) and ¾ (¾), but only these three.
smartDashes: default: true
Blackfriday flag: HTML_SMARTY_DASHES
Purpose: false disables smart dashes; i.e., the conversion of multiple hyphens into an en-dash or em-dash. If true, its behavior can be modified with the latexDashes flag below.
latexDashes: default: true
Blackfriday flag: HTML_SMARTYPANTS_LATEX_DASHES
Purpose: false disables LaTeX-style smart dashes and selects conventional smart dashes. Assuming smartDashes:
If true, -- is translated into – (–), whereas --- is translated into — (—).
However, spaced single hyphen between two words is translated into an en dash— e.g., “12 June - 3 July” becomes 12 June – 3 July upon rendering.
hrefTargetBlank: default: false
Blackfriday flag: HTML_HREF_TARGET_BLANK
Purpose: true opens ~~external links~~ absolute links in a new window or tab. While the target="_blank" attribute is typically used for external links, Blackfriday does that for all absolute links (ref). One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting canonifyURLs to true or via absURL).
nofollowLinks: default: false
Blackfriday flag: HTML_NOFOLLOW_LINKS
Purpose: true creates ~~external links~~ absolute links with nofollow being added to their rel attribute. Thereby crawlers are advised to not follow the link. While the rel="nofollow" attribute is typically used for external links, Blackfriday does that for all absolute links. One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting canonifyURLs to true or via absURL).
noreferrerLinks: default: false
Blackfriday flag: HTML_NOREFERRER_LINKS
Purpose: true creates ~~external links~~ absolute links with noreferrer being added to their rel attribute. Thus when following the link no referrer information will be leaked. While the rel="noreferrer" attribute is typically used for external links, Blackfriday does that for all absolute links. One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting canonifyURLs to true or via absURL).
plainIDAnchors: default true
Blackfriday flag: FootnoteAnchorPrefix and HeaderIDSuffix
Purpose: true renders any heading and footnote IDs without the document ID.
Example: renders #my-heading instead of #my-heading:bec3ed8ba720b970
extensions: default: []
Purpose: Enable one or more Blackfriday’s Markdown extensions (EXTENSION_*).
Example: Include hardLineBreak in the list to enable Blackfriday’s EXTENSION_HARD_LINE_BREAK.
See Blackfriday extensions section for information on all extensions.
extensionsmask: default: []
Purpose: Disable one or more of Blackfriday’s Markdown extensions (EXTENSION_*).
Example: Include autoHeaderIds as false in the list to disable Blackfriday’s EXTENSION_AUTO_HEADER_IDS.
See Blackfriday extensions section for information on all extensions.
skipHTML: default: false
Blackfriday flag: HTML_SKIP_HTML
Purpose: true causes any HTML in the markdown files to be skipped.

Blackfriday extensions

noIntraEmphasis

default: enabled
Purpose: The “_” character is commonly used inside words when discussing code, so having Markdown interpret it as an emphasis command is usually the wrong thing. When enabled, Blackfriday lets you treat all emphasis markers as normal characters when they occur inside a word.

tables

default: enabled
Purpose: When enabled, tables can be created by drawing them in the input using the below syntax: Example:

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

fencedCode

default: enabled
Purpose: When enabled, 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).

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.

Example:

 ```md
# Heading Level 1
Some test
## Heading Level 2
Some more test
```

autolink

default: enabled
Purpose: When enabled, URLs that have not been explicitly marked as links will be converted into links.

strikethrough

default: enabled
Purpose: When enabled, text wrapped with two tildes will be crossed out.
Example: ~~crossed-out~~

laxHtmlBlocks

default: disabled
Purpose: When enabled, loosen up HTML block parsing rules.

spaceHeaders

default: enabled
Purpose: When enabled, be strict about prefix header rules.

hardLineBreak

default: disabled
Purpose: When enabled, newlines in the input translate into line breaks in the output.

tabSizeEight

default: disabled
Purpose: When enabled, expand tabs to eight spaces instead of four.

footnotes

default: enabled
Purpose: When enabled, Pandoc-style footnotes will be supported. The footnote marker in the text that will become a superscript text; the footnote definition will be placed in a list of footnotes at the end of the document.
Example:

This is a footnote.[^1]

[^1]: the footnote text.

noEmptyLineBeforeBlock

default: disabled
Purpose: When enabled, no need to insert an empty line to start a (code, quote, ordered list, unordered list) block.

headerIds

default: enabled
Purpose: When enabled, allow specifying header IDs with {#id}.

titleblock

default: disabled
Purpose: When enabled, support Pandoc-style title blocks.

autoHeaderIds

default: enabled
Purpose: When enabled, auto-create the header ID’s from the headline text.

backslashLineBreak

default: enabled
Purpose: When enabled, translate trailing backslashes into line breaks.

definitionLists

default: enabled
Purpose: When enabled, a simple definition list is made of a single-line term followed by a colon and the definition for that term.
Example:

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.

joinLines

default: enabled
Purpose: When enabled, delete newlines and join the lines.

Extend Markdown

Hugo provides some convenient methods for extending markdown.

Task Lists

Hugo supports GitHub-styled task lists (i.e., TODO lists) for the Blackfriday markdown renderer. If you do not want to use this feature, you can disable it in your configuration.

Example Task List Input

content/my-to-do-list.md


- [ ] a task list item
- [ ] list syntax required
- [ ] incomplete
- [x] completed

Example Task List Output

The preceding markdown produces the following HTML in your rendered website:

<ul class="task-list">
    <li><input type="checkbox" disabled="" class="task-list-item"> a task list item</li>
    <li><input type="checkbox" disabled="" class="task-list-item"> list syntax required</li>
    <li><input type="checkbox" disabled="" class="task-list-item"> incomplete</li>
    <li><input type="checkbox" checked="" disabled="" class="task-list-item"> completed</li>
</ul>

Example Task List Display

The following shows how the example task list will look to the end users of your website. Note that visual styling of lists is up to you. This list has been styled according to the Hugo Docs stylesheet.

a task list item
list syntax required
incomplete
completed

Emojis

To add emojis directly to content, set enableEmoji to true in your site configuration. To use emojis in templates or shortcodes, see emojify function.

For a full list of emojis, see the Emoji cheat sheet.

Shortcodes

If you write in Markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality. This is one of the most powerful features in Hugo and allows you to create your own Markdown extensions very quickly.

See Shortcodes for usage, particularly for the built-in shortcodes that ship with Hugo, and Shortcode Templating to learn how to build your own.

Code Blocks

Hugo supports GitHub-flavored markdown’s use of triple back ticks, as well as provides a special highlight shortcode, and syntax highlights those code blocks natively using Chroma. Users also have an option to use Pygments instead. See the Syntax Highlighting section for details.

Mmark

Mmark is a fork of BlackFriday and markdown superset that is well suited for writing IETF documentation. You can see examples of the syntax in the Mmark GitHub repository or the full syntax on Miek Gieben’s website.

Use Mmark

As Hugo ships with Mmark, using the syntax is as easy as changing the extension of your content files from .md to .mmark.

In the event that you want to only use Mmark in specific files, you can also define the Mmark syntax in your content’s front matter:

---
title: My Post
date: 2017-04-01
markup: mmark
---

MathJax with Hugo

MathJax is a JavaScript library that allows the display of mathematical expressions described via a LaTeX-style syntax in the HTML (or Markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here.

This is not an introduction into actually using MathJax to render typeset mathematics on your website. Instead, this page is a collection of tips and hints for one way to get MathJax working on a website built with Hugo.

Enable MathJax

The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventurous readers can consult the Loading and Configuring section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by include a <script> tag for the officially recommended secure CDN (cdn.js.com):

add-mathjax-to-page.html


<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

One way to ensure that this code is included in all pages is to put it in one of the templates that live in the layouts/partials/ directory. For example, I have included this in the bottom of my template footer.html because I know that the footer will be included in every page of my website.

Options and Features

MathJax is a stable open-source library with many features. I encourage the interested reader to view the MathJax Documentation, specifically the sections on Basic Usage and MathJax Configuration Options.

Issues with Markdown

After enabling MathJax, any math entered between proper markers (see the MathJax documentation) will be processed and typeset in the web page. One issue that comes up, however, with Markdown is that the underscore character (_) is interpreted by Markdown as a way to wrap text in emph blocks while LaTeX (MathJax) interprets the underscore as a way to create a subscript. This “double speak” of the underscore can result in some unexpected and unwanted behavior.

Solution

There are multiple ways to remedy this problem. One solution is to simply escape each underscore in your math code by entering \_ instead of _. This can become quite tedious if the equations you are entering are full of subscripts.

Another option is to tell Markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a <div> </div> block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the <div> is not acceptable. The syntax for instructing Markdown to treat inline text as verbatim is by wrapping it in backticks (`). You might have noticed, however, that the text included in between backticks is rendered differently than standard text (on this site these are items highlighted in red). To get around this problem, we could create a new CSS entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the HTML and CSS source that would accomplish this (note this solution was adapted from this blog post—all credit goes to the original author).

mathjax-markdown-solution.html


<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  tex2jax: {
    inlineMath: [['$','$'], ['\\(','\\)']],
    displayMath: [['$$','$$'], ['\[','\]']],
    processEscapes: true,
    processEnvironments: true,
    skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
    TeX: { equationNumbers: { autoNumber: "AMS" },
         extensions: ["AMSmath.js", "AMSsymbols.js"] }
  }
});
</script>

As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page.

mathjax-style.css


code.has-jax {
    font: inherit;
    font-size: 100%;
    background: inherit;
    border: inherit;
    color: #515151;
}

In the CSS snippet, notice the line color: #515151;. #515151 is the value assigned to the color attribute of the body class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body.

Usage

With this setup, everything is in place for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `$ TeX Code $` or `$ TeX Code $`. To include display style mathematics, just put LaTeX code in between <div>$$TeX Code$$</div>. All the math will be properly typeset and displayed within your Hugo generated web page!

Additional Formats Through External Helpers

Hugo has a new concept called external helpers. It means that you can write your content using Asciidoc, reStructuredText, or pandoc. If you have files with associated extensions, Hugo will call external commands to generate the content. (See the Hugo source code for external helpers.)

For example, for Asciidoc files, Hugo will try to call the asciidoctor or asciidoc command. This means that you will have to install the associated tool on your machine to be able to use these formats. (See the Asciidoctor docs for installation instructions).

To use these formats, just use the standard extension and the front matter exactly as you would do with natively supported .md files.

Hugo passes reasonable default arguments to these external helpers by default:

asciidoc: --no-header-footer --safe -
asciidoctor: --no-header-footer --safe --trace -
rst2html: --leave-comments --initial-header-level=2
pandoc: --mathjax

Learn Markdown

Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running:

Supported Content Formats

Configure BlackFriday Markdown Rendering

Blackfriday Options

Blackfriday extensions

Extend Markdown

Task Lists

Example Task List Input

Example Task List Output

Example Task List Display

Emojis

Shortcodes

Code Blocks

Mmark

Use Mmark

MathJax with Hugo

Enable MathJax

Options and Features

Issues with Markdown

Solution

Usage

Additional Formats Through External Helpers

Learn Markdown

See Also

“Supported Content Formats” was last updated: October 24, 2019: remake. (28623dd)