Deploy weblog site with hugo

使用 Hugo 构建静态博客，并快速免费部署。

几个静态网站构建工具对比

NAME STARTS FORKS FIRST RELEASED LANGUAGE
jekyll 51k 10k Nov, 2008 Ruby
Hexo 41k 5k Oct, 2012 TypeScript
Hugo 86k 8k Jul, 2013 Go
VuePress ~3k ~1k Apr, 2018 TypeScript
VitePress 17k ~3k Apr, 2020 TypeScript
MkDocs 21k ~3k Nov, 2014 Python

这几个工具个有优缺点

  • jekyll ：GitHub 最古老最多人关注，构建工具依赖 Ruby 和相关依赖包，在最新的 macOS 系统上安装麻烦，依赖包兼容性差；
  • Hexo ：中文主题多但自身官方文档不完整且混乱；
  • VuePress ：适合开源软件项目简陋官网和文档，易于通过 Vue 编写扩展，但默认缺乏最基本分类 (categories)、标签 (tags) 等静态博客功能。
  • VitePress ： 定位和功能和 VuePress 类似。基于更现代的 Vue 3 和 Vite 技术栈构建，热更新和构建速度更快。
  • MkDocs : 对旧系统和旧浏览器（如 Windows 7 和 IE 11）兼容性最好的工具，避免使用浏览器现代技术因此默认主题简陋。适合构建需支持全版本全平台技术类文档。
  • 其他
    • astro 类似整合 Vue 和 next.js 为一体的工具，强大而复杂。

核心功能对比

FEATURE Hugo MkDocs
使用常见 markdown 语法 no yes
自定义 CSS yes yes
自定义页面列表顺序 yes yes
自定义导航栏 yes yes
自定义边栏 no yes
自定义主题 yes yes
自动深色模式 no no
响应式(Responsive) yes yes
集成搜索 ? yes
支持 IE11 no yes
Windows 7 构建 yes yes

最适合现代博客

hugo + Cloudflare 的方案

在 Cloudflare 上部署 hugo 最新版本构建的静态博客。

  • 构建工具使用 hugo，安装简单只有一个二进制文件、构建速度快、文档完善；
  • 静态页面托管、域名、SSL 证书都是用 Cloudflare ，免费且稳定；

部署步骤

  • 以此文编写时刻为例，按 hugo 官方文档是用构建工具版本为 0.147.2， 生成项目后，添加 markdown 页面内容；
    • 安装构建工具参考命令 CGO_ENABLED=1 go install -v -tags extended github.com/gohugoio/hugo@v0.147.2
    • 如果是用官方文档推荐的默认 ananke 主题，需要锁定它的版本 cd themes/ananke ; git checkout v2.12.0
  • 提交内容项目到 GitHub 仓库；
  • 在 Cloudflare 上创建项目，选择 hugo 构建工具，选择 GitHub 仓库，等待构建完成；
  • 配置域名和 SSL 证书，完成。

注意：

  • Cloudflare Pages 如果不通过环境变量指定 hugo 版本，默认会使用 0.118.2 版本，导致构建失败；
  • 设置环境变量 HUGO_VERSION 和前面生成项目时指定的版本一致即可。

最终方案的效果就是当前博客的样子。

自定义 hugo CSS 样式

根据使用 theme 不一样可能要按需修改，以 themes/ananke 为例。

  • 根目录下新建 layouts/partials/head-additions.html 文件， 内容为 <link rel="stylesheet" href="{{ "css/main.css" | relURL }}">
  • 根目录下新建 static/css/main.css ，文件内容为要添加的自定义 CSS 样式

工作原理， themes/ananke 会在 baseof.html 引入 partials/head-additions.html 子模板，默认从根目录开始加载文件覆盖（如有）。

最适合全平台手册

MkDocs + Cloudflare 的方案

在 Cloudflare 上部署 MkDocs 最新版本构建的技术手册。

ref: https://developers.cloudflare.com/pages/framework-guides/deploy-an-mkdocs-site/

自定义 Python 版本

在 Environment variables 环境变量中添加 PYTHON_VERSION 指定版本即可，如 3.8.10 。

自定义 MkDocs CSS 样式

新建 custom_theme/main.html 文件修改，模板语法和内容参考 https://www.mkdocs.org/dev-guide/themes/

集成 Disqus 并禁用冗余强制广告

在 custom_theme/main.html 文件添加以下

{% include "disqus.html" %}

新建 custom_theme/disqus.html 文件，内容如下

{% block comments %}

<div id="disqus_thread"></div>
<script>
  /**
   *  RECOMMENDED CONFIGURATION VARIABLES: EDIT AND UNCOMMENT THE SECTION BELOW TO INSERT DYNAMIC VALUES FROM YOUR PLATFORM OR CMS.
   *  LEARN WHY DEFINING THESE VARIABLES IS IMPORTANT: https://disqus.com/admin/universalcode/#configuration-variables    */
  /*
  var disqus_config = function () {
  this.page.url = PAGE_URL;  // Replace PAGE_URL with your page's canonical URL variable
  this.page.identifier = PAGE_IDENTIFIER; // Replace PAGE_IDENTIFIER with your page's unique identifier variable
  };
  */
  (function () {
    // DON'T EDIT BELOW THIS LINE
    var d = document,
      s = d.createElement("script");
    s.src = "https://你的-domain-name.disqus.com/embed.js";
    s.setAttribute("data-timestamp", +new Date());
    (d.head || d.body).appendChild(s);
  })();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>

<!-- https://stackoverflow.com/a/56613937 -->

<style>
  iframe[src*="ads-iframe"] {
    display: none;
  }
</style>

{% endblock %}
comments powered by Disqus