Build Blog with Hugo&GitHub

· 2924字 · 6分钟

利用GitHub Pages构建Blog项目 🔗

Tags: Git GitHub hugo markdown Blog

网上相关主题帖子较多，但缺乏从git工作流角度细节。本文可以帮助读者从git项目维护角度来理解和掌握操作过程，避免小坑

目前github pages上构建个人blog主流的框架工具有jekyll, hexo, hugo. 通过比对，选择hugo来开发blog静态网站。关于三者的比较可以阅读 https://zhuanlan.zhihu.com/p/368407566

参考： 🔗

Step By Step 🔗

实现思路： 在github上构建两个repo，一个用于hugo blog内容开发（https://github.com/alexhegit/alexhegit-blog），另一个为部署的GitHub Pages repo (https://github.com/alexhegit/alexhegit.github.io)。 此外，还引用了hugo theme repo。github page repo和hugo theme repo都作为hugo blog repo的submodule, 三者的git提及相对独立。

image.png

利用github pages构建blog项目 🔗

例如我自己的项目名称为alexhegit-blog，后续讲解以此为例。 NOTE：这里创建一个空项目，不要创建README。因为，后续用hugo创建网页项目时，hugo要求项目目录为空目录。

image.png

使用hugo创建网站项目 🔗

创建一个同github blog项目同名的新目录，并用hugo初始化一个网站项目：

image.png

常用目录用处如下

子目录名称 功能
archetypes 新文章默认模板
config.toml Hugo配置文档
content 存放所有Markdown格式的文章
layouts 存放自定义的view，可为空
static 存放图像、CNAME、css、js等资源，发布后该目录下所有资源将处于网页根目录
themes 存放下载的主题

将hugo网站项目连接到github 🔗

在项目目录下，创建第一个patch引入刚刚创建的blog项目文件: 🔗

$ git init
$ git commit -a -s

image.png

将hugo blog项目提交到github: 🔗

$ git remote add origin git@github.com:alexhegit/alexhegit-blog.git
$ git branch -M main
$ git push -u origin main

NOTE：关于远程ssh提交代码，这里假设您已经设置好了ssh key以及GPG key。具体操作可参考文末“一些问题及解决方法”或者github官方文档。

在blog项目目录下，以git submodule方式安装mini主题 🔗

mini是一个简洁快速的轻量级主题

$ git submodule add https://github.com/nodejh/hugo-theme-mini.git themes/mini)
提交相关改动：
$ git commit -a -s
$ git push -u origin main

到这一步为止，githug page(blog)是空的，访问结果404.

image.png

添加首篇blog 🔗

使用并修改mini的config 🔗

参考https://github.com/nodejh/hugo-theme-mini/blob/master/README.md相关操作，如下： 在 exampleSite 目录中有一个 config.yaml 的配置文件，你可以将其复制到你的项目根目录中，将一些配置项修改为你的配置。这些配置都可以随意修改。

    > ⚠️ 你需要删除这行配置： `themesDir: ../../` 。

创建第一个Post 🔗

$hugo new posts/my-first-post.md
该命令将在content目录下创建posts/my-first-post.md。然后，您可以根据需要修改该md文件。

image.png 

每一个new post的md文件，包含了title/data等信息，可酌情修改。
且默认都标记为draft，需要以-D参数方式针对Draft提供渲染服务。正式发布前，需要将"draft true"。修改"draft false"。

image.png 

测试发布结果。-D表示draft方式运行， -t指定theme风格。
$ hugo server -D -t mini

image.png 

打开浏览器预览发布，输入http://localhost:1313 可看到结果。可反复修改，直至效果满意。

image.png

将正式发布编译成静态网页 🔗

在项目更目录下运行"hugo"命令，完成后在子目录public中生成静态网页文件。

image.png

将生成的静态网页部署到github上 🔗

创建github pages repo
以自己的github用户名创建一个github pages repo, 例如我的是alexhegit.github.io。具体步骤参考官方文档。

NOTE 需要构建一个完全空的项目，不含README及LICENSE（文件）。否则，后续git submodule add时会报错。

将生成的Blog网页托管至github pages repo 🔗

方法一：将每次Blog项目build出来的静态网站的文件从public拷贝到github pages repo。 🔗

  • 先克隆github pages repo到本地
  • 将Blog网页项目build出来的所有文件从public目录拷贝至本地的github pages repo并进行提交。

方法二：将github pages repo以submodule加入到Blog网页项目中的public目录 🔗

  • 因为之前构建Blog编译过网页，所以先要删除public目录
  • 将github pages repo以submodule加入的Blog网页项目
    $ git submodule add git@github.com:alexhegit/alexhegit.github.io.git public
    $ git commit -a -s
  • 重新build出静态网页文件 $ hugo
  • 将build出的静态网页commit到github pages repo
    $ cd public
    $ git init
    $ git commit -a -s
    $ git branch -M main
    $ git push -u origin main

提交完成后，所见即所得 Alex He’s Blog

关于后续新发布内容的操作细节 🔗

发布流程 🔗

基于上面的描述，您已经构建好了2个git repo。后续新增内容的发布流程将简化为：

  1. 在Hugo blog repo中post一个新的内容。

    • 这里建议为每一个新的内容build出一个子目录。
    例如：这里我将建立一个新的主题发布“Deploy-CodeShell-w-VSCode”
$hugo new posts/Deploy-CodeShell-w-VSCode  //创建新主题及目录,及默认主题的md文件
$mkdir posts/Deploy-CodeShell-w-VSCode/resources  //创建资源目录，在此可以放置md使用的图片

将hugo自动创建的发布md重新命名为index.md(这样才可以build出可引用图片资源内容页面)
$mv posts/Deploy-CodeShell-w-VSCode/Deploy-CodeShell-w-VSCode.md posts/Deploy-CodeShell-w-VSCode/index.md

    该发布的目录结构如下：

     $ tree content/posts/
content/posts/
├── Deploy-CodeShell-w-VSCode
│   ├── index.md
│   └── resources
│       ├── image-1.png
│       ├── image-2.png
│       ├── image-3.png
│       ├── image-4.png
│       ├── image-5.png
│       ├── image-6.png
│       └── image.png

  2. 填写内容，测试内容完成后build出页面结果

    在创建出的index.md中，编辑发布内容。测试，并在浏览器中观察结果
$hugo server -D
确认内容可发布后，将index.md中的draft字段值从"true"改为"false"

  3. 提交新内容到Hugo blog repo

    将本次新创建的post内容文件及资源文件，提交同步到githug remote repo。
$git add .
$git commit -a -s
$git push

  4. 在public子目录中，即github page repo中，commit/push新的内容

    build新发布内容
$hugo
在public子目录下将自动生成新内容相关的输出文件

    同布内容到github page repo
$cd public
$git add .
$git commit -a -s
$git push

  5. 登录github page浏览新发布

一些问题及解决方法 🔗

欢迎访问我的github blog获取更多经验分享: https://alexhegit.github.io

您也可以在 FlowUs 息流来观看该文原始版本（可视化可能更佳）

comments powered by Disqus