Deploy weblog site with hugo

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

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

这几个工具个有优缺点

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

核心功能对比

最适合现代博客

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 %}