【2.1.1】hugo

May 06, 2015 blog 阅读量：次

因为被Rmarkdown的魅力吸引，从而了解bookdown,有因为对bookdown的惊叹，认识了大鹏志（http://dapengde.com/ http://www.pzhao.org/zh/）和谢益辉 https://yihui.name/cn/about/ ，然后再认识到Hugo，这里面的故事后面再聊，我们还是先来认识一下Hugo吧

一、介绍

Hugo是一个用Go语言编写的静态网站生成器，它使用起来非常简单，相对于Jekyll复杂的安装设置来说，Hugo仅需要一个二进制文件hugo(hugo.exe)即可轻松用于本地调试和生成静态页面。

博客文章可以以文本文件的方式（MarkDown）在本地维护管理，不需要像之前那样在网页的编辑器里提交到网站数据库。你可以方便的使用github管理你的博客文章，不会丢失，又能追溯到每一次的内容变更。

Hugo官方主页：https://gohugo.io/
入门文档：http://www.gohugo.org/
中文文档： http://www.gohugo.org/doc/
官方文档：https://gohugo.io/overview/introduction/
皮肤列表：https://github.com/spf13/hugoThemes

二、安装与生存静态网页

Hugo的安装方式有两种：

一种是直接下载编译好的Hugo二进制文件。如果只是使用Hugo推荐用这种方式。
另一种方式是获取Hugo的源码，自己编译。

下载位置： https://github.com/gohugoio/hugo/releases

我选择的是mac版34位的下载

weget -c https://github.com/gohugoio/hugo/releases/download/v0.26/hugo_0.26_macOS-64bit.tar.gz
tar -xzf hugo_0.26_macOS-64bit.tar.gz

下载下来后，只有一个叫hugo或者hugo.exe的程序，接下来开始生成自己的站点：

./hugo new site mysite

然后hugo会自动生成这样一个目录结构：

▸ archetypes/
▸ content/
▸ layouts/
▸ static/
  config.toml

简要介绍一下，config.toml是网站的配置文件，这是一个TOML文件，全称是Tom’s Obvious, Minimal Language，这是它的作者GitHub联合创始人Tom Preston-Werner 觉得YAML不够优雅，捣鼓出来的一个新格式。如果你不喜欢这种格式，你可以将config.toml替换为YAML格式的config.yaml，或者json格式的config.json。hugo都支持。

content目录里放的是你写的markdown文章，layouts目录里放的是网站的模板文件，static目录里放的是一些图片、css、js等资源。

进入生成的site目录：

cd mysite/

创建一个页面：

../hugo new about.md

然后会提示/Users/tanqianshan/Documents/3.blog/mysite/content/about.md created

如果是博客日志，最好将md文件放在content的post目录里。

../fhugo new post/first.md

这个时候会提示：/Users/tanqianshan/Documents/3.blog/mysite/content/post/first.md created 执行完后，会在content/post目录自动生成一个MarkDown格式的first.md文件：

---
title: "First"
date: 2017-08-24T15:54:20+08:00
draft: true
---

+++可以替换为Jekyll一样的—，里面的内容是这篇文章的一些信息。下面就可以开始写你的文章内容，比如：

默认生成的网站是没有任何皮肤模板的。为了看看第一个写的示例，还得去Github上把一个网页模板下载下来。如果你网络够好，网速够快，你可以在刚才的目录将Hugo官方的所有模板都下载下来(不建议下所有的，真心太花时间啦)：

git clone --recursive https://github.com/spf13/hugoThemes themes

或者选择现在其中的一个模板：

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

启动本地调试：

$ ../hugo server --theme=hyde --buildDrafts

（注明：v0.15 版本之后，不再需要使用 –watch 参数了）然后，根据提示，浏览器里打开： http://localhost:56626/

然后就可以看到我们的网页生成哒

我下载的主题：

文档介绍主题 git clone https://github.com/progrhyme/hugo-theme-bootie-docs.git
很干净的主题 git clone https://github.com/vimux/mainroad

三、调试与部署

3.1. 调试

../hugo server --theme=hyde --buildDrafts

3.2. FTP/SFTP上傳

光本地的肯定不够撒，我的目标是需要把他放到我的服务器上去。如果是在vps下部署，那么hugo转换后的public文件夹可以被直接用于部署到像nginx、apache、caddy这样的Web Server下面。

当我们写好内容以后，需要把内容放到服务器上去的时候，我们不能mysite底下的资料目录都丢到我服务器上去，而是在mysite文件夹下启动一个命令

$../hugo --theme=hyde

