阿修的博客
文章 标签 分类
阿修的博客

目录

Hugo博客安装教程,评论系统,自定义js Css,代码高亮

 收录于 Hugo教学
   约 3542 字   预计阅读 8 分钟 
https://cdn.jsdelivr.net/gh/gohugoio/gohugoioTheme/static/images/hugo-logo-wide.svg

一、Hugo介绍、安装

盘点一下当下流行的博客框架，当极客们想生成搭建自己的网站时，有这些选择

  • WordPress，强大，不仅可以搭建博客，还能搭建商城等，后台为PHP

  • Hexo 基于node.js的静态博客框架

  • Jekyll 静态博客框架

  • Hugo 基于go语言的静态博客框架，号称是世界上最快的网页构件框架

前面两者的生态可能会更庞大丰富，但是Hugo更方便更快，越来越多的人转到Hugo，相信Hugo是未来。

GitHub搜索hexo theme和hugo theme，前者的项目和star基本上是后者的两倍，求稳的可以先观望。



1.1 hugo安装

不要看官网，直接从GitHub上下载，展开所有assets，下载windows-amd64.zip，下载后就能在当前文件夹打开cmd或powershell运行了。想要任意位置都能运行就添加到环境变量。



二、快速开始

2.1 创建网站

进入目标文件夹，运行hugo new site [项目名]

会建立一个名为[项目名]的文件夹，里面是初始化的文件，让我们来认识一下

.
├── archetypes
├── content		# 文章md文件存放目录
├── public		# 输出目录，存放渲染好后的网页文件
├── static		# 静态资源，存放要引用的图片、js等，部署后能直接从网站根目录访问这里面的资源
├── themes		# 主题
└── config.toml	# 核心配置文件

如果使用git的话，public添加到.gitignore，而主题则使用submodule



2.2 创建文章

运行`hugo new posts/[文件名].md

创建的文件在content/posts下，所有文章都放这个目录下，content目录下无需创建其它文件夹，而posts目录下也无需子文件夹，识别不到的

文件名就是后续访问的url，建议是小写英文，用 - 代替空格，当然用中文也可以。设定以后，被搜索引擎收录后，尽量不要修改文件名。

hugo new命令和直接创建md文件的区别就是，命令创建的有模板内容

我们发现新的文章中有这种内容

---
title: ""
date: 2022-10-12T16:33:35+08:00
draft: true
---

文章头部的这些信息在渲染网站时需要用到，具体含义以后再说。



2.3 下载主题

没有主题那么构建出来public文件中只有xml文件，没有网站html文件

选择主题，可以谷歌，而博主直接在GitHub中搜索，选一个star多，心仪的，下载

git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt

配置主题，打开config.toml，确保theme = 'LoveIt'，配置文件我们后面详说



2.4 构建网站

将渲染后的网站文件输出public，运行

hugo --buildFuture --buildDrafts

使用的环境变量是production，这样就能拿public目录中的文件去服务器上部署了

而博主推荐调试时，直接在本地生成web服务，浏览器可访问

hugo server --buildFuture --buildDrafts

使用的环境变量是development，运行后结结果中有http://localhost:xxx的链接，浏览器打开即可。程序运行在后台会监控文件的变化，自动更新网站页面

如果本地调试时，有的参数和生产时不一样，可以在config/development/config.toml文件中单独设置这个变量，会优先使用这个，比如

[params]
  [params.page]
    [params.page.library]
      [params.page.library.js]
        zCustomJS = "http://localhost:1313/js/custom.js"

两个参数分别是渲染date在未来的文章、渲染draft: true的草稿文章。否则新建的文章默认是草稿，那就不会渲染，出现找不到文章的尴尬情况



三、Hugo配置

官方文档

hugo支持多种格式的配置文件，toml、yaml、json

最好的是yaml，可以在配置中使用变量，无需输入重复的字符串

但是还是推荐toml，因为主题用的toml多，以及在网上找到的配置也是toml居多，可以直接复制粘贴

主题中也有一份配置文件，我们在根目录编辑会覆盖主题中的相同参数。一些主题独有的配置我们可以在根目录配置，不用去更改主题目录内的文件



3.1 config.toml配置

# 网站语言, 仅在这里 CN 大写 ["en", "zh-CN", "fr", "pl", ...]
languageCode = "zh-CN"
# 语言名称 ["English", "简体中文", "Français", "Polski", ...]
languageName = "简体中文"
# 是否包括中日韩文字
hasCJKLanguage = true
# 阅读全文、发布于等字体的语言
defaultContentLanguage = "zh-cn"

theme = 'LoveIt'

# 构建所有文章，包括草稿等
buildDrafts = true
buildExpired = true
buildFuture = true

enableEmoji = true

# 根据git信息自动为所有文章添加最后修改日期
enableGitInfo = true
[frontmatter]
  lastmod = [':git', 'lastmod', ':fileModTime', ':default']

# 启用文章标签和分类
[taxonomies]
  category = 'categories'
  tag = 'tags'

# 允许渲染html标签
[markup]  
  [markup.goldmark]    
    [markup.goldmark.renderer]     
      unsafe = true

# 顶部右侧显示菜单
[menu]
  [[menu.main]]
    weight = 1
    identifier = "posts"
    # 你可以在名称 (允许 HTML 格式) 之前添加其他信息, 例如图标
    pre = ""
    # 你可以在名称 (允许 HTML 格式) 之后添加其他信息, 例如图标
    post = ""
    name = "文章"
    url = "/posts/"
    # 当你将鼠标悬停在此菜单链接上时, 将显示的标题
    title = ""
  [[menu.main]]
    weight = 2
    identifier = "tags"
    pre = ""
    post = ""
    name = "标签"
    url = "/tags/"
    title = ""
  [[menu.main]]
    weight = 3
    identifier = "categories"
    pre = ""
    post = ""
    name = "分类"
    url = "/categories/"
    title = ""

其余的baseURL、title、作者信息等基本配置就不说了

修改网页的favicon图标只需文件名是favicon.ico，放到static目录下即可。使用透明的png图片，谷歌搜索png转ico，尺寸为32即可

主题支持的话，要开启rss订阅，这就是网站地图，是一个xml文件，可以提交给搜索引擎收录



3.2 评论系统

由于我们是静态页面，没有后台，想做评论系统就得借助第三方应用

国内的就不介绍了

utteranc 是基于GitHub issues的评论系统，无广告，评论起来需要先登录GitHub

disqus 是国外最大的第三方评论平台，数据应该是在他们的数据库上。有广告，使用起来需要登录，可以选择谷歌、推特、disqus等登录方式

cusdis 如果觉得GitHub issues不好管理评论，disqus加载慢且有广告，则cusdis是一个好选择，它是为了怼disqus而生的。用户无需登录即可评论，但是需要管理员同意才会展示

前两者在LoveIt主题中直接填写信息即可配置，cusdis未被支持，需要自己嵌入页面



3.3 搜索系统

同评论系统，我们只能用第三方应用来进行搜索

LoveIt支持配置第三方搜索，推荐algolia

需要先注册，创建index，接着在用户的settings - api keys，获得app id和Search-Only API Key 三个分别填入LoveIt主题配置即可

接着需要在algolia提交我们网站的内容，才能进行搜索

推荐使用hugo-algolia，在项目根目录创建config.yaml，其中的key填写Admin API Key。



3.4 代码高亮

highlightjs支持的语法更多，代码高亮更丰富

使用方法是

引入文件

<link rel="stylesheet"
      href="//unpkg.com/@highlightjs/cdn-assets@11.6.0/styles/default.min.css">
<script src="//unpkg.com/@highlightjs/cdn-assets@11.6.0/highlight.min.js"></script>

运行渲染js

<script>hljs.highlightAll();</script>



3.5 自定义css和js

很遗憾，找遍全网，没有找到Hugo哪能引用自定义的css、js文件

目前来说只能曲线引用，比如LoveIt主题支持配置第三方库文件

params.page.library可以引入网页链接或主题目录下assets目录中的文件

我们可以这样引入语法高亮的文件，css就会被放在页面head中，而js在body最后

我们还可以自己写js防止static目录下，再把本站的网页链接放入填入

第二个方法是，在填写页脚等处内容时，嵌入script标签

<script>
    var customJS = document.createElement('script')
    customJS.setAttribute('src', '/js/custom.js')
    document.body.appendChild(customJS)
</script>

所有js写/js/custom.js中即可



四、文章前置参数

文章开头的配置，可能包含LoveIt主题的特殊配置

---
title: "文章标题"
date: 创建时间，hugo new时自动生成
lastmod: 文章最后修改时间，如果配置了git lastmod，这里不用写
draft: 是否是草稿
categories: ["分类","配置了taxonomies才有效"]
tags: ["标签","同上"]
featuredImage: "文章内顶部图片的url"
featuredImagePreview: "主页显示文章时展示的图片"
summary: 文章摘要，重要！关乎ESO搜索引擎优化
---



负二、其它技巧

-2.1 cdn

我们网站的内容不必要全在自己服务器上，有些免费cdn可用

比如jQuery，可用谷歌jQuery cdn，直接引用，而不需要下载放到我们的服务器上

比如GitHub上的文件，可用查看raw格式的，然后使用https://raw.githubusercontent.com/的url

或者使用jsdelivr，所有GitHub的文件都能通过修改url变成jsdelivr的cdn来访问，jsdelivr会自动对GitHub进行加速。不过最近（2022年10月13日）国内已有部分被墙



负一、遇到的问题

一个是LoveIt主题文章页面左侧留白太多了，能展示作者信息就好了

第二个是LoveIt主题评论不支持disqus

algolia url中的空格问题



文章的最后，感谢jsdelivr、cusdis、algolia等免费的平台，正是有了开放、分享和贡献精神，互联网才会美好。而那些什么建图床，逮住往死里薅的人，是环境的破坏者，是大家的公敌。比如jsdelivr，传闻它被墙了，但是 .js .svg等文件国内仍能流程访问，就是png这种不能访问，显然是开发者禁止中国访问大文件图片了

更新于 2023-07-20
 建站
返回 | 主页