Ryan Watters
5.8 KiB
title, linktitle, description, date, publishdate, lastmod, categories, tags, weight, draft, aliases, toc, notesforauthors
| title | linktitle | description | date | publishdate | lastmod | categories | tags | weight | draft | aliases | toc | notesforauthors | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Supported Content Formats | Content Formats | Markdown is natively supported in Hugo and is parsed by the feature-rich and incredibly speed Blackfriday parse. Hugo also provides support for additional syntaxes (eg, Asciidoc) via external helpers. | 2017-01-10 | 2017-01-10 | 2017-01-10 |
|
|
20 | false |
|
true |
Markdown
Markdown is the native content format for Hugo and is rendered using the excellent Blackfriday project, a blazingly fast parser written in Golang.
{{% note "Deeply Nested Lists" %}} Before you begin writing your content in markdown, Blackfriday has a known issue (#329) with handling deeply nested lists. Luckily, there is an easy workaround. Use 4-spaces (i.e., tab) rather than 2-space indentations to delimit nesting of lists in your content. {{% /note %}}
Configuring Markdown Rendering
You can configure multiple aspects of Blackfriday. For more information, see how to configure your Hugo projects:
{{< readfile file="content/readfiles/bfconfig.md" markdown="true" >}}
Extending 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
{{% code file="content/my-to-do-list.md" %}}
- [ ] a task list item
- [ ] list syntax required
- [ ] incomplete
- [x] completed
{{% /code %}}
Example Task List Output
The preceding markdown produces the following HTML in your rendered website:
{{% output file="my-to-do-list.html" %}}
<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>
{{% /output %}}
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
Shortcodes
If you write in markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality to act as the intermediary between your content and templating. This is one of the most powerful features in Hugo and allows you to essentially 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 nested shortcode to render syntax highlighting via Pygments. For usage examples and a complete explanation, see the syntax highlighting documentation in developer tools.
Markdown Learning Resources
If you are unfamiliar with markdown syntax, it can easily be learned within a single sitting. The following are excellent resources to get you up and running:
- Daring Fireball: Markdown, John Gruber (Creator of Markdown)
- Markdown Cheatsheet, Adam Pritchard
- Markdown Tutorial (Interactive), Garen Torikian
Additional Content Formats
Since 0.14, Hugo has defined a new concept called external helpers. This means you can write your content using Asciidoc, reStructuredText, or Org-mode. If you have files with associated extensions, Hugo will call external commands to generate the content. (See the Hugo source code for external helpers). The exception is Org-mode, which is parsed natively.
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.
{{% warning "Performance of External Helpers" %}} Because additional format are external commands---with the exception of org mode---generation performance will rely heavily on the performance of the external tool used. As this feature is still in its infancy, feedback is especially welcome. {{% /warning %}}