hugo命令是启动网站内容生成的命令，这里面没有加server这个参数，就是没有必要启动本电脑的服务器模拟功能，hydee为指定的使用的主题，当然也可以指定其他在themes中的主题哦。通过这个命令后，可以看到mysite文件夹下多了一个文件夹public，这个就是Hugo把新网站自东道国转换的css,html等网页语法的框架，原则上这个文件夹底下的东西，就是我们要公开到网络上供其他人阅读交流的。

不过在形成pulic文件夹的命令之前，先要修改mysite文件下的config.toml中的baseurl信息，就是把正确的网址填进去，这样在执行Hugo命名后自动产生的Pulic内容相应的链接才真确。

baseURL = "http://hugo.qinqianshan.com/"
languageCode = "zh-tw"
title = "My New Hugo Site"

[Params]
 Author='sam'

打开ftp软件（我用的是Pycharm）,将pulic下面的东西都丢到http://hugo.qinqianshan.com/对应的文件夹下面即可。

当然，当然hugo本身也可以作为一个Web server来支撑你的静态站点，就像上面提到的，你可以在你的站点目录(比如上面的”tonybai.com”)下执行：

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

如果无法使用80端口（比如通过apache2反向代理），那么需要加上–appendPort=false，否则转换后的public下面的url地址都会带上你的hugo端口（1313）：

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

3.3. gtihub

hugo --theme=hyde --baseUrl="http://coderzh.github.io/"

如果一切顺利，所有静态页面都会生成到 public 目录，将pubilc目录里所有文件 push 到刚创建的Repository的 master 分支。

$ cd public
$ git init
$ git remote add origin https://github.com/coderzh/coderzh.github.io.git
$ git add -A
$ git commit -m "first commit"
$ git push -u origin master

浏览器里访问：http://coderzh.github.io/

自动部署的脚本可以参考Repo里的deploy.py脚本：https://github.com/coderzh/coderzh-hugo-blog 全自动化部署到GitHub和GitCafe，见博客：https://blog.coderzh.com/2015/09/13/use-webhook-automated-deploy-hugo/

四、配置与维护站点

4.1 配置分类、标签

由于我们使用了hyde theme，所以我们只需看themes/hyde下面的目录结构即可，tonybai.com下面的除content之外的其他layout, data等可忽略不计。

mysite/themes/hyde/archetypes/default.md

+++
Description = ""
Tags = ["Development", "golang"]
Categories = ["Development", "GoLang"]
menu = "main"
+++

在hyde/archetypes下存放着这个主题下文章的默认分类和tags集合。这个default的作用是每次new post后，hugo会将default中的tags和categories自动copy到Post头中的tags和categories中。

每个Post的分类和tag在post自身的.md文件头中指定，见Categories和Tags两个配置项：

mysite/content/welcome.md

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

+++

你可以根据需要在你的post md文件中灵活增删你的tags和categories，不局限于default.md中的那些已知项。

4.2、修改字体样式 (未尝试)

hyde主题的字体样式在tonybai.com/themes/hyde/layouts/partials/head.html中指定：

缺内容

由于googleapis在国内无法访问，因此要么注释掉这行（使用浏览器默认字体样式），要么将其换为其他字体公共服务，比如：

缺内容

字体的设置在tonybai.com/themes/hyde/static/css下的各个css文件中，谨慎调整。

4.3、添加评论功能 (未尝试)

多说 2017年6月1日停止服务网易云跟帖 2017年8月1日停止服务自建的评论系统挑了 ISSO 和 HashOver Disqus 国外最流行的 ,需要翻墙 Gitment 是作者实现的一款基于 GitHub Issues 的评论系统不是对话式的评论，所以放弃来必力需要FW，中间很多环节是韩语，弃坑

有言最后选择有言

themes/hugo-xmin/layouts/partials/foot_custom.html中添加

{{ if .IsPage }}
  {{ partial "youyan.html" . }}
{{ end }}

youyan.html为注册以后提供的一段代码，放到yoyan.html文件汇总即可

各种评论工具汇总(超赞) https://blog.shuiba.co/comment-systems-recommendation

4.4、代码高亮 (未尝试)

Hugo官方说明中采用Pygments来进行代码高亮的支持，在部署机上安装Pygments，个人觉得这个方法不好。于是换另一外一种js代码法，即采用highlightjs的方法支持代码高亮。

highlightjs同样很强大，支持135种语言（关键是支持Golang）和60多种样式（有我喜爱的github样式和monokai_sublime样式），但不支持linenumber。

我们首先将highlightjs下载到本地:

mysite/themes/hyde/static/css/highlight.js/8.8.0/styles/github.min.css
mysite/themes/hyde/static/js/highlight.js/8.8.0/highlight.min.js

