首页 / 前端 / 文章

如何用 GitHub Pages + Hugo 搭建个人博客

前端 潘老师 来源：KrislinBlog转 9个月前 (07-26) 253 ℃ (0) 扫码查看

你想知道如何用 GitHub Pages + Hugo 搭建个人博客吗？想要拥有一个属于自己的技术博客，但有不想花钱买域名服务器，那就试试用GitHub Pages + Hugo的方式来搭建一套自己的博客网站吧！

1. 概念，搭建思路和运行环境

1.1 什么是 GitHub Pages？

Github Pages 是一个可以从你的 Github 源码仓库中直接生成个人、组织或者项目页面的静态站点托管服务。

Github Pages 只能托管静态站点，不能运行服务器端源码，比如 PHP、Java、Python 或者 Ruby。

Hugo 是用 Go 语言写的静态网站生成器（Static Site Generator）。可以把 Markdown 文件转化成 HTML 文件。

  1. 创建 2 个 GitHub 仓库
    • 博客源仓库：储存所有 Markdown 源文件（博客内容），和博客中用到的图片等。
    • GitHub Pages 仓库：储存由 Hugo 从Markdown 文件生成的 HTML 文件。
  2. 将在博客源仓库中 Hugo 生成的静态 HTML 文件部署到远端 GitHub Pages 仓库中。

2. 创建 GitHub 仓库

  1. 命名博客源仓库（whatever you want）
  2. 勾选 Pricate，设置为公开仓库。
  3. 勾选添加 README 文件。

我将博客源码分开存放到一个private repo里，也可以将源码放到github pages repo中，但这样其他人能获取文章的源文件。

2.2 创建 GitHub Page 仓库

  1. 命名 GitHub Pages 仓库，这个仓库必须使用特殊的命名格式 <username.github.io>， <username> 是自己的 GitHub 的用户名。
  2. 勾选 Public，设置为公开仓库。
  3. 勾选添加 README 文件，这会设置 main 分支为仓库的默认主分支，这在后面提交推送博客内容时很重要。

  1. 打开想要在本地储存项目的文件夹（比如我的项目的文件夹是 project ） 
    cd project
  2. 克隆博客源仓库到项目文件夹，克隆时使用的 HTTPS 仓库链接在这里查看：

git clone git@github.com:krislinzhao/BlogSource.git

4. 使用 Hugo 创建网站

  1. 进入刚刚克隆下来的博客源仓库文件夹（比如：我的博客源仓库文件夹名是 BlogSource，则cd BlogSource ），在这个文件夹里用 Hugo 创建一个网站文件夹。
  2. 用 Hugo 创建网站文件夹的命令是 hugo new site 网站名字。(比如，我的命名是 BlogSource) 
    cd BlogSource
hugo new site BlogSource

    我是直接创建在博客源码仓库中的。

  3. 用 Hugo 创建的网站共有 7 个文件夹和 1 个文件，这些文件分别代表：

  • archetypes：存放用 hugo 命令新建的 Markdown 文件应用的 front matter 模版
  • content：存放内容页面，比如「博客」、「读书笔记」等
  • layouts：存放定义网站的样式，写在layouts文件下的样式会覆盖安装的主题中的 layouts文件同名的样式
  • static：存放所有静态文件，如图片
  • data：存放创建站点时 Hugo 使用的其他数据
  • public：存放 Hugo 生成的静态网页
  • themes：存放主题文件
  • config.toml：网站配置文件

5. 安装和配置 Hugo 主题

5.1 选择 Hugo 主题

可以从 Hugo 社区提供的主题中选择一个喜欢的主题应用在自己的网站中。

5.2 安装 Hugo 主题

  1. 一般在你选择的 Hugo 主题的文档中，都会给出「如何安装这个主题」的命令，比如我选用的 BlowFish 的文档中给出：
  2. 打开刚刚用 Hugo 创建的网站文件夹（我的是 BlogSource），在终端粘贴文档中给出的安装命令。

这时可以看到在themes文件夹中，多出了刚刚安装的主题文件，代表主题安装成功。

5.3 配置 Hugo 主题

  1. 一般安装的 Hugo 主题的文件结构中都会有 exampleSite 文件夹，也是你在选择主题时参考的网站 demo。
  2. 把 exampleSite 的文件复制到站点目录，在此基础上进行基础配置。 非常推荐这么做，这样做能解决很多「为什么明明跟教程一步一步做下来，显示的结果却不一样？」的疑惑。（这主要是因为不同的主题模版配置文件不同导致的。）
  3. 在把exampleSite文件复制到站点目录时，请根据对应文件夹进行复制文件
    • 比如exampleSite下有 content ,  static  和  config.toml 3 个文件，就找到你自己的站点跟目录下这对应的三个文件。在把对应目录中的内容分别复制过去。
  4. 其中在复制config.toml的内容时要注意：
    • baseURL 
      baseURL = "https://example.com/" #把https://example.com/改成自己的域名

      如果你没有在 GitHub Pages 中设置自定义域名，这里的域名应该填 https://<username>.github.io/ （⚠️ 注意：最后的/不要忘了加）

    • themes 
      themes = "你选择的主题名字"。 #这一行命令代表启用你安装的主题

      在 config.toml 中输入这行命令才能启用安装的主题，不过一般这行命令在你复制 exampleSite 的配置文件信息时，主题作者已经写好了这行。

