基于hugo的个人网站搭建

作为攻城狮一枚，必须有自己的网站以彰显技术的优势，顺便记录一下技术文档，偶尔记录一下心灵感悟。经过一番选型对比，最终决定使用hugo +markdown文档静态化的方案，直接存储在github上，大大简化了部署运维的复杂度，让我们可以随时随地的查看和记录。这里分享搭建过程，重点记录hugo的部分，其他部分从略，欢迎交流，给出建议。

搭建步骤

• VPS和nginx配置
• github仓库
• hugo
• 创作第一篇文章
• 发布网站
• 主题修改
• Tips
• 附注-选型对比
• 参考

VPS和nginx配置

VPS的优势是可以有更多自由，因此我没有选择github等免费静态空间。开通腾讯云账号，新建云服务器。考虑到流量不大，可以选择按流量计费模式，系统选择Debian（个人偏好），然后直接安装nginx：

	sudo apt-get install nginx

HTTPS已经是标配，所以开通Nginx的HTTPS端口（SSL证书可以在腾讯云申请免费版 ，修改nginx的site配置文件：

	sudo vi /etc/nginx/sites-available/default

在默认site配置文件default文件中添加以下配置：

	listen 443 ssl default_server;
	listen [::]:443 ssl default_server;

	ssl_certificate {{SSL_CERT_FILE}};
	ssl_certificate_key {{SSL_KEY_FILE}};
	ssl_session_timeout 5m;
	ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
	ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
	ssl_prefer_server_ciphers on;

然后重启Nginx：

	sudo systemctl restart nginx

打开浏览器，应该可以看到正常的Nginx欢迎网页了。

特别提醒，国内的VPS开通WWW服务一定要记得备案，腾讯云可以直接提供在线电子备案，北京局审核很快（点赞），备案后发现还要30天内公安备案，不容易啊。备案过程就不讲了，参考腾讯云的说明文档 。

github

网站数据是宝贵的，一定要及时备份，既然用了hugo，直接用git是最方便的，那就使用github吧，当然你也可以自建git server。

注册/登录github，建一个空的仓库，比如就叫www，建议选择为private，然后checkout出来，放在～/work目录下：

	cd ~/work/
	git clone git@github.com:USER/www.git

为了避免hugo生成的public文件夹被commit，建议在.gitignore文件中添加public。

然后hugo登场，正式开启建站之旅。

hugo

由于Debian内置的hugo版本过低，因此我没有用apt-get安装，直接从官网下载预编译的最新二进制包 ，解压缩后就一个清爽的hugo二进制文件，要保证hugo在$PATH可以找到的目录里。

初始化site：

	cd ~/work
	hugo new site www --force

下载themes

	cd www
	git submodule add https://github.com/razonyang/hugo-theme-bootstrap.git themes/hugo-theme-bootstrap

拷贝themes的exampleSite：

	cd ~/work/www
	cp -a themes/hugo-theme-bootstrap/exampleSite/* .
	cp themes/hugo-theme-bootstrap/archetypes/default.md archetypes/

hugo-theme-bootstrap把配置文件放在config目录里，大家可以根据需要修改，这里汇总一下我修改的一些关键配置项：

• config/_default/config.toml

	baseURL = "" # baseURL可以为空，主题会自动生成
	title = "My Site"
	copyright = "Copyright © {year} MYSITE"
	defaultContentLanguage = "zh-cn"

• config/_default/config.zh-cn.toml

	title = "My Site"

• config/_default/author.toml

	name = "MyName"
	bio = ""

• config/_default/languages.toml

  修改zh-cn的weight为1，可以在 hugo new生成新post的时候，默认放在zh-cn目录下（为此我研究了好久）。

	[en]
		weight = 2
	[zh-cn]
		weight = 1
	[zh-tw]
		weight = 3

• config/_default/params.toml

	poweredBy = false
	brand = "MySite"
	description = ""
	mainSections = ["post", "posts"] # 默认显示在主页List的文章目录

其他配置大家酌情修改，比如我修改comment = false禁用了评论。

mainSections 可以配置显示在主页List中的目录列表，一般文章放在posts目录，当然你可以建立多个目录放不同的文章。经过测试，如果一篇文章不在mainSections的所包含的目录下，首页不会显示，但在标签、分类、专栏里仍然会显示。如果文章这时没有配置任何的标签、分类和专栏，那只能通过搜索才能找到。

最后一步，清理theme包含的内置文章内容（我没有删除en下的内置帮助文章，留作参考）：

	cd ~/work/www
	rm -rf content/zh-cn/posts/shortcodes
	rm -rf content/zh-tw/posts/shortcodes

最最后一步，生成你自己的支付宝和微信打赏码：

	cp MyAlipay.webp static/images/reward/alipay.webp
	cp MyWechat.webp static/images/reward/wechat.webp

然后正式开启你的内容创作之旅吧！

创作第一篇文章

一般建议把文章放在content/zh-cn/posts下，当然你可以建立自己的目录结构：

	cd ~/work/www
	hugo new posts/myfirst.md
	vi content/zh-cn/posts/myfirst.md

打开文档使用markdown飙字吧。可以利用tags/categories修改文章的分类和标签。

Hugo 随时本地调试，修改的文档可以在浏览器实时更新和查看：

	hugo server -D

或者指定IP和端口：

	hugo server -D --bind 1.1.1.1 -p 8080

发布网站

发布网站非常简单：

	hugo -D
	sudo cp -a public/* /var/www/html

当然，重点提醒，每次写完文档，不但要执行hugo 生成文档，还要及时git commit。

主题修改

如果主题有些模版不适合，就需要修改主题来完成，稍后举例来说明调整的办法。但实际上主题一般使用hugo的partial或者shortcode来实现。根据hugo的机制，它寻找shortcode的路径顺序是：

layouts/shortcodes
themes/THEME/layouts/shortcodes

寻找layout的路径顺序是：

layouts/partials
themes/THEME/layouts/partials

所以更好的办法是在根目录下直接修改，这样就可以避免修改第三方的主题了。参考以下案例：

1. 删除文章版权

   覆盖主题partial的方式：

   cd ~/work/www
   mkdir -p layouts/partials/post/
   touch layouts/partials/post/copyright.html
   

   直接修改主题的方式：

   cd ~/work/www
   cd themes/hugo-theme-bootstrap/layouts/partials/post/
   mv copyright.html copyright.html.bak
   touch copyright.html
   

2. 不显示个人profile

   覆盖主题partial的方式：

   cd ~/work/www
   mkdir -p layouts/partials/sidebar/
   touch layouts/partials/sidebar/profile.html
   

   直接修改主题的方式：

   cd ~/work/www
   cd themes/hugo-theme-bootstrap/layouts/partials/sidebar/
   mv profile.html profile.html.bak
   touch profile.html
   

3. 添加备案号和链接

   覆盖主题partial的方式：

   cd ~/work/www
   mkdir -p layouts/partials/footer/
   vi layouts/partials/footer/copyright.html
   

   直接修改主题的方式：

   cd ~/work/www
   cd themes/hugo-theme-bootstrap/layouts/partials/footer/
   mv copyright.html copyright.html.bak
   vi copyright.html
   

   在这个文件中添加备案号和链接即可。

Tips

• mainSectors 参考hugo介绍章节

• 发布隐藏的文章，利用_build选项可以强制某篇文章或者某个section不render（不渲染成HTML）或不List（不显示在列表和搜索结果中，但生成HTML）。根据测试，使用list = "never"选项不能再配置任何的tags、categories和series，否则仍旧会被显示。 单独文件配置，在文件的Front Matter中增加：

  [_build]
    render = "always"
    list   = "never"
  

  如果要使整个目录都不List，可以在目录中创建_index.md文件，然后在文件中配置：

  +++
  title = "test"
  [_build]
      render = "always"
      list   = "never"
  [cascade._build]
      render = "always"
      list   = "never"
  +++
  

• 支持Latex公式

  hugo-theme-bootstrap通过内置Katex支持Latex公式嵌入，如果要全局支持，可以在params.toml配置文件中增加：

  math = true
  

  如果不需要开全局支持，可以在每个文件的Front Matter中加入：

  math = true
  

  该文章即可正常显示公式了。需要注意的是，如果使用typora编辑器，最好使用双$嵌入公式的方法，并需要注意Katex和MathJax的兼容性问题，这篇文章 中能看到一些兼容性差异，有些Latex语法Katex并不支持。

  当然，也可以使用页面中直接MathJax或者Katex来支持，这需要在MD文件中显式的嵌入javascript，不优雅但可以解决问题。由于hugo使用的goldmark默认会转义HTML，所以需要在config.toml中增加：

  [markup.goldmark.renderer]
    unsafe= true
  

  然后在MD文件中直接增加HTML代码即可，根据测试上表中有些语法Mathjax不支持，有些特殊字符比如\, $, 可能会引起两次处理的转义错误，会有一些奇怪的展示，需要针对个例再研究。

  <script type="text/x-mathjax-config">
    MathJax.Hub.Config({ tex2jax: { inlineMath: [['$','$'], ['$$', '$$']] } });
  </script>
  <script type="text/javascript"
    src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
  </script>
  

• 修改代码高亮的样式

  hugo使用Chroma来做代码样式生成，Chroma支持许多种语言，也多种不同的显示样式，默认样式是monokai（黑底彩色），可以在配置文件中修改：

  [markup.highlight]
    anchorLineNos = true
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineAnchors = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    style = "monokailight" # 修改这里可以调成不同的样式
    tabWidth = 2
  

  提醒一下，hugo（版本0.80.0）使用主题hugo-theme-bootstrap，config目录下的highlight.toml不生效，因此需要把上述配置放在config.toml中。

  参考：

  • hugo highlight文档
  • hugo syntax highlight
  • Chroma
  • Chroma Style Gallery

附注-选型对比

为什么要选择hugo？为什么不用wordpress？每个人爱好不同，所以选择也不同，所以不要问我为什么，没有最好的方案。我的一些考虑：

• SAAS产品：优先私有化部署到VPS，所以忽略语雀，notion，gitbook等方案。

• CMS类，比如wordpress，zblog，dede（织梦），功能强大的而复杂，大多依赖php和数据库，我不需要。

• wiki类，比如confluence，mediawiki，dokuwiki，wiki功能结构强大，和CMS类似，过于强大，往往依赖PHP或Java和数据库，放弃。

• 还有一类，gitbook类，比如gitbook，hexo，docsify，其实hugo也属于这一类。除了hugo外，其他几个都依赖node，hexo功能完整一些，docsify很简单功能也单一，gitbook已经主攻saas版本，社区版只适合写书，功能不够完善，不想依赖node环境，还是hugo一个bin走天下吧，性能还很强大！

• 当然，也可以自己开发，在流行996的当下，还是留点时间娱乐吧，拥抱开源。

参考

• hugo官网
• hugo-theme-bootstrap官网
• hugo不完美教程