【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/
然后就可以看到我们的网页生成哒
我下载的主题:
- 文档介绍主题 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