hugo的使用

本文

主要介绍了如何下载和使用hugo。

版本 说明
0.1 初版发布

背景

  • 主机: Thinkpad S2
  • 系统: Deepin GNU/Linux 15.11
  • 内核: Debian 6.3.0-18+deb9u1
  • hugo版本: hugo 0.58

参考

hugo的介绍和安装

可查看本站另一篇帖子 hugo的安装

快速使用

根据自己的摸索,保存了一个基于jane主题的基本使用框架,开箱及用,只需要在content目录下写markdown文件即可。查看我的百度网盘分享资源 链接:https://pan.baidu.com/s/1l4RU%5FJx-2XKI-pflL-a7zA 密码:pf03 。基于此框架你也可以根据个人需求,简单调整。

使用hugo生成站点

使用Hugo生成站点,比如希望生成到当前目录,文件名为my_blog。打开终端,命令如下:

1
hugo new site ./my_blog

这样就在当前目录下生成了初始站点 my_blog ,进去目录查看,其文件结构如下:

  ├─archetypes
  ├─content
  ├─data
  ├─layouts
  ├─static
  ├─themes
  └─config.toml

这里对站点的几个文件介绍一下:

  • archetypes:原型文件,里面存在一个markdown文件的模板,使用 “hugo new xx.md” 命令时会依据该模板创建markdown文件,我一般不使用 “hugo new” 命令,而是直接手动创建markdown文件,所以不关心模板
  • content:内容文件,所有的帖子都以markdown文件形式存在这里,hugo会自动索引,一般功能栏的 “关于” “友链” 等页面,我会存在content一级目录,其他帖子内容在content内另建post目录,而且根据不同分类可以在post内新建目录存储,hugo会自动层级索引,也就是只要在content内的markdown文件,hugo都能找到
  • data:这个目前还真不知道做什么的,但不影响使用,可暂不关心(如果有熟悉的可以帮忙解释一下)
  • layouts:个人理解这里存放的应该是关于网站布局以及其他关于网站页面显示的文件(html),不过我们一般都会安装主题,所以这个可以不关心
  • static:静态文件,一般js(javascript)和css文件会存放在这里,这些文件主要是与博客网页显示相关的,我没这个需求,主要是也不懂,在这里我主要存放的就是博客中用到的图片了
  • themes:主题文件,可以寻找自己喜欢的主题,存放在这里,简单配置即可使用
  • config.toml:全局配置文件,博客站点所有的配置,都在此文件完成,最比如设置使用的主题

安装主题

hugo生成站点后,还不能正常使用,需要安装自己喜欢的主题,也叫皮肤。到hugo主题列表选择一款自己喜欢的主题,下载到themes目录下,每个主题都会有一个readme文件,介绍主题的特性和指导你如何使用主题。这里以我使用的主题为例,hugo-theme-jane,此主题是由贤民大哥开发的,可以先浏览一下他的主页 贤民的比特记忆,看一下效果。

下载jane主题

  • 进入jane主题github网址,点击 [Clone or download] ,选择 [Download Zip] ,通过网页下载压缩包,解压后放到themes目录下
  • 通过git下载,打开终端,进入themes目录,输入以下命令(这个网址就是github中 [Clone or download] 栏显示的网址):
1
git clone https://github.com/xianmin/hugo-theme-jane.git

测试体验

  • 存放主题文件和更名:将下载的jane主题文件放到站点的themes目录下,并将文件名hugo-theme-jane改为jane(因为exampleSite中config.toml文件对主题的选择是jane,当然你也可以修改config.toml)
  • 复制一些示例文本:打开终端,进入站点根目录 my_blog ,输入以下命令(如果content有自己的文件,请先备份,此命令会覆盖content)
1
cp -rf themes/jane/exampleSite/content ./
  • 复制默认的站点设置:打开终端,进入站点根目录 my_blog ,输入以下命令(如果config.toml有自己的内容,请先备份,此命令会覆盖config.toml)
1
cp -rf themes/jane/exampleSite/config.toml ./
  • 启动 hugo server:打开终端,进入站点根目录 my_blog ,输入以下命令
1
hugo server
jane主题效果

配置主题

根据自己的需求,我做了如下改动:

  • 修改菜单栏为中文显示,配置文件的修改详见下文 我的配置
  • 将外链菜单,改为页面显示,需在content目录创建 links.md 文件,文件内容就是外链页面显示内容,配置文件的修改详见下文 我的配置 (添加新菜单页面都可以使用此方式)
  • 将about菜单页面添加到配置文件,统一管理,目的是将“about”改为中文“关于”,需要将原about.md文件的 “menu: “main” 删除(其实将title改为中文“关于”也可以实现),配置文件的修改详见下文 我的配置
  • 调整了菜单的顺序,更改weight值即可,配置文件的修改详见下文 我的配置
  • 删除doc菜单,个人觉得不需要此功能,删除方法是将doc菜单下的几个帖子对应的markdown文件打开,删除下面所示的代码设置(这也是一种加功能菜单的方法,需要时可以用起来)
1
2
3
4
menu:
  main:
    parent: "docs"
    weight: 3
  • 删除社交链接,本人觉得不需要,所以将所有社交链接注释掉了,但还有一个RSS订阅图标,有点强迫症,还是想把它删掉,于是进入主题jane,找到 "./layouts/partials/social_links.html” ,将RSS图标显示相关代码注释掉了,如下
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<!--
{{/* RSS icon  */}}
{{ with .Site.GetPage "home" -}}
  {{- with .OutputFormats.Get "RSS" -}}
  <a href="{{ .Permalink }}" rel="noopener {{ .Rel }}" type="{{ .MediaType.Type }}"
    class="iconfont" title="rss" target="_blank">
    {{ partial "svg/rss.svg" }}
  </a>
  {{ end -}}
{{- end -}}
-->
  • 下面展示一下 我的配置 ,基本每一处都做了注释,并标注了需要改的地方:
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
# 基础设置
#-------------------------------------------------------------------
baseURL = "https://wenhui.space"               # 博客部署网址 :部署到github时需要改
title = "Wenhui's Rotten Pen"                  # 网址名称 :改
enableRobotsTXT = true                         # 是否支持Robots协议,也就是机器人协议/爬虫协议,简单说可以通过搜索引擎搜索到你的主页(不确定)
enableEmoji = true                             # 是否支持Emoji表情符号
theme = "jane"                                 # 选用jane主题
hasCJKLanguage = true                          # 自动检测是否包含 中文\日文\韩文
paginate = 10                                  # 首页每页显示的文章数目
rssLimit = 20                                  # 限制 Rss 文章输出数量
disqusShortname = ""                           # disqus_shortname
googleAnalytics = ""                           # 配置google统计,这里设置一个 google 的统计配置id,格式为UA-XXXXXXXX-X
copyright = ""                                 # 默认为下面配置的author.name,

# 关于语言
defaultContentLanguage = "zh-cn"               # 默认博客语言环境,可选:en, zh-cn (选项由theme中i18n文件支持所决定)
[languages.zh-cn]                              # 语言支持 en/zh-cn/other... 可查看theme中i18n文件
  languageCode = "zh-cn"

# 关于语法高亮,具体使用可查看https://gohugo.io/content-management/syntax-highlighting/
PygmentsCodeFences = true                      # Enable syntax highlighting with GitHub flavoured code fences
PygmentsUseClasses = true                      # Use CSS classes to format highlighted code
PygmentsCodefencesGuessSyntax = true           #
PygmentsOptions = "linenos=table"              # 开启显示行号

[author]                                       # 作者名称 :改
  name = "文辉"
[sitemap]                                      # 暂不清楚
  changefreq = "weekly"
  priority = 0.5
  filename = "sitemap.xml"
#-------------------------------------------------------------------

#菜单设置
#-------------------------------------------------------------------
[[menu.main]]
  name = "主页"
  weight = 10
  identifier = "home"
  url = "/"
[[menu.main]]
  name = "归档"
  weight = 20
  identifier = "archives"
  url = "/post/"
[[menu.main]]
  name = "分类"
  weight = 30
  identifier = "categories"
  url = "/categories/"
[[menu.main]]
  name = "标签"
  weight = 40
  identifier = "tags"
  url = "/tags/"
[[menu.main]]
  name = "关于"
  weight = 50
  identifier = "about"
  url = "/about/"
[[menu.main]]
  name = "友链"
  weight = 60
  identifier = "links"
  url = "/links/"
[[menu.main]]
  name = "订阅"
  weight = 70
  identifier = "feed"
  url = "/index.xml"
#-------------------------------------------------------------------

#其他参数设置
#-------------------------------------------------------------------
[params]
  since = "2019"                                # 站点建立时间
  homeFullContent = false                       # 主页是否显示全部文章内容,否的话仅显示摘要,建议设为否
  rssFullContent = true                         # if false, Rss feed instead of the summary
  logoTitle = "文辉的烂笔头"                      # 博客标题,默认值是上面设置的title,也就是网址名称
  keywords = ["Hugo", "linux", "emacs", "CPU"]  # 关键字,应该是与搜索引擎搜索有关,博客内无展示
  description = ""                              # 网页描述,应该是与搜索引擎搜索有关,博客内无展示
  archive-paginate = 30                         # 归档、标签、分类每页显示的文章数目,建议修改为一个较大的值
  dateFormatToUse = "2006-01-02"                # 日期显示格式,查看可支持的格式见https://gohugo.io/functions/format/
  moreMeta = true                               # 是否显示字数统计与阅读时间
  showMenuLanguageChooser = true                # 显示语言选择开关
  showAuthorInfo = true                         # 文章末尾显示作者信息

  # 一些全局开关,这些是默认值,也可以在每一篇内容的 front matter 中对单篇内容关闭或开启某些功能,在 archetypes/default.md 查看更多信息。
  toc = true                                    # 是否开启目录
  photoswipe = true                             # 是否启用PhotoSwipe(图片可点击)
  bootcdn = true                                # 是否使用bootcdn(@Deprecated: 请使用[params.publicCDN])(好像可以加快网页访问速度)
  mathjax = false                               # 是否使用mathjax(数学公式)
  contentCopyright = '文辉原创文章,如需转载请注明出处,谢谢!!!' # 改

  customCSS = []            # if ['custom.css'], load '/static/css/custom.css' file
  customJS = []             # if ['custom.js'], load '/static/js/custom.js' file
#-------------------------------------------------------------------

# CDN设置,据说是提高访问速度的,具体也没感受到
#-------------------------------------------------------------------
  [params.publicCDN]        # load these files from public cdn,若启用公共CDN,需自行定义
    enable = true
    jquery = '<script src="https://cdn.jsdelivr.net/npm/jquery@3.2.1/dist/jquery.min.js" integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4=" crossorigin="anonymous"></script>'
    slideout = '<script src="https://cdn.jsdelivr.net/npm/slideout@1.0.1/dist/slideout.min.js" integrity="sha256-t+zJ/g8/KXIJMjSVQdnibt4dlaDxc9zXr/9oNPeWqdg=" crossorigin="anonymous"></script>'
    gitmentJS = '<script src="https://cdn.jsdelivr.net/npm/gitment@0.0.3/dist/gitment.browser.min.js" crossorigin="anonymous"></script>'
    gitmentCSS = '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitment@0.0.3/style/default.min.css" crossorigin="anonymous">'
    photoswipe = '<script src="https://cdn.jsdelivr.net/npm/photoswipe@4.1.3/dist/photoswipe.js" integrity="sha256-AC9ChpELidrhGHX23ZU53vmRdz3FhKaN9E28+BbcWBw=" crossorigin="anonymous"></script>'
    photoswipeUI = '<script src="https://cdn.jsdelivr.net/npm/photoswipe@4.1.3/dist/photoswipe-ui-default.min.js" integrity="sha256-UKkzOn/w1mBxRmLLGrSeyB4e1xbrp4xylgAWb3M42pU=" crossorigin="anonymous"></script>'
    photoswipeCSS = '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/photoswipe@4.1.3/dist/photoswipe.css" integrity="sha256-SBLU4vv6CA6lHsZ1XyTdhyjJxCjPif/TRkjnsyGAGnE=" crossorigin="anonymous">'
    photoswipeSKIN = '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/photoswipe@4.1.3/dist/default-skin/default-skin.css" integrity="sha256-c0uckgykQ9v5k+IqViZOZKc47Jn7KQil4/MP3ySA3F8=" crossorigin="anonymous">'
#-------------------------------------------------------------------

# 下面是关于评论系统,更新显示commit内容,谷歌搜索,文章打赏,访问数据统计等等,个人觉得不需要,全部false掉了
#-------------------------------------------------------------------
  [params.utteranc]         # utteranc is a comment system based on GitHub issues. see https://utteranc.es
    enable = false
    repo = "xianmin/comments-for-hugo-theme-jane"    # The repo to store comments
    issueTerm = "pathname"

  [params.gitment]          # Gitment is a comment system based on GitHub issues. see https://github.com/imsun/gitment
    owner = ""              # Your GitHub ID
    repo = ""               # The repo to store comments
    clientId = ""           # Your client ID
    clientSecret = ""       # Your client secret

  [params.livere]               #LiveRe comment. see https://www.livere.com/
    uid = ""

  [params.reward]                                         # 文章打赏
    enable = false
    wechat = "/path/to/your/wechat-qr-code.png"           # 微信二维码
    alipay = "/path/to/your/alipay-qr-code.png"           # 支付宝二维码

  [params.counter.busuanzi]  # a Chinese visitor counter  # 卜算子计数器
    enable = false

  [params.counter.leancloud]  # Chinese leancloud visitor counter  # leancloud 计数器
    enable = false
    appId = ""
    appKey = ""

  [params.commentCount.disqus] # show counts of comments for Disqus
    enable = false

  [params.search.google]    # google custom search, see https://cse.google.com
    enable = false
    id = "002186711602136249422:q1gkomof_em"
    title = "Search"

  [params.gitInfo]
    gitRepo = "https://github.com/xianmin/xianmin.org"
    showCommitMessage = false
#-------------------------------------------------------------------

#社交链接,不需要可注释掉
#-------------------------------------------------------------------
#  [params.social]
#    a-email = "mailto:your@email.com"
#    b-stack-overflow = "http://localhost:1313"
#    c-twitter = "http://localhost:1313"
#    d-facebook = "http://localhost:1313"
#    e-linkedin = "http://localhost:1313"
#    f-google = "http://localhost:1313"
#    g-github = "http://localhost:1313"
#    h-weibo = "http://localhost:1313"
#    i-zhihu = "http://localhost:1313"
#    j-douban = "http://localhost:1313"
#    k-pocket = "http://localhost:1313"
#    l-tumblr = "http://localhost:1313"
#    m-instagram = "http://localhost:1313"
#    n-gitlab = "http://localhost:1313"
#    o-goodreads = "http://localhost:1313"
#    p-coding = "http://localhost:1313"
#    q-bilibili = "http://localhost:1313"
#    r-codeforces = "http://localhost:1313"
#    s-mastodon = "http://localhost:1313"
#-------------------------------------------------------------------

到此,你可以启动 hugo server ,查看一下自己的博客了,若仍有不满意的,可以尝试继续修改。

开始写帖子

hugo是对markdown支持的,若对markdown语法不了解,可参考另一篇帖子 markdown基本语法。这里只对hugo使用的markdown文件头部进行说明(其他参数可以查看hugo官方文档):

  • date : 文件创建时间
  • draft : 是否为草稿,草稿文件不会发布到站点
  • title : 文件标题
  • tag : 标签
  • categories : 分类
  • toc : 是否开启目录
1
2
3
4
5
6
7
8
+++
date = "2015-10-25T08:36:54-07:00"
draft = true
title = "about"
tags = ["tag1", "tag2"]
categories = ["分类1"]
toc = true
+++

可以开始书写你的博客内容了,顺便说一句,markdown的编辑器可使用typora。


文章原创,可能存在部分错误,欢迎指正,联系邮箱 cao_arvin@163.com。