hugo快速建站

Sun, Nov 15, 2015

本来想直接研究hugo的theme结构和相关配置的，但是自己在Github Pages上建站的过程中尽管参考了其他人的教程，还是有过一些错误，导致了一些问题，因此想再用自己的话梳理一下过程和方法，强调一下容易出错的地方，尽量追求全而细，让能看到这篇文章的人，不管有没有编程方面的经验都能够实践成功。来吧，让我们使用windows+msysgit+Github+hugo来实现自己的个性化页面。相关软件打包：百度云，提取码：aca1。

1.准备工作
2.正式建立静态网站
3.高级配置
- 3.1 多说评论
- 3.2 代码高亮
4.后记

1.准备工作

1.1 msysGit客户端

在Windows下默认是没有预装Git的，如果你是Mac和Linux的用户则没有这个烦恼，因此我们首先需要在Windows系统下安装一个Git软件，笔者使用的是msysGit，截止发文最新的版本是2.6.3，官网Download会自动识别系统（32位和64位）下载，之后一个个步骤按照向导安装就行，上面英文写的很清楚，基本可以按照默认的来，但是到了Ajusting your PATH environment（即设置环境变量）这一步时，建议还是勾选第二项Run Git from Windows Command Prompt，这样在Windows命令行中就可以全局使用Git相关命令。

1.2 注册Github

点击Github官网进入Github首页，这样你能够进行注册，输入用户名、Email地址、密码即可进行注册，我们选择不需要花钱的Free类型用户，点击Finish sign up，这样即可完成注册，此时在页面顶部Bootcamp系统会提示你接下来可以做哪些事情，而我们首先需要做的就是Create Repositories，我们可以点击这一项进去看看教程，当然也可以根据我下面的提示直接开始：

点击右侧New repository（新建仓库），此时系统会提示你验证邮箱，你需要去刚刚注册用的邮箱验证地址；
验证完毕即可重新New reository，用户名一定要用：你的注册用户名.github.io，其他无需修改，然后点击Create repository即可;
下面自动进入一个快速设置页面，告诉我们如何在仓库内添加东西，这就需要在Windows本地设置了。

1.3 Windows本地配置Git

本文开篇就说了Windows下的Git程序，但是没有做配置，还是不能用的，这里解说下基本的配置：

首先打开Git Bash做些全局设置：

git config --global user.name "你的注册用户名"
git config --global user.email "你的邮箱"
git config --global color.ui auto

设置SSH Key：
```
ssh-keygen -t rsa -C "你的邮箱"
```
然后会要求输入存储id_rsa的目录，接着是输入密码，这个密码可以与github的不同，过程中确认即可，最后会出现一个随机图形，说明生成SSH密匙成功，这样我们需要到刚刚的存储目录下打开id_rsa.pub复制里面的内容，到你的github页面上->点击右上角头像旁三角->settings->SSH keys->add SSH key->黏贴刚刚复制的内容保存。

1.4 使用hugo

hugo是一个快速的静态网站引擎，使用Go语言开发，可以用Markdown格式的文章生成一个完整的静态网站，然后托管到自己的用户名.Github.io的Github仓库中，实现一个静态站点，一般用于博客或者项目主页等。那么我们先来了解下如何获取和使用：

先从官网下载相关的版本，比如我是32位windows系统的，我下载hugo_0.14_windows_386.zip；
解压缩后，将里面的exe文件重命名为hugo.exe，并放在C:\hugo\hugo.exe即可；
添加环境变量：我的电脑-属性-高级系统设置-环境变量，编辑PATH，加入;C:\hugo,用英文分号与之前的内容分割开。

这样我们可以测试下环境是否正常：使用Windows命令行（Win+R输入cmd）输入下列命令：

cd C:\hugo
hugo new site www

进入hugo目录下可以看到一个www的文件夹，就是刚刚新建的站点，目录的结构是：

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

尽管里面没有任何内容，但是恭喜你，说明程序可以正常使用了。

2.正式建立静态网站

2.1 新建文章

首先需要先命令行进入www文件夹下，然后输入以下命令，创建一个关于页面：

hugo new about.md

这样就生成楼www/content/about.md，打开该文件可以看到以下信息：

+++
date = "2015-11-15T10:42:51+08:00"
draft = true
title = "about"

+++

文件是md的，但是+++之间的内容是用TOML编写的文档信息，date代表文档创建的时间，后面的+08：00代表的时区，draft代表草稿，如果生成网站时不加入特殊说明是不生成该页的，title是这篇文章的标题，因此正文中不需要自己再写标题了。为了方便之后生成聚合页面，我们继续在www/content/post/目录生成第一篇文章：

hugo new post/first.md

打开first.md文件可以看到以下内容，跟上面的about.md差不多，我们在+++后面编辑一点内容并保存：

+++
date = "2015-11-15T10:48:56+08:00"
draft = true
title = "first"

+++
# My first blog
1. aaa
2. bbb
3. ccc

2.2 安装皮肤

hugo有很多皮肤(Github),也可以看这里(中文),可以找到喜欢的皮肤地址，然后在www文件夹下创建一个themes文件夹，在命令行中进入该文件夹后用git的方法获得皮肤(笔者这里使用hyde这个简单点的皮肤主题)：

git clone http://github.com/spf13/hyde.git

2.3 运行hugo

在站点根目录www文件夹下运行hugo调试命令：

hugo server --theme=hyde --buildDrafts --watch

theme指明使用的主题名称（themes文件夹下的主题文件夹名称），buildDrafts指出编译草稿部分（即draft=true的文件），watch参数可以在文件修改时实时自动刷新页面。生成后我们可以在按照命令行提示在浏览器中输入http://127.0.0.1:1313查看页面，正常的话显示如下：

