基于Hugo搭建静态博客站点

分类: golang

  

主题: blog

  

标签: markdown hugo

by Crius

1 缘起

经常上Github的人，一定对项目文档里的README.md不陌生，此文件一般是项目的简介文档，直接点击就能在浏览器里查看，展现的源码格式是HTML的。早就听闻md文件是用Markdown语法编写的，最近空闲，对Markdown研究了下。首先是熟悉感，因为之前对另一个文档标记语言reStructuredText比较熟悉，用sphinx工具写过很多项目文档，Markdown一样，也是一种轻量级标记语言，它的语法受到了很多种text-to-HTML格式标记语言的影响，其中就包括reStructuredText。 Markdown语法大约从2004年就开始创建，随着GitHub, reddit等知名开源站点的应用，逐渐得到普及，在2016年3月份被吸收为RFC7763 and RFC 7764文档，作为一种新的HTML文件MIME type格式（text/markdown），目前网络上有众多的离线和在线编写工具可供使用，相比reStructuredText而言，简直方便太多了。这促使了我想用Markdown写项目文档的想法，搜索编辑和渲染工具，比较后首先发现的是markdownpad软件，运行在windows平台上，具有代码高亮和实时预览的功能，这对于新手来说是最方便的了。

关于Markdown的资料，这里做一个链接：wikipedia，csdn博文，zhihu问答，Markdown语法。

偶尔发现了Hugo。Hugo吸引我的原因：

  1. 它是用golang语言编写的，恰好我最近在玩Golang，之前看到过一个Golang 10大开源项目榜单，Hugo貌似在列。再次遇见，很想clone下来研究下；
  2. Hugo是一个静态博客站点构造工具，能把Markdown格式的博文生成为HTML格式，也支持实时渲染。 博客站点，我之前是用Wordpress的，最大的痛感其实也是动态博客站点的缺点，首先是搭建麻烦，要安装数据库、PHP等，发布在云虚拟机上，由于资源有限，还要进行优化配置，复杂度高，麻烦！其次是不安全感，搞应用的考虑最多的是服务的高可用，线上代码要做备份方案，极端情况下要异地部署，个人站点一般是单机部署，mysql备份、同步和恢复比较繁琐，如果哪天云主机挂了，疏于管理被关了咋办？Wordpress出bug了，数据丢了咋办？博客迁移到其他系统，多麻烦？Hugo的方案都能解决。首先部署简单，得益于Golang的发布方式，一个可执行文件丢上去就能运行，源码编译也行；博文在本地编写md文件，写完rsync上去，就能自动生成HTML发布；备份？天生的备份，构造程序和md文件本地保留着，一键rsync到服务器就能运行。Hugo还支持按Topic、Tag、和日期归档列表，基本够用了。但是评论和统计需要借助于三方服务，但是这对我来说不重要，我的个人博客就是用来技术笔记和思路整理的。

关于Hugo的一切资料，包括简介、Realase、模版和安装说明等，都能在Hugo官站上找到。作者的Github主页https://github.com/spf13/，repository是hugo和hugoThemes。

2 构造站点

2.1 Hugo安装

Hugo安装有二进制和源码安装两种方式。 截至2016.12.9，作者两种方式都尝试了，但源码安装后有点问题：在Windows下运行始终失败，Linux下的归档功能有bug（.Site.Pages.GroupByDate时获取不到数据）。最终下载了releases版本0.17,运行才正常。两种方式都记录一下：

源码安装：

go get github.com/spf13/hugo        
cd  /gosrc/src/github.com/sp13/hugo     
go get  
go build -o /go/bin/hugo github.com/spf13/hugo

二进制安装：下载相关系统的release包，解压到任一目录，并确保此目录在PATH环境变量中。

2.2 Hugo简单使用

查看完整Hugo运行参数

hugo -help

常用命令：

  • 创建站点

运行hugo new site 命令，创建目录结构

hugo new site /data/gorun/blog      

会自动生成这样一个目录结构：
▸/data/gorun/blog
    ▸ archetypes/
    ▸ content/
    ▸ content/
    ▸ data/
    ▸ static/
    ▸ themes
    config.toml

这几个文件夹的作用不赘述，实际使用过程中，下载的模版，放到themes目录下，发布的md博文，放到content目录下。

  • 启动站点调试，运行hugo server命令

    hugo server –port=80 –buildDrafts –watch –verbose