然后在tonybai.com/themes/hyde/layouts/partials/head.html添加如下代码:

缺内容

highlightjs会自动检测语言类型，并使用github样式。

4.5、统计代码

提供统计服务的站点，比如statcounter.com一般都会提供安装代码（js）的，将那段代码copy到mysite/themes/hyde/layouts/partials/head.html中即可。

4.6.统计分类中的文章数

在list.html中添加

{{ $count := sub (len .Data.Pages) 1 }}
{{ $count2 :=add $count 1 }}
<p> 总篇数：{{ $count2 }}</p>

在index.html中统计

{{ $count := sub (len .Site.RegularPages) 1 }}
{{ $count2 :=add $count 1 }}

注：

Site.Pages = All the Pages (note the capital P) in the site.
.Data.Pages: All the Pages for the given Node (sections, taxonomies). This will be a subset of the above for all other nodes than the home page: On that Node I believe these slices are the same.

4.7.自定义文章列表的排序

在md文章的加入weight

---
author: sam
comments: true
date: 2018-01-15 08:19:50+00:00
#layout: post
slug: biodatabase-description
title: 1.生物数据库概述
weight: 1
---

在layout/list.html中增加

<ul>
	{{ range .Data.Pages.ByWeight }}
  <li>
    <span class="date">{{ .Date.Format "2006/01/02" }}</span>
    <a href="{{ .URL }}">{{ .Title }}</a>
  </li>
  {{ end }}
</ul>

在Index.html中加入：

<ul>
  {{ range (where .Site.RegularPages.ByDate.Reverse "Section" "!=" "") }}
  <li>
    <span class="date">{{ .Date.Format "2006/01/02" }}</span>
    <a href="{{ .URL }}">{{ .Title }}</a>
  </li>
  {{ end }}
</ul>

五、进阶

5.1 index.html、single.html和list.html

站点的首页模板在themes/hyde/layouts/index.html中。除首页外，其他Post或叫Page，都被Hugo抽象为两类：单体页面和列表页面，对应这两种页面的默认模板都在themes/hyde/layouts/_default中，分别对应着single.html和list.html。

我们之前通过hugo new welcome.md创建的Post使用的是single.html模板，而查看tags或categories的页面默认采用的是list.html，比如查看tonybai.com/categories/golang，你会在浏览器中看到分类在golang这一类的所有Post列表。

5.2 type和section

我们执行如下两个命令：

$hugo new post/firstpost.md
mysite/content/post/firstpost.md created
$hugo new post/secondpost.md
mysite/content/post/secondpost.md created

创建后我们可以看到站点的源文件结构变成了：

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

hugo中源码文件的布局影响着最终生成的html文件的结构布局。有些时候我们的站点可能会分成若干个部分，每部分通过目录隔离开，比如这里content下的post目录，这样hugo转换后，firstpost.html和secondpost.html也会在public的post目录下。这里的“post”被称为一个section。

hugo会为每个section自动生成index.html页，采用的是index.html模板。

至于是否采用的是hyde/layouts/_default下的list.html，这要看host的匹配order，官方给出的是：

/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 在本例子中，/layouts/下是空的，不予考虑。/themes/hyde/layouts下没有建立section/post.html模板，/themes/hyde/layouts/_default/section.html也不存在，因此用的是_default/list.html。

hugo官方建议静态站点源码文件按section组织，每个section使用相应(同名）的type，这样section下面的.md就会自动使用响应type的meta data。

当我们hugo new post/firstpost.md时，hugo会到archetypes下找是否有post.md文件，如果有则使用post.md文件的categories和tags来初始化content/post/firstpost.md的元数据，如果没有post.md，则使用archetypes/default.md的。

5.3 模板语言

Hugo使用Golang的模板语法，表达能力很强大；配合Hugo predefined的变量或自定义变量，你可以玩转模板。关于模板内容较多，这里不赘述，需要时查看 http://gohugo.io/templates/introduction/

PS:

差不多，先了解到这，后面有需求，再来改。

参考资料

http://www.gohugo.org/
http://self.jxtsai.info/2016/07/hugo_26.html
http://www.gohugo.org/post/coderzh-hugo/
http://studygolang.com/articles/4923
http://tonybai.com/2015/09/23/intro-of-gohugo/
Hugo 对比 Jekyll https://zhuanlan.zhihu.com/p/27552299
https://gohugo.io/commands/hugo_server/ # hugo对应的参数和命令文档

药企，独角兽，苏州。团队长期招人，感兴趣的都可以发邮件聊聊：tiehan@sina.cn

个人公众号，比较懒，很少更新，可以在上面提问题，如果回复不及时，可发邮件给我： tiehan@sina.cn