- The thing is, that Hugo is mainly - but not only - geared towards writing content in extended Markdown. In fact, one of the major selling points of static blog/content generators like Jekyll and Hugo is their proclaimed ability to let you “Blog Like a Hacker” 1, not “blog like an underpaid web designer”. So falling back to HTML would be.
- Now you can do the same with Markdown Render Hooks. And the cherry on top is that it renders 15% faster and requires less memory. Before we get started with hugo website I would recommend to develop hugo website inside development docker container.
Improve this question. Follow edited Dec 25 '20 at 17:27. 332 2 2 silver badges 14 14 bronze badges. Asked Dec 24 '20 at 6:31. 1,294 1 1 gold badge 7 7 silver badges 18 18 bronze badges. Add a comment 2 Answers Active Oldest Votes. To answer the question: 'Can unsafe mode be applied. Archie - Hugo theme. Archie is a minimal and clean theme for hugo with a markdown-ish UI. Forked from Ezhil Theme. Check the Demo hosted on GitHub Pages:smile:. You can find the source code to that in the site branch of this repository. Make a new blog post by executing hugo new post/postnamehere/index.md in your shell. At the top of the new markdown file, is what’s called the front matter. The front matter is the page’s metadata that determines how Hugo and aether generate the HTML for your post.
This page is a shameful copy of the great Grav original page.Only difference is information about image customization (resizing, add CSS classes…)
Let’s face it: Writing content for the Web is tiresome. WYSIWYG editors help alleviate this task, but they generally result in horrible code, or worse yet, ugly web pages.
Markdown is a better way to write HTML, without all the complexities and ugliness that usually accompanies it.
Some of the key benefits are:
- Markdown is simple to learn, with minimal extra characters so it’s also quicker to write content.
- Less chance of errors when writing in markdown.
- Produces valid XHTML output.
- Keeps the content and the visual display separate, so you cannot mess up the look of your site.
- Write in any text editor or Markdown application you like.
- Markdown is a joy to use!
John Gruber, the author of Markdown, puts it like this:
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.– John Gruber
Grav ships with built-in support for Markdown and Markdown Extra. You must enable Markdown Extra in your
system.yaml
configuration fileWithout further delay, let us go over the main elements of Markdown and what the resulting HTML looks like:
Headings
Headings from
h1
through h6
are constructed with a #
for each level:Renders to:
h2 Heading
h3 Heading
h4 Heading
h5 Heading
h6 Heading
HTML:
Comments should be HTML compatible
Comment below should NOT be seen:
Horizontal Rules
The HTML
<hr>
element is for creating a “thematic break” between paragraph-level elements. In markdown, you can create a <hr>
with any of the following:___
: three consecutive underscores---
: three consecutive dashes***
: three consecutive asterisks
renders to:
Body Copy
Body copy written as normal, plain text will be wrapped with
<p></p>
tags in the rendered HTML.So this body copy:
renders to this HTML:
Emphasis
Bold
For emphasizing a snippet of text with a heavier font-weight.
The following snippet of text is rendered as bold text.
renders to:
rendered as bold text
and this HTML
Italics
For emphasizing a snippet of text with italics.
The following snippet of text is rendered as italicized text.
renders to:
rendered as italicized text
and this HTML:
Strikethrough
In GFM (GitHub flavored Markdown) you can do strikethroughs.
Which renders to:
HTML:
Blockquotes
For quoting blocks of content from another source within your document.
Add
>
before any text you want to quote.Renders to:
Fusion Drive combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.
and this HTML:
Blockquotes can also be nested:
Renders to:
Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
Notices
The old mechanism for notices overriding the block quote syntax (
>>>
) has been deprecated. Notices are now handled via a dedicated plugin called Markdown NoticesLists
Unordered
A list of items in which the order of the items does not explicitly matter.
You may use any of the following symbols to denote bullets for each list item:
For example
Renders to:
- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
And this HTML
Ordered
A list of items in which the order of items does explicitly matter.
Renders to:
- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
And this HTML:
TIP: If you just use
1.
for each number, Markdown will automatically number each item. For example:Renders to:
- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
Code
Inline code
Wrap inline snippets of code with
`
.Renders to:
In this example,
<section></section>
should be wrapped as code.HTML:
Indented code
Or indent several lines of code by at least two spaces, as in:
Renders to:
HTML:
Block code “fences”
Use “fences”
```
to block in multiple lines of code.HTML:
Syntax highlighting
GFM, or “GitHub Flavored Markdown” also supports syntax highlighting. To activate it, simply add the file extension of the language you want to use directly after the first code “fence”,
```js
, and syntax highlighting will automatically be applied in the rendered HTML.See Code Highlighting for additional documentation.
For example, to apply syntax highlighting to JavaScript code:
Renders to:
Tables
Tables are created by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned.
Renders to:
Option | Description |
---|---|
data | path to data files to supply the data that will be passed into templates. |
engine | engine to be used for processing templates. Handlebars is the default. |
ext | extension to be used for dest files. |
And this HTML:
Right aligned text
Adding a colon on the right side of the dashes below any heading will right align text for that column.
Option | Description |
---|---|
data | path to data files to supply the data that will be passed into templates. |
engine | engine to be used for processing templates. Handlebars is the default. |
ext | extension to be used for dest files. |
Links
Basic link
Renders to (hover over the link, there is no tooltip):
HTML:
Add a tooltip
Renders to (hover over the link, there should be a tooltip):
HTML:
Named Anchors
Hugo Markdown Html
Named anchors enable you to jump to the specified anchor point on the same page. For example, each of these chapters:
will jump to these sections:
NOTE that specific placement of the anchor tag seems to be arbitrary. They are placed inline here since it seems to be unobtrusive, and it works.
Images
Images have a similar syntax to links but include a preceding exclamation point.
or
Like links, Images also have a footnote style syntax
Alternative usage : note images
With a reference later in the document defining the URL location:
Resizing image
Add HTTP parameters
width
and/or height
to the link image to resize the image. Values are CSS values (default is auto
).Add CSS classes
Add a HTTP
classes
parameter to the link image to add CSS classes. shadow
and border
are available but you could define other ones.Lightbox
Add a HTTP
featherlight
parameter to the link image to disable lightbox. By default lightbox is enabled using the featherlight.js plugin. You can disable this by defining featherlight
to false
.Both HTML and Markdown are supported content formats.
You can put any file type into your
/content
directories, but Hugo uses the markup
front matter value if set or the file extension (see Markup identifiers
in the table below) to determine if the markup needs to be processed, e.g.:- Markdown converted to HTML
- Shortcodes processed
- Layout applied
List of content formats
The current list of content formats in Hugo:
Name | Markup identifiers | Comment |
---|---|---|
Goldmark | md, markdown, goldmark | Note that you can set the default handler of md and markdown to something else, see Configure Markup. |
Blackfriday | blackfriday | Blackfriday will eventually be deprecated. |
MMark | mmark | Mmark is deprecated and will be removed in a future release. |
Emacs Org-Mode | org | See go-org. |
AsciiDoc | asciidocext, adoc, ad | Needs Asciidoctor installed. |
RST | rst | Needs RST installed. |
Pandoc | pandoc, pdc | Needs Pandoc installed. |
HTML | html, htm | To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is. |
The
markup identifier
is fetched from either the markup
variable in front matter or from the file extension. For markup-related configuration, see Configure Markup.External Helpers
Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files,Hugo will try to call the
asciidoctor
command. This means that you will have to install the associatedtool on your machine to be able to use these formats.Hugo passes reasonable default arguments to these external helpers by default:
asciidoctor
:--no-header-footer -
rst2html
:--leave-comments --initial-header-level=2
pandoc
:--mathjax
Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
External Helper AsciiDoc
AsciiDoc implementation EOLs in Jan 2020 and is no longer supported.AsciiDoc development is being continued under Asciidoctor. The format AsciiDocremains of course. Please continue with the implementation Asciidoctor.
External Helper Asciidoctor
The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo.See the Asciidoctor docs for installation instructions. Make sure that also alloptional extensions like
asciidoctor-diagram
or asciidoctor-html5s
are installed if required.Hugo Markdown Table
External
asciidoctor
command requires Hugo rendering to disk to a specific destination directory. It is required to run Hugo with the command option --destination
.Some Asciidoctor parameters can be customized in Hugo:
Parameter | Comment |
---|---|
backend | Don’t change this unless you know what you are doing. |
doctype | Currently, the only document type supported in Hugo is article . |
extensions | Possible extensions are asciidoctor-html5s , asciidoctor-bibtex , asciidoctor-diagram , asciidoctor-interdoc-reftext , asciidoctor-katex , asciidoctor-latex , asciidoctor-mathematical , asciidoctor-question , asciidoctor-rouge . |
attributes | Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See Asciidoctor’s attributes. |
noHeaderOrFooter | Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don’t change this unless you know what you are doing. |
safeMode | Safe mode level unsafe , safe , server or secure . Don’t change this unless you know what you are doing. |
sectionNumbers | Auto-number section titles. |
verbose | Verbosely print processing information and configuration file checks to stderr. |
trace | Include backtrace information on errors. |
failureLevel | The minimum logging level that triggers a non-zero exit code (failure). |
Hugo provides additional settings that don’t map directly to Asciidoctor’s CLI options:
- workingFolderCurrent
- Sets the working directory to be the same as that of the AsciiDoc file being processed, so that include will work with relative paths. This setting uses the
asciidoctor
cli parameter--base-dir
and attributeoutdir=
. For rendering diagrams with asciidoctor-diagram,workingFolderCurrent
must be set totrue
. - preserveTOC
- By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable
.TableOfContents
to enable further customization and better integration with the various Hugo themes. This option can be set totrue
to preserve Asciidoctor’s TOC in the generated page.
Below are all the AsciiDoc related settings in Hugo with their default values:
Hugo Markdown
Notice that for security concerns only extensions that do not have path separators (either
, /
or .
) are allowed. That means that extensions can only be invoked if they are in one’s ruby’s $LOAD_PATH
(ie. most likely, the extension has been installed by the user). Any extension declared relative to the website’s path will not be accepted.Hugo Markdownify
Example of how to set extensions and attributes:
Hugo Static Site Generator
In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with allparameters. Run Hugo with
-v
. You will get an output likeLearn Markdown
Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running: