Featured image of post 360°无死角记录HuGo博客搭建（方式一）
#技术#HuGo

360°无死角记录HuGo博客搭建（方式一）

使用GitHub Pages方式

Windows 环境安装

  1. 下载拓展版（Extended version）HuGo 压缩包

    NOTE: 标准版本没有 SCSS/SASS 支持

  2. 解压缩后，配置 PATH 环境变量，方便使用 hugo 命令

    例如我的 PATH 环境变量的值是：D:\Software\hugo_extended_0.128.0_windows-amd64。

  3. 验证安装。打开 CMD 窗口，执行以下命令

    1
2

    D:\Java\Code\hugo>hugo version
hugo v0.128.0-e6d2712ee062321dc2fc49e963597dd5a6157660+extended windows/amd64 BuildDate=2024-06-25T16:15:48Z VendorInfo=gohugoio

    如果您使用V的SCode 终端，配置好环境变量后，请重启VSCode

项目初始化

  1. 创建你的 HuGo 项目

    1

    hugo new site username.github.io

  2. 目录介绍

    • archetypes：存放内容类型的模板文件。当你使用 hugo new 命令创建新内容时，Hugo 会根据这里的模板文件生成相应的内容文件。你可以为不同的内容类型（如博客文章、页面等）定义不同的模板。
    • assets：这里存放用于 Hugo Pipes 的资源文件，例如 SCSS/SASS 样式表、JavaScript 文件等。Hugo Pipes 允许你对这些资源进行处理（如编译、压缩）并生成最终的静态文件。
    • content：主要存放网站的内容文件，如 Markdown 格式的博客文章、页面等。内容文件按照不同的分类和类型存放在子目录中。
    • data：存放数据文件，支持 YAML、JSON 和 TOML 格式。你可以在模板中通过 site.Data 访问这些数据文件，以便在网站生成时动态加载和使用数据。
    • i18n：国际化
    • layouts：存放定义网站的样式，写在layouts文件下的样式会覆盖安装的主题中的  layouts文件同名的样式。你可以在这里定义页面模板、部分模板（如头部、脚部）、列表模板等。模板文件使用 Go 模板语言编写。
    • public：存放  Hugo  生成的静态网页
    • static：存放静态文件（如图片、CSS、JavaScript 文件等），这些文件不会被 Hugo 处理，而是直接复制到最终生成的网站中。静态文件在网站中可以通过 /static/ 路径访问。
    • themes：存放主题文件夹。每个主题都有自己的目录，包含主题的模板、静态文件、资源文件等。你可以在 hugo.toml 或 hugo.yaml 中指定要使用的主题。
    • hugo.toml：网站配置文件。默认为toml格式，支持yaml格式

  3. 启动

    1
2

    # -D 能看草稿文章
hugo server -D

  4. 预览
    本地访问网站的默认 URL：http://localhost:1313/

撰写您的第一篇文章

文章分类 & 标签

当文章多了之后，content 目录会十分混乱，因此提前做好文章分类和标签很有必要~

一级分类 一级分类目录路径 二级分类 二级分类目录路径 二级分类描述 三级分类目录路径 三级分类描述
#技术 post\techs #HuGo hugo HuGo
#Markdown markdown Markdown使用指南
#fanpin fanpin fanpin项目文档
deployment-guides 生产服务器环境安装及部署准备
system-biz fan4cloud-system-biz项目
web vue-pure-admin项目
#文学 post\literature #中国 post\literature\china 国内文学
#法国 post\literature\franch 法国文学
#艺术 post\arts #口琴 post\arts\harmonica 口琴曲谱、吹奏经验
#体育 post\sports #网球 post\sports\tennis 网球技术归纳
#羽毛球 post\sports\badminton 羽毛球球技术归纳
分类 标签名 标签描述
开发语言 Go
Java
Python
Vue3
项目文档 FanPin
HuGo
GitHub Pages
DevOps
Linux
Ubuntu
Markdown

布局文件创建

在没有主题的情况下，需要手动创建一些基本的布局文件。步骤如下：

  • 在 layouts 目录中，创建一个名为 index.html 的文件： 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

    <!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{ .Title }}</title>
  </head>
  <body>
    <h1>{{ .Title }}</h1>
    <div>{{ .Content }}</div>
  </body>
</html>
  • 创建 layouts/_default/single.html 以渲染单个文章页面： 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

    <!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{ .Title }}</title>
  </head>
  <body>
    <h1>{{ .Title }}</h1>
    <div>{{ .Content }}</div>
  </body>
</html>

文章创建 

1

hugo new post\arts\harmonica\曲谱.md

预览文章

http://localhost:1313/post/arts/harmonica/曲谱/

更多文章撰写笔记相关文章：
1. Markdown写作指南

发布GitHub Pages·

创建两个GitHub Repository

  • 第一个：HTML 文件远程仓库，存储HuGo项目构建后生成 HTML 文件。Repository name必须是你的用户名.github.io。比如我的命名为pierai.github.io
  • 第二个：HuGo项目远程仓库

提交HuGo项目代码至HuGo项目远程仓库

  1. 在提交前先配置.gitignore文件： 
    1
2
3
4

    public
resources
assets/jsconfig.json
.hugo_build.lock
  2. 初始化远程仓库： 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

    # 进入项目根目录
d:
cd D:\Java\Code\hugo

# 初始化 Git 仓库
git init

# 初始化 Git 仓库时创建的默认主分支名是 master。将 git init 创建的 master 修改成 main
git init -b main  # 如果这一步错过了修改分支名，推送前仍可修改本地分支名：git branch -m master main

# 添加远程仓库
git remote add origin https://github.com/username/repository.git

# 提交所有文件
git add .
git commit -m "Initial commit"

# 如果你的远程仓库中已经有一些提交，而本地仓库中没有这些提交（这通常发生在远程仓库中有初始的 README.md 文件或 .gitignore 文件。），需要执行以下命令：
git pull origin main --allow-unrelated-histories # NOTE: 本地分支名要和远程分支对应

# 推送到远程仓库
git push -u origin main

构建并提交至HTML 文件远程仓库

  1. 执行hugo server -D。不需要草稿文章则去掉-D参数。

    NOTE: 草稿文章，也就是.md文件头部Frontmatter Configs中draft: false的文章。

  2. 在项目根目录运行 hugo 命令将 Markdown 文件生成 HTML 文件到public文件夹。 
    1
2
3
4

    # 进入项目根目录下的public文件夹
cd public

# 重复上面的Git操作，将public下的所有文件提交到 HTML 文件仓库

预览

浏览器访问: https://${你的GitHub用户名}.github.io/

[可选]绑定个人域名

  1. 获得GitHub域名解析出的IP

    1

    nslookup ${你的GitHub用户名}.github.io

    示例： 图片 1

  2. 打开你的域名管理控制台，新增域名解析记录，其中：

    • 一条CNAME记录
    • 第一步域名解析出几个IP就配置几条A记录
    主机记录 记录类型 记录值
    blog CNAME 你的GitHub Pages访问地址，比如我的是<pierai.github.io>.
    @ A 第一步解析出的IP 1
    @ A 第一步解析出的IP 2
    @ A 。。。
    @ A 第一步解析出的IP N

    示例： 图片2

    NOTE: 这里由于我的子域名负载均衡数量超出限制，A记录只配置了两条

  3. GitHub Settings配置

    1. 打开GitHubHTML 文件远程仓库Settings配置 图片3
    2. 配置你的域名并Save 图片4

  4. 预览
    访问： https://你的域名/
    这里我访问自己博客的域名是:https://blog.somi.love/

扩展

配置stack主题

HuGo Stack主题使用指南

Q & A

提交HTML 文件远程仓库代码冲突了？

删除public文件夹， 重新hugo、hugo server -D、提交public文件夹到仓库

更新 hugo.yaml 或 hugo.toml 文件配置后没生效？

执行以下命令

1
2

# 清除缓存
hugo --cleanDestinationDir

这个命令会执行以下操作：

  1. 删除 public 目录中的所有文件和子目录。
  2. 根据你的内容和模板生成最新的静态文件。
  3. 将生成的静态文件输出到 public 目录。

详细说明

  • 清理目标目录：在构建网站之前，Hugo 会删除目标目录中的所有内容，确保没有旧的或不需要的文件。
  • 构建网站：Hugo 会根据你的内容、模板、配置等生成最新的静态文件。
  • 输出到目标目录：生成的静态文件会输出到目标目录（默认是 public）。

适用场景

使用 --cleanDestinationDir 特别适用于以下场景：

  1. 确保目录干净：确保发布目录中的文件都是最新的，没有遗留的旧文件，避免网站出现未更新或多余的文件。
  2. 自动化部署：在自动化部署脚本中使用，确保每次部署都从一个干净的目录开始，避免潜在的问题。
  3. 调试和开发：在开发过程中，确保每次构建都是干净的，方便调试和测试。

参考资料

comments powered by Disqus
© 2020 - 2024 Example Person
使用 Hugo 构建
主题 Stack 由 Jimmy 设计