hugo-Framework Learning

Concept

Hugo is a static site builder implemented by the go language. Simple, easy to use, efficient, easy to scale, fast to deploy.

Mainly used for personal blog, project documents, start-up site construction.

Hugo's download installation is very simple, you can refer to the official QuickStart, this article mainly introduces the basic concept of the Hugo Framework and working principle .

Directory structure

Order: Hugo new Site Blog

blog├── archetypes├── config.toml├── content├── data├── layouts├── static├── themes└── public

Archetypes

When you create a content page with Hugo new XXX, by default, Hugo creates a front matter such as date, title, and so on, you can set a custom front matter by creating a file in the archetypes directory.

Config.toml

All Hugo sites have a global profile that configures the information for the entire site, and Hugo defaults to providing multiple configuration instructions.

Content

All content pages under the site, that is, the MD files we created are under this content directory.

Data

The data directory is used to store Web sites with some configuration, data files. The file type can be a format such as Yaml|toml|json.

Layouts

A template file that is used to render the contents of the content directory, the template. End of HTML format, layouts can be stored in both the project directory and the Themes/<theme>/layouts directory.

Static

Used to store images, CSS, JS and other static resource files.

Themes

Used to store themes, themes can easily help us to quickly set up a site, you can easily switch the style of the site.

Public

Hugo compiles all the files of the Web site that are stored here, and put this directory on any Web server to publish the site successfully.

Page bindings

Page Bundles

The content organization in Hugo relies on page bundles to manage it. Page bundles includes the leaf bundle (No child nodes) and the branch bundle (home page, section, taxonomy terms, taxonomy list) in two categories.

	Leaf bundle	Branch Bundle
Index file	Index.md	_index.md
Layout type	Single	List
Nesting	Nesting is not allowed	Allow leaf or branch bundle nesting

Section

A section is a collection of pages based on the organization structure defined in the content/directory.

The first level sub-directory under content/is a section. If you want to make a subdirectory a section, you need to define the _index.md file under the directory. All sections form a section tree.

content└── blog        <-- Section, 因为是content的子目录    ├── funny-cats    │   ├── mypost.md    │   └── kittens         <-- Section, 因为包含_index.md    │       └── _index.md    └── tech                <-- Section, 因为包含 _index.md        └── _index.md

If the section tree needs to be navigable, at least the bottommost part needs to define a _index.md file.

Front matter

Front matter is used to configure the title, time, link, category and other meta-information of the article, provided to the template call

+++title = "post title"description = "description."date = "2018-08-20"tags = [ "tag1", "tag2", "tag3"]categories = ["cat1","cat2"]weight = 20+++

Templates

Hugo uses the Html/template Library of the Go language as the template engine to render content into HTML through templates as a bridge between content and display views.

Hugo is made up of three types of templates: Single, list, and partial.

Hugo has his own template lookup mechanism, and if you can't find the templates that exactly match the content, it will move up one level and search from there. Try it until you find a matching template or run out of templates. If the template is not found, it will use the site's default template.

Single Template

The single template is used to render page content.

List Template

The list template is used to render a set of related content, such as all content under a site, and content under a directory;

Homepage is _index.md, is a special type of list Template,homepage is actually a site of all the content of the portal.

Partial Template

The partial template can be referenced by other templates and can actually be understood as a template-level component, such as the head of the page, the bottom of the page, and so on.

Basic template Query Rules

The basic template refers to the search rule for baseof.html

1. /layouts/section/<TYPE>-baseof.html2. /themes/<THEME>/layouts/section/<TYPE>-baseof.html3. /layouts/<TYPE>/baseof.html4. /themes/<THEME>/layouts/<TYPE>/baseof.html5. /layouts/section/baseof.html6. /themes/<THEME>/layouts/section/baseof.html7. /layouts/_default/<TYPE>-baseof.html8. /themes/<THEME>/layouts/_default/<TYPE>-baseof.html9. /layouts/_default/baseof.html10. /themes/<THEME>/layouts/_default/baseof.html