6. 用 Hugo 创建文章

用 Hugo 创建一篇文章的命令是:

hugo new xxx.md

用这个命令创建的 Markdown 文件会套用 archetypes 文件夹中的 front matter 模版，在空白处用 Markdown 写入内容。

其中，draft: true代表这篇文章是一个草稿，Hugo 不会显示草稿，要在主页显示添加的文章，可以设置 draft: false；或者直接删掉这行。

  1. 在发布到网站前可以在本地预览网站或内容的效果，运行命令： 
    hugo server
  2. 也可以在本地编辑 Markdown 文件时，通过 hugo server 来实时预览显示效果。
  3. hugo server  运行成功后，可以在 http://localhost:1313/ 中预览网站

使用Github Actions功能实现提交源码后自动发布。

8.1 生成Actions secrets

  1. 生成Personal access tokens 首先点击github头像在下拉栏里进入Setting->Developer Settings->Personal access tokens -> tokens (classic)选择Generate new token
  2. 点击Generate token生成token，并先复制保存该token。(这个token只有显示一次，所以一定要复制保存)
  3. 生成Actions secrets 接下来在源码repo中添加上面的personal access token：
  4. 进入repo的Settings->Secrets and variable一栏，选择New repository secret
  5. 名称自取，Secret复制上面生成的Personal access tokens

    8.2 配置actions文件

    在repo根目录新建嵌套的两个文件夹.github/workflows

    在workflows里新建一个后缀为.yml的配置文件，名字自取。

    写进去以下配置（从hugo官方文档修改而来）：

name: github pages # 名字自取

on:
  push:
    branches:
      - main  # 这里的意思是当 main分支发生push的时候，运行下面的jobs，这里先改为github-actions

jobs:
  deploy: # 任务名自取
    runs-on: ubuntu-latest    # 在什么环境运行任务
    steps:
      - uses: actions/checkout@v2    # 引用actions/checkout这个action，与所在的github仓库同名
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive) 获取submodule主题
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo    # 步骤名自取
        uses: peaceiris/actions-hugo@v2    # hugo官方提供的action，用于在任务环境中获取hugo
        with:
          hugo-version: 'latest'    # 获取最新版本的hugo
          # extended: true

      - name: Build
        run: hugo --minify    # 使用hugo构建静态网页

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3    # 一个自动发布github pages的action
        with:
          # github_token: ${{ secrets.GITHUB_TOKEN }} 该项适用于发布到源码相同repo的情况，不能用于发布到其他repo
          external_repository: krislinzhao/krislinzhao.github.io    # 发布到哪个repo
          personal_token: ${{ secrets.ACTION_ACCESS_TOKEN }}    # 发布到其他repo需要提供上面生成的personal access token
          publish_dir: ./public    # 注意这里指的是要发布哪个文件夹的内容，而不是指发布到目的仓库的什么位置，因为hugo默认生成静态网页到public文件夹，所以这里发布public文件夹里的内容
          publish_branch: main    # 发布到哪个branch

yml文件中只需要改external_repository为自己的github page仓库，personal_token: ${{ secrets.XXX }} XXX改成上面生成Actions secrets步骤中取得名称。

  1. 将BlogSource文件夹初始化为 Git 仓库，并设置默认主分支名为 main。这么做的原因是：GitHub 创建仓库时生成的默认主分支名是 main 用 git init 初始化 Git 仓库时创建的默认主分支名是 master 将 git init 创建的 master 修改成 main ，再推送给远端仓库，这样才不会报错。 
    git init -b main
  2. 将 public 文件夹关联远程 GitHub Pages 仓库，使用 GitHub Pages 仓库的 SSH 链接。 
    git remote add origin ggit@github.com:krislinzhao/BlogSource.git
  3. 推送本地文件到远程仓库 
     git pull --rebase origin main
 git add .
 git commit -m "...(修改的信息)"
 git push origin main

推送完成之后到github仓库中的Actions中就可以看到runs运行成功，你的github pages仓库就会有hugo生成的html文件了，然后你就可以通过 https://krislinzhao.github.io 访问你的博客了。

以上就是如何用 GitHub Pages + Hugo 搭建个人博客的全部内容了，你学会了吗？学会了赶紧去试试吧！

版权声明：本站文章，如无说明，均为本站原创，转载请注明文章来源。如有侵权，请联系博主删除。
本文链接：https://www.panziye.com/front/13129.html
喜欢 (1)赏
【请潘老师喝杯Coffee吧！】
分享 (0)

相关文章

用户头像
发表我的评论
取消评论
表情 贴图 签到 代码

Hi，您需要填写昵称和邮箱！

  • 昵称【必填】
  • 邮箱【必填】
  • 网址【可选】