运行后，访问本地 http://localhost， 就能打开博客站点了。不过目前页面是空白的，因为还没有Theme。另

hugo server --buildDrafts -w
参数-w意味监视watch，此时如果修改了网站内的信息，会直接显示在浏览器的页面上，不需要重新运行$hugo server，
  • 生成站点

运行示例

cd /data/gorun/blog 
hugo -d="/data/nginx/blog"
nohup hugo -d="/data/nginx/blog" -w &

表示把当前目录的hugo项目，生成到指定目录下。生成后配置nginx站点，指定到该目录就能访问了。

  • 使用Themes：下载喜欢的样式到themes目录

hugo项目的模版在https://github.com/spf13/hugoThemes，但是不要一下子把所有样式都下载完，完整下载有700多兆，下载慢，也会加重网站负担。可以在 http://themes.gohugo.io/先挑选喜欢的样式，再下载。个人比较喜欢bootstarp风格的hugo-bootstrap-premium模版，下载方式：

cd  /data/gorun/blog/themes
git clone https://github.com/spf13/hugo-bootstrap-premium

下载后把exampleSite中的config.toml配置文件和content目录下的文件拷贝到项目目录。

再运行hugo server就能看到效果了。

3 hugo-bootstrap-premium样式改造

hugo-bootstrap-premium的 样例站点如下图所示。

![最终效果] [theme_samle]

如图红框所示，我们要在导航条空白位置加一个网站标题，在右侧sidebar下方加一个按月份归档。

  • 添加标题

查看首页模版文件 layouts/index.html，三行代码：

{{ partial "head" . }}
{{ partial "homepage" . }}
{{ partial "foot" . }}

按照字面意思揣摩，应该是嵌套了三个子模版。然而partial是什么意思？ 在Golang的Template语法里并没有这个关键字啊。在hugo项目中搜索partial，我们很容易发现它是hugo项目内定义的一个模版语法关键字。代码如：https://github.com/spf13/hugo/blob/master/tpl/template_funcs.go#L2086。 作者实现的模版语法还是相当全面的，牛！ 好了我们先不研究模版语法。先来实现功能吧。 按照模版嵌套，逐层深入打开文件，最终在 layouts/partials/base/header.html文件里发现了最终代码。

在导航栏的logo和菜单所在的两个div中间，插入代码：

<div class="collapse navbar-collapse navbar-header" >
    <h5 style="margin:25px 0 0 20px;" class="text-center">{{.Site.Title }}</h5> 
</div>

使用了bootstrap的预定义响应式样式，当页面变窄时能自动隐藏。

  • 添加sidebar归档

在layouts/partials/bloc/content/sidebar.html文件 最外层div内添加

{{ if not (eq (len .Site.Pages) 0) }}
<div class="section taxonomies">
    <header><div class="title"><b>归档</b></div></header>
    <div class="content">
      <ul>
        {{ range $value := .Site.Pages.GroupByDate .Site.Params.MonthFormat }}
         {{ $url := (index $value.Pages 0).Node.Date.Format "2006-01" | urlize }}
        <li><a href="{{ $.Site.BaseURL }}/post/#{{ $url }}">{{ .Key }} ({{ len $value.Pages }}篇)</a></li>
        {{ end }}
      </ul>
    </div>
</div>
{{ end }}

同时在config.toml内的params块内添加

[params]
    MonthFormat = "2006-01"
  • 使用catalog分类

样例里sidebar只有tag和topic分类，我们现在来添加一个catalog分类。只需要在config.toml内添加

[taxonomies]
    catalog = "categories"
    topic = "topics"    
    tag = "tags"

另外在写md博文时，在文件头内把categories标签写上。

+++
date = "2016-12-09T12:00:00+08:00"
draft = false
title = "基于Hugo搭建静态博客站点"
author = "Crius"
categories = ["工具","开源项目"]
topics = ["文档编写"]
tags = ["静态博客", "Markdown", "Hugo", "Golang"]

+++


## 一、缘起
经常上Github的人，一定对项目文档里的README.md不陌生，此文件一般是项目的简介文档，直接点击就能在浏览器里查看，展现的源码格式是HTML的。早就听闻md文件是用Markdown语法

最终效果如下图：

  • todo

hugo-bootstrap-premium样式比较复杂，它内嵌了评论、统计代码、社交帐号等等，对于国内用户来说，很多功能可能还用不上，得根据需要裁剪。

2016.12.9 16:00