Hugo
Last updated
Was this helpful?
Last updated
Was this helpful?
Task
Command
Create a new single page
hugo new posts/a/index.md
Local preview at localhost: 1313
hugo server
(-D
to include drafts)
Update all submodules
git pull --recurse-submodules
Task
Command
Install Hugo via brew
brew install hugo
Verify that Hugo is installed
which hugo
or hugo version
Create a new site
hugo new site davidfeng.us
Select a theme from .
Download the theme as a git submodule: git submodule add https://github.com/Track3/hermit.git themes/hermit
Copy themes/hermit/exampleSite/config.toml
to the top level.
To customize a theme, e.g. you want to make some changes to a config.toml
, an archetype, a template/layout, or a static file (favicon), either change the theme directly (in the themes/hermit
directory), or copy the file you want to change to the same location on the top level and change it. Hugo will prioritize the files on the top level.
In config.toml
, I changed the following fields: baseURL, title, googleAnalytics, disqusShortname, author name, homeSubtitle, justifyContent, social icons' names and urls, menu items. Usually Hugo server needs to be restarted after modification of config.toml
.
In archetypes
, I removed image, toc, tags, comments fields in the front matter.
Content lives in content/
directory. There are two type of pages in Hugo: list page and single page. Usually directories correspond to list pages and individual markdown files are single pages.
Markdown file
Command to generate
URL
content/a.md
hugo new a.md
localhost:1313/a/
content/a/index.md
hugo new a/index.md
localhost:1313/a/
content/dir1/dir2/b.md
hugo new dir1/dir2/b.md
localhost:1313/dir1/dir2/b/
The hugo new path/file
command populates the markdown file according to the archetypes.
I usually use an index.md page as my single page so that I can put related assets (e.g. images) in the same directory.
If you create a file at content/dir1/dir2/_index.html
, localhost:1313/dir1/dir2/
will points to a HTML file generated based on the _index.html
. content/dir1/dir2/
becomes a section and the list page contains links to all pages in this section. It seems all pages in this section will NOT appear in the list page of the parent section anymore. Hugo automatically creates list page for top level directories in content/
.
In each markdown file, remove the draft: true
in the front matter to publish.
The hugo
command will generates a public/
folder, which you can put on the server. Don't forget to add public/
to .gitignore
file.
To create a template is basically to create you own theme. You can either put the files in themes/your_theme/layouts/
, or in the layouts/
at top level which override the same file in the themes.
Default template: the list.html
and single.html
in layouts/_default/
.
Homepage template: layouts/index.html
.
Section template: if you want to have a special template for the list pages in posts/
, create a file at layouts/posts/list.html
for it.
We can put common parts of list.html
and single.html
into a base template, i.e. baseof.html
:
single.html
:
list.html
:
layouts/partials/
. For example, we can have a header.html
file for header template.
Custom variables:
Only available in templates (layouts/
), not available in content/
.
General form: {{ .Title }}
. Common variables: .Date
, .URL
, .Content
.
In front matter in markdown: myVar: "myValue"
, you can access it in the template by .Params.myVar
. If you did not define it, nothing shows up. No errors. For example:
In template: for example:
Again, functions are only available in layouts/
, not in content/
.
General form: {{ funcName param1 param2 }}
. Examples:
A real example - highlight current page's title in a menu:
Under archetypes
directory, the default.md
defines the front matter and common content of the markdown files when you create it via hugo new
.
The archetypes/dir1.md
file applies to new files created by hugo new dir1/new-file.md
.
Another way of thinking shortcodes is to treat them as functions (in the context of programming). The general form of shortcode is:
which is basically just
To use the custom shortcode (call the function) in the markdown files in content/
, we need to add a shortcode template in layouts/shortcodes/shortcode-name.html
(define the function).
In the markdown file, a shortcode can take in positional (e.g. {{</* youtube 2xkNJL4gJ9E */>}}
) or named parameters (e.g. {{</* img src="a.png" */>}}
).
In the template, use {{.Get 0}}
or {{.Get "src"}}
to get the passed in values.
In the following case, the template cannot use quotes to wrap color, so ` is used instead.
Use a double tag shortcode if you want to pass in a large block of text.
In the markdown file, call it as follows:
In the template, access the text between the opening and closing tags via {{.Inner}}
.
If the inner text needs further markdown processing (e.g. **bold**
), call the shortcode with % % instead of < >:
Pages in content/
can be grouped by taxonomies. The default two taxonomies are tags and categories. In config.toml
, add the following lines:
To disable category, use category = ""
. To add a custom taxomony (e.g. mood), add mood = "moods"
.
In content markdown files, the front matters can contain taxonomy information:
In the single page, tag1
links to localhost:1313/tags/tag1/
, which is a list page that shows all single pages with tag1
as one of their tags.
data/
directory: we can put json, yaml, and toml files. For example, we can have a states.json
, which contains an array of "state" objects, which have a "name" field. and in templates:
I created layouts/shortcodes/pen.html
and copied a shortcode for codepen from .
I generated favicon files and put them under static/
.
Alternatively, if you host your site on , when you push your changes to GitHub, Netlify will rebuild and publish your site.
We can embed resources from other websites (e.g. YouTube) using shortcodes without writing a long iframe HTML code. For example, to embed a YouTube video at , All I need to do is to add {{</* youtube 2xkNJL4gJ9E */>}}
in the markdown file. Hugo will expand that "shortcode" into the iframe HTML code.
Hugo has built-in shortcodes for Twitter, Instagram, YouTube, Vimeo, etc. See for more.