【2.1.1】hugo

因为被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/

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

我下载的主题:

三、调试与部署

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:

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

参考资料

这里是一个广告位,,感兴趣的都可以发邮件聊聊:tiehan@sina.cn
个人公众号,比较懒,很少更新,可以在上面提问题,如果回复不及时,可发邮件给我: tiehan@sina.cn