Page template Query rules

Kind

Determine if the page is a single page or a list page?

If it is a single page, the template will be selected _default/single.html

If it is a list page (section listings, home page, taxonomy lists, taxonomy terms), the template will be selected _default/list.html

Output Format

Select a matching template based on the name and suffix of the output format. For example, the output format is RSS, the suffix is. html, first see there is no matching index.rss.html format template.

Language

Select the matching template according to the language of the site settings, for example, the language of the site is FR, the priority of the template match is: index.fr.amp.html > index.amp.html > index.fr.html

Layout

You can set the front matter:layout on the head of the page, and the Settings page renders with the specified template, for example, the page is under directory posts (the default section), Layout=custom, and the lookup rule is as follows:

• Layouts/posts/custom.html
• Layouts/posts/single.html
• Layouts/_default/custom.html
• Layouts/_default/single.html

Type

If the property type property, such as Type=event, is set on the head of the page, the lookup rule is as follows:

• Layouts/event/custom.html
• Layouts/event/single.html
• Layouts/events/single.html
• Layouts/_default/single.html

Grammar

Basic syntax

Go-template Basic Syntax

Block

By defining a block in the parent template {{ block "xxx"}} , you can replace it with {{define "xxx"}} the defined content in the submodule.

{{< button Theme= "info";} template definition {{</button;}}

{{ define "chrome/header.html" }}  <div>{{ .Site.Params.author}}</div>{{ end }}

Template reference

method One : partial (recommended)

For the introduction of a defined local template, the local template location must be in the Themes/layouts/partials or layouts/partials directory.

{{ partial "chrome/header.html" . }}

method Two : template

Template is used in some older versions to introduce a defined local template, which is now still used in the internal template.

{{ template "chrome/header.html" . }}

{{-xxx-}}

-Used to remove spaces, for example:

1. {{-xxx} to remove whitespace from {{-}
2. {{xxx-} for removal-}} The space behind
3. {{-xxx-}} to remove spaces on both sides

Paginator

. Paginator is primarily used to build menus, and can only be used in homepage, listpage.

{{ range .Paginator.Pages }}   {{ .Title }}{{ end }}

Short Code

The Short code (shortcodes) is equivalent to some custom templates, which, by reference in the MD documentation, generate code snippets similar to those in some JS frameworks.

The short code must be defined in the Themes/layouts/partials or layouts/partials directory.

Short code references in the template file are not valid and can only be referenced in the *.md file under the content directory.

Citation method

{{%/* msshortcodes params1="xxx" */%}}**this** is a text{{%/* /msshortcodes */%}}{{</* msshortcodes params1="xxx"  */>}} **Yeahhh !** is a text {{</* /msshortcodes */>}}

1. % indicates that the content in the short code needs to be rendered further
2. < represents a content item in the middle of a short code that does not require further rendering

Taxonomy

Hugo uses taxonomy to enable users to group content. Taxonomy needs to be defined in the site configuration file:

[taxonomies]  category = "categories"  tag = "tags"  series = "series"

By default, Hugo provides category, tag two categories, do not require the user to define in the configuration file, but if there are other taxonomy definitions, the default tag, category also needs to be defined;

How to use

1. Add taxonomy in the site configuration file, for example: series
2. Define the taxonomy list template; For example, in layouts/taxonomy/series.html
3. Set term in the front matter of the content file, for example, series = ["S1", "S2"]
4. Access the taxonomy list, for example, LOCALHOST:1313/SERIES/S1

Variable

Hugo provides a number of different types of variables for creating templates and building sites.

Site

Most site variables are defined in the site configuration file (config. [Yaml|toml|json])

. Site.menus: All menus under the site

. Site.pages: All pages under the site

. Site.params: Parameters under the site

Page

Page-level parameters are defined in the front matter of the page header, for example:

+++title = "Hugo"date = 2018-08-13T18:29:20+08:00description = ""draft = falseweight = 10+++

How to use

{{ .Params.xxx }} 或者是 {{ .Site.Params.xxx }}