2.4 简单配置

目前为止，已经生成一个简单的静态站点，但是还有很多地方需要修改，以适应每个人的需求，可以在www站点根目录下看到一个config.toml配置文件，该文件使用TOML语法编写，基本内容如下：

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

可以修改成类似这样的：

baseurl = "http://newoxygen.github.io/"#name of your repository
languageCode = "en-us"
title = "氧气计算"#title of your page
theme = "hyde"#default theme

[params]
    description = "CC博客，信奉望远镜与显微镜的哲学"#simple description on page
    themeColor = "theme-base-08" # for hyde theme

重新根目录运行hugo server --theme=hyde --buildDrafts --watch看看效果：

3.高级配置

由于之前已经设置默认主题，我们再来用hugo new post/sencond.md新建一篇文章看看有什么区别：

+++
Categories = ["Development", "GoLang"]
Description = ""
Tags = ["Development", "golang"]
date = "2015-11-15T11:53:15+08:00"
menu = "main"
title = "second"

+++

可以看出多了Categories、Description、Tags和menu几个格式化选项，顾名思义，我们可以为文章分类、添加简单描述、添加标签，menu = “main”代表在左侧home下面显示标题并连接，我们可以把之前创建的about.md文件里加上这句，然后在里面写一些个人简介，这样别人就可以简单点击左侧连接查看你的简介了。介绍完一些有用的配置，我们接着来学习2个高级技巧。

3.1 多说评论

hyde主题默认使用disqus插件，是国外的一种使用javascript编写的评论插件，可以用来嵌入页面中实现静态网页的评论功能，可以直接在config.toml文件中[params]下加入disqusShortname = "你的disqus用户名"，当然前提是你自己去disqus网站注册一个个人账户。国人的模仿能力是无限的，因此也有替代的国内版本多说，可以注册一个多说账号，进入后台管理，有一段需要我们嵌入页面的代码，我们需要将www/themes/hyde/layouts/partials/disqus.html文件重命名为duoshuo.html然后打开文件修改成如下形式并保存：

<!-- 多说评论框 start -->
<div class="ds-thread" data-thread-key="{{ .URL }}" data-title="{{ .Title }}" data-url="{{ .Permalink }}"></div>
<!-- 多说评论框 end -->

<!-- 多说公共JS代码 start (一个网页只需插入一次) -->
<script type="text/javascript">
    var duoshuoQuery = {short_name:"{{.Site.Params.duoshuoShortname}}"};

    (function() {
     var ds = document.createElement('script');
     ds.type = 'text/javascript';ds.async = true;
     ds.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + '//static.duoshuo.com/embed.js';
     ds.charset = 'UTF-8';
     (document.getElementsByTagName('head')[0]
      || document.getElementsByTagName('body')[0]).appendChild(ds);
     })();
    </script>
<!-- 多说公共JS代码 end -->

然后在www/themes/hyde/layouts/_default/single.html文件中替换如下代码：

{{ if and (isset .Site.Params "disqusShortname") (ne .Site.Params.disqusShortname "") }}
            <h2>评论</h2>
            {{ partial "disqus" . }}
        {{ end }}

最后在www/config.toml文件中的[params]下加入duoshuoShortname = "你的多说用户名"，这样我们再次调试站点可以看到每篇文章的下面都有一个多说评论框，其他人可以使用这个评论框评论文章。

3.2 代码高亮

官方推荐使用Pygments来进行代码高亮的支持，我使用了Tony Bai推荐的highlight.js,用起来很顺手，目前最新的版本是8.9.1,只要下载常用代码的高亮支持即可，是一个zip的压缩文件包，内容如下：

▸ styles/
  CHANGES.MD
  highlight.pack.js
  LICENSE
  README.md
  README.ru.md

我一般会把highlight.pack.js改成highlight.js方便调用，styles目录下有很多不同类型的高亮方式，都是css文件。接下来把highlight.js文件放到www/themes/hyde/static/js/目录下，没有目录自己建；把需要的哪种风格的css文件放到www/themes/hyde/static/css目录下。接着在www/themes/hyde/layouts/partials/head.html文件中插入如下内容：

<!-- Highlight.js and css -->
<script src="{{ .Site.BaseURL }}js/highlight.js"></script>
<link rel="stylesheet" href="{{ .Site.BaseURL }}css/monokai.css">
<script>hljs.initHighlightingOnLoad();</script>

因为个人比较喜欢monokai风格，所以用了monokai.css，相应的要把monokai.css复制到刚刚说的css目录下，你也可以根据自己的喜好选择其他的风格。当你再次调试站点查看时如果内容中有代码可以发现代码已经被着色，更加清楚明了。

4.将本地站点上传

之前第一节已经注册好Github并创建软件仓库，现在我们需要生成最终的页面并上传到自己的Github仓库中，完成站点的最终部署，只需要在www根目录输入：

hugo
或没有配置好config.toml文件的话用：
hugo --thmem=hyde --baseUrl="http://用户名.github.io"

这样在www目录下会生成一个public文件夹用于发布正式的站点，进行下列操作上传所有文件：

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

过程中会要求用户输入github的用户名和密码，密码是隐式的，所以别以为没输入。上传成功后，只要在浏览器中输入http://用户名.github.io即可访问你自己的站点了。

4.后记

之前想自己写博客，觉得自己搭建东西放心点，就在网上搜索了相关方法，最后锁定到hugo这个软件，花了一个晚上熟悉网上各位大神的说明文档，自己一步步搭建起来的，后面用了一个上午的时间写了这篇文章总结了自己搭建的方法和过程，如有问题还望评论提问，如有错误一并指正。