Use Hugo to build a static site

This is a creation in Article, where the information may have evolved or changed.

Although the previous blog claimed to use Markdown to start writing post, but the actual operation still found a lot of incompatibility problems (plug-in and theme, plug-in and plug-ins), so that writing and modifying the article becomes very cumbersome, so I studied the static Web site Generation tool Hugo. Hugo was a heavyweight employee of the former Docker (who resigned from Docker at the end of August 2015): Steve Francia implements an open source static site Generation tool framework, similar to Jekyll, octopress, or Hexo, which is a specific format ( The most common is the markdown format for converting text files to static HTML files and generating a static site, which is used for personal blog sites, project documents (the official Docker manual site is generated by Hugo), a start-up site, and so on. This kind of tool more and more by the programmer and so on the "geek" spirit of the community, combined with github.com and other version control services, with a simple syntax format but strong expression of markdown markup language, people can in a very short time to build a consistent with their own needs of a static web site. In these tools, Hugo is a rising star, its greatest advantage is fast! A medium-sized site can be generated within a fraction of a second. The second is good cross-platform features, simple configuration, easy to use and so on. All this stems from its good genes: it is implemented in the go language. In addition to the Hugo platform itself, Steve Francia maintains a Hugo theme repo, a Hugo theme library that can help Hugo users quickly find their favorite theme and quickly build static sites. There are not many people who use Hugo at home, but they are feeling the trend is growing. Here to write this post, but also for everyone into a door, lead a way.

I. Installation of Hugo

Hugo is hosted on the github.com, so there are at least two ways to get Hugo to install Hugo.

1. Installation package

For ordinary users (no git, no development experience), downloading the installation package directly is the simplest way. We can download Hugo's release version, so far the latest version is v0.14, where you can download the corresponding versions of your platform (Linux, Windows, Darwin, NetBSD, FreeBSD, and arm, etc.). However, I found that the 0.14 version seems to have bugs, and the Hugo Docs site generated on my macosx is always panic.

2. Source code Compilation

For developers, source code compilation is the Most geek way:

go get -u -v github.com/spf13/hugogo build -o hugo main.gomv hugo $GOPATH/bin

Execute the Hugo command at the command line, and if you get a result similar to the following, you have successfully installed Hugo:

$hugo versionHugo Static Site Generator v0.15-DEV BuildDate: 2015-09-20T23:53:39+08:00

Second, generate static site

1. Create a static site

Let's create a static site called "tonybai.com":

$hugo new site tonybai.com$tree.└── tonybai.com    ├── archetypes    ├── config.toml    ├── content    ├── data    ├── layouts    └── static

We see that, through the Hugo New site command, we have built the backend directory structure of the tonybai.com site. But careful you will find: The directory here is empty. In addition to the config.toml in the poor three line content:

baseurl = "http://replace-this-with-your-hugo-site.com/"languageCode = "en-us"title = "My New Hugo Site"

However, even if the directory is empty, this is also a complete static site source files, we can build our site based on these files.

$cd tonybai.com$hugo server0 draft content0 future content0 pages created0 paginator pages created0 tags created0 categories createdin 6 msServing pages from /Users/tony/test/hugotest/tonybai.com/publicWeb Server is available at http://localhost:1313/ (bind address 127.0.0.1)Press Ctrl+C to stop

The Hugo command above puts the repo into the public directory when converting to a static site file:

├── public│   ├── 404.html│   ├── index.html│   ├── index.xml│   └── sitemap.xml

After that, Hugo started a server as the Web server for that site. With a browser access to http://localhost:1313, you will see a completely blank site home page. Although this site has no practical value (a blank), but this is a good starting point.

2. Add Theme

Added theme after the site only flesh and blood, colorful.

To add theme, let's take Hyde theme as an example:

First create the Themes directory and download the Hyde theme file:

$ mkdir themes$ cd themes$ git clone https://github.com/spf13/hyde.git

Next, we need to configure the site, TONYBAI.COM/CONFIG.TOML is the site's top-level configuration file, the configuration of the Config.toml file as follows:

baseurl = "http://tonybai.com/"languageCode = "en-us"title = "Tony Bai"theme = "hyde"[params]    description = "这里是Tony Bai的个人博客"    themeColor = "theme-base-08" # for hyde theme

which
Theme = "Hyde" Specifies that the site uses Hyde themes;
ThemeColor = "Theme-base-08″ Specifies the theme color of the site (the default is black, this is changed to a red)

Re-execute the Hugo server in the Tonybai.com directory and open the browser to view the site homepage, you will find the content in the field of view:

3. First post

Structure and style have, we have no content yet. Let's create the first post of a site:

$hugo new welcome.md/Users/tony/Test/hugotest/tonybai.com/content/welcome.md created

Hugo creates a welcome.md file under content, and we write some file content:

+++Categories = ["Development", "GoLang"]Description = ""Tags = ["Development", "golang"]date = "2015-09-23T16:30:37+08:00"menu = "main"title = "你好，Hugo"+++这是使用Hugo创建的站点中的第一篇文章。

After saving, re-execute the Hugo Server command, open the browser, and you will see the following scenario:

At this point, if you are a minimalist, you do not have any other requirements, you can use this site to write post.

Iii. Commissioning and Deployment site

1. Commissioning the site

Using Hugo's static site in the editing of articles, debugging site is very convenient, you have to do is to edit the text, save, open the browser to see the results after rendering. But the repeated execution of the Hugo Server command was still a bit annoying, and Hugo had thought of it earlier, and Hugo offered:
-w, --watch[=false]

When you execute the Hugo Server command with the-w option, Hugo can automatically detect changes to local site files and automate the MD-to-HTML conversion. This will refresh the browser page to see the results of your changes:

$hugo server -w0 draft content0 future content1 pages created0 paginator pages created2 tags created2 categories createdin 16 msWatching for changes in /Users/tony/test/hugotest/tonybai.com/{data,content,layouts,static,themes/hyde}Serving pages from /Users/tony/test/hugotest/tonybai.com/publicWeb Server is available at http://localhost:1313/ (bind address 127.0.0.1)Press Ctrl+C to stop

By Hugo Server-w's output log, Hugo can automatically detect changes in the Data,content,layouts,static,themes/hyde directory, However, changes to the top-level config.toml of the site cannot be detected and the Hugo Server needs to be restarted.

2. Deploy the site

Like Jekyll, a static site that uses Hugo can be deployed to a GitHub page, but this method is not described in detail and can be seen in official documents

If deployed under VPS, the Hugo converted public folder can be used directly for deployment to Web servers like Nginx, Apache, Caddy, and so on.

Of course, Hugo itself can be a Web server to support your static site, as mentioned above, you can in your site directory (such as the above "tonybai.com") under the execution:

$sudo hugo server --bind="0.0.0.0" -v -w -p 80 -b http://tonybai.com

If you cannot use port 80 (for example, through apache2 reverse proxy), then you need to add –appendport=false, otherwise the URL address under the converted public will take your Hugo Port (1313):

$hugo server -v -w -p 1313 -b http://tonybai.com --appendPort=false

Iv. Configuring and maintaining the site

Most people will not stop at the above only can write post site, configure classification, label, modify font style, add comment function, increase the statistical code, add code highlighting (programmer favorite), and even custom theme is geek most like to toss things, here can't full table, enumerate a few common configuration and maintenance methods , or has been Hyde the subject as an example.

1. Configuration classification, label

In the browser enter: http://localhost:1313/categories/or http://localhost:1313/tags, you will see the site output a similar directory list like a page:

development/golang/

Where did development and Golang come from?

Hidden deeper, also to find it out:

tonybai.com/themes/hyde/archetypes/default.md+++Description = ""Tags = ["Development", "golang"]Categories = ["Development", "GoLang"]menu = "main"+++

Since we use the Hyde theme, we only need to look at the directory structure below the Themes/hyde, tonybai.com the following other than the content of the layout, data and so on negligible. The default category and tags collection for articles under this topic are stored under Hyde/archetypes. The default function is that after each new post, Hugo will automatically copy tags and categories from default to tags and categories in the post header.

The classification and tag of each post are specified in the. md file header of the post itself, see categories and tags two configuration items:

tonybai.com/content/welcome.md+++Categories = ["Development", "GoLang"]Description = ""Tags = ["Development", "golang"]date = "2015-09-23T16:30:37+08:00"menu = "main"title = "你好，Hugo"+++

You can flexibly delete your tags and categories as needed in your post MD file, not limited to those known items in default.md.

2. Modify the font style

The font style of the Hyde theme is specified in tonybai.com/themes/hyde/layouts/partials/head.html:

Because Googleapis is inaccessible in the country, either comment out the line (using the browser's default font style) or change it to a different font public service, such as:

Font settings are carefully adjusted in each CSS file under Tonybai.com/themes/hyde/static/css.

3. Add Comment function

Hugo does not have a built-in comment feature, and the ability to add comments requires the integration of third-party commenting services, such as the most popular disqus abroad. The Hyde theme has built-in Disqus comment plugin, but you need to configure it as follows, otherwise the Disqus plugin at the bottom of the page always shows that you cannot connect.

Get Disqusshortname

Here with Disqus Master Account No, you need to use the Master account login:Add a newsite to Disqus, such as join tonybaicom.disqus.com, so your disqusshortname is: tonybaicom;

Configure Disqusshortname

Configure the Disqusshortname in TONYBAI.COM/CONFIG.TOML:

[params]    disqusShortname = "tonybaicom"

If you want to use the domestic comment service, for example: Say more, you can refer to tonybai.com/themes/hyde/layouts/partials/disqus.html, with the more said install code to replace Disqus code, Form duoshuo.html:

Then replace the following code in tonybai.com/themes/hyde/layouts/_default/single.html:

{{ if and (isset .Site.Params "disqusShortname") (ne .Site.Params.disqusShortname "") }}                
Comments
                {{ partial "disqus" . }}            {{ end }}

is similar to the following code:

{{ if and (isset .Site.Params "duoshuoShortname") (ne .Site.Params.duoshuoShortname"") }}                
Comments
                {{ partial "duoshuo" . }}            {{ end }}

Note: Once you use the above-mentioned code, you need to configure Duoshuoshortname in CONFIG.TOML:

[params]    duoshuoShortname = "tonybaicom"

4, code highlighting

Hugo official note In the use of Pygments for code highlighting support, install pygments on the deployment machine, personally think this method is not good. Therefore, another external JS code method, that is, the use of Highlightjs method to support code highlighting.

Highlightjs is also very powerful, supports 135 languages (key is support Golang) and 60 styles (with my favorite GitHub style and monokai_sublime style), but does not support linenumber.

We will first download Highlightjs to Local:

tonybai.com/themes/hyde/static/css/highlight.js/8.8.0/styles/github.min.csstonybai.com/themes/hyde/static/js/highlight.js/8.8.0/highlight.min.js

Then add the following code to the tonybai.com/themes/hyde/layouts/partials/head.html:

Highlightjs automatically detects language types and uses the GitHub style.

5. Statistical code

The site that provides the statistic service, for example Statcounter.com General will provide installs the code (JS), copy that piece of code to tonybai.com/themes/hyde/layouts/partials/head.html.

Four, advanced

1, index.html, single.html and list.html

The homepage template of the site is in themes/hyde/layouts/index.html. In addition to the first page, the other post or page, are Hugo abstract two categories: single page and List page, corresponding to the two pages of the default template are in Themes/hyde/layouts/_default, respectively, corresponding to single.html and list.html.

The post we created with Hugo New welcome.md was using the single.html template, and the page viewing tags or categories by default was list.html, such as viewing tonybai.com/ Categories/golang, you will see in the browser all the post lists categorized in the Golang category.

2. Type and section

We execute the following two commands:

$hugo new post/firstpost.mdtonybai.com/content/post/firstpost.md created$hugo new post/secondpost.mdtonybai.com/content/post/secondpost.md created

Once created, we can see that the source file structure of the site has become:

... ...├── archetypes├── config.toml├── content│   ├── post│   │   ├── firstpost.md│   │   └── secondpost.md│   └── welcome.md... ...

The layout of the source file in Hugo affects the structure layout of the resulting HTML file. Sometimes our site may be divided into sections, each separated by a directory, such as the post directory under Content, so that after Hugo transforms, firstpost.html and secondpost.html will also be in the public post directory. Here the "POST" is called a section.

Hugo will automatically generate index.html pages for each section, using the index.html template.

As to whether the use of hyde/layouts/_default under the list.html, this depends on the host's matching order, the official given is:

/layouts/section/SECTION.html/layouts/_default/section.html/layouts/_default/list.html/themes/THEME/layouts/section/SECTION.html/themes/THEME/layouts/_default/section.html/themes/THEME/layouts/_default/list.html这个例子中THEME=hyde, SECTION=post

In this case, the/layouts/is empty and is not considered. Section/post.html template is not established under/themes/hyde/layouts,/themes/hyde/layouts/_default/section.html does not exist, so _default/is used. List.html.

Hugo Official recommends static site source code files are organized by section, each section uses the corresponding (same name) type, so that the. MD below the section will automatically use the meta data of the response type.

When we Hugo New Post/firstpost.md, Hugo will go to archetypes to find out if there are post.md files, if any, categories and tags that use post.md files to initialize content/post/ FIRSTPOST.MD metadata, if not post.md, uses archetypes/default.md.

3. Template language

Hugo uses Golang's template syntax to be powerful, and with Hugo predefined variables or custom variables, you can play with the template. More about the template content, here do not repeat, when needed to view the official detailed manual.

Bigwhite. All rights reserved.