Hugo是使用go(又称golang)语言编写的一个静态网站生成器,主要用于构建Blog、项目文档、静态网站等。以其极快的速度、强大的内容管理和强大模板语言而著称,不仅解决了环境依赖、性能较差的问题,还有简单、易用、高效、易扩展、快速部署等诸多优点,开发过程中使用LiveReload(即时渲染,即时预览网站效果),极大优化了文章写作体验。
“ 静态”的含义反映在网站页面的生成时间。一般web服务器(WordPress、Ghost、Drupal等)在收到页面请求时,需要调用数据库生成页面,再返回给用户请求。静态网站在建立网站前就生成所有页面(称为静态文件),访问时直接返回现成的静态页面,不需要数据库参与。
静态网站基本不需要维护,不需要考虑复杂的运行时间、依赖、数据库和安全性等问题。静态网站最大好处是访问快速。当网站有更改时,静态网站生成器需要重新生成所有与更改相关的页面。对于小型的个人网站、项目主页等,网站规模很小,重新生成整个网站也非常快。Hugo在速度方面做得非常好,官方宣传每篇页面的生成时间不到1ms。
如果说速度快是Hugo的第一大优点,那么安装简单应该就是Hugo的第二大优点。
Hexo基于node.js开发,需要依赖环境才能运行,要实现一些主题额外功能还需要下载和匹配各种依赖,甚是麻烦。Hugo基于go开发,打包成独立文件,不需要额外环境,安装并设置系统的环境变量后,就能直接运行,可以说是非常便利和快捷。
示例:Windows平台安装Hugo。
Hugo Releases下载对应平台的Hugo二进制文件
本地创建一个目录存储Hugo的可执行文件和项目文件
在本地创建一个新目录:示例为E:/Hugo。
下载的zip包解压到E:/Hugo/bin文件夹内,就完成了安装
设置环境变量,将E:/Hugo/bin添加到系统变量中的环境变量Path中
安装好后,运行hugo version
检测是否成功返回版本号
- $ hugo version
- Hugo Static Site Generator v0.61.0-9B445B9D windows/amd64 BuildDate: 2019-12-11T08:29:13Z
升级时:将新版本的zip包解压覆盖E:/Hugo/bin文件夹内的文件。
语法:
- hugo [command] [flags]
command的参数(可使用hugo --help
命令查看其详细帮助文档)有:
command | 功能 |
---|---|
config | 输出(显示)站点配置 |
convert | 转换内容(content)的格式 |
deploy | 将站点部署到云提供商 |
env | 输出(显示)Hugo版本和环境信息 |
gen | 几个有用的生成器的集合 |
help | 关于任何命令的帮助 |
import | 从其他站点导入您的站点 |
list | 列出内容的各种类型 |
mod | Hugo模块助手 |
new | 为您的站点创建新内容 |
server | 一个高性能的网络服务器(调用本地web服务器) |
version | 输出(显示)Hugo的版本号 |
在项目根目录(又称网站根目录,示例为Hugo/sites/ebook)中运行Hugo命令。
新建网站(Hugo项目)或主题
- hugo new [command]
参数:
command | 功能 | 示例 | 备注 |
---|---|---|---|
site | 新建项目 | hugo new site ebook |
项目以目录形式存在,目录名任意 |
theme | 新建主题 |
网站内新建内容(称为页面文件)
- hugo new [path] [flags]
根据提供的路径(path参数)创建一个新的内容文件,根据原型文件自动设置日期和标题等。原型文件使用“-k|–kind”参数指定或由Hugo智能猜测。
参数 | 描述 | 示例 | 备注 |
---|---|---|---|
path | 内容文件在content目录中的相对路径 | hugo new hugo/hugo.md |
文件路径:content/hugo/hugo.md |
flags | 使用“-k|–kind”指定内容文件的类型 | hugo new --kind chapter hugo/_index.md |
文件类型指定为chapter |
本地预览
编译生成缓存的静态文件(不会输出到public目录)并启动本地web服务:
- $ hugo server
- Building sites …
- …………
- Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
- Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
- Press Ctrl+C to stop
一直保持运行命令。手动结束命令后,将会清除缓存的静态文件。
生成网站文件
生成静态文件并输出到默认的public目录(不会启动本地web服务):
- $ hugo
- Building sites …
- | EN
- +------------------+-----+
- Pages | 47
- Paginator pages | 0
- Non-page files | 47
- Static files | 211
- Processed images | 0
- Aliases | 11
- Sitemaps | 1
- Cleaned | 0
-
- Total in 897 ms
CLI(命令行工具,例如cmd、PowerShell或Bash等)进入E:/Hugo/sites目录:
- E:\>cd E:\Hugo\sites
- E:\Hugo\sites>
在E:/Hugo/sites目录下新建项目(假设名称为ebook):
- $ hugo new site ebook
- Congratulations! Your new Hugo site is created in E:\Hugo\sites\ebook.
-
- Just a few more steps and you're ready to go:
-
- 1. Download a theme into the same-named folder.
- Choose a theme from https://themes.gohugo.io/ or
- create your own with the "hugo new theme <THEMENAME>" command.
- 2. Perhaps you want to add some content. You can add single files
- with "hugo new <SECTIONNAME>\<FILENAME>.<FORMAT>".
- 3. Start the built-in live server via "hugo server".
-
- Visit https://gohugo.io/ for quickstart guide and full documentation.
hugo server
命令项目目录的树结构为:
- . # Hugo项目根目录(示例为E:\Hugo\sites\ebook)
- ├─archetypes # markdown文件的模板,通常用来自定义设置扉页等
- | └─default.md # 缺省,Hugo预设的一个模板
- ├─content # 内容目录,存放网站内所有内容文件的源代码
- | ├─_index.md # 网站的主页(网站的简介)
- | ├─章节文件夹 # 章节目录,内容文件分类存放
- | | ├─_index.md # 章节的主页(章节的简介)
- | | ├─内容文件夹 # 章节内的子页面目录(根据需要设置)
- | | ├─xxx.md # 子页面内容,通常是markdown文件
- | | └─本地图片 # markdown文件引用的图片
- ├─data # 网站的自定义配置文件,文件类型可以是yaml|toml|json等格式
- ├─layouts # 布局目录,存放渲染content目录的模版文件,模版的文件类型是html格式
- ├─resource # 主题产生的目录,未明用途
- ├─static # 静态资源目录,存放静态资源文件,例如:图片、css、js等
- ├─themes # 主题目录,存放Hugo主题
- | └─XXX主题 # 安装后的主题名称
- | | └─layouts # 某个主题下的网站模板文件
- ├─public # 编译后生成的网站文件
- └─config.toml # 网站的配置文件(支持格式有:toml、yaml、json)
theme = "xxx"
设置默认主题(xxx是theme目录内的主题名), 或运行hugo|hugo server --theme=xxx
命令时设置临时渲染主题虽然只是一些小问题,但每次重复发生,也是一个麻烦。
Hugo的Date属性带有时区
Hugo日期格式:date: 2019-12-11T23:19:14+08:00;Hexo日期格式:date: 2019-11-25 18:49:20。在迁移时注意此问题并进行格式转换。
Hugo的网址链接
若直接输入网址(示例:https://gohugo.io/),Hugo不能识别为网址;
若粗体显示网址(示例:https://gohugo.io/),Hugo能识别为网址。
Hugo默认使用“Pretty URLs”(漂亮URL),Hexo使用“Ugly URLs”(丑陋URL)
- ├─content # 网站源代码目录
- | ├─_index.md # URL转换为:https://example.com/
- | ├─posts # 一个名为posts的章节文件夹
- | | ├─_index.md # URL转换为:https://example.com/posts/
- | | ├─first.md # URL转换为:https://example.com/posts/first/
- | | └─topic # 章节内的子页面内容目录(包含md文件和图片)
- | | | ├─second.md # URL转换为:https://example.com/posts/topic/second/
- | | | └─123.jpg # second.md文件引用的本地图片
“_index.md”和”index.md”文件在Hugo中具有特殊含义(用于组织页面)。在“Pretty URLs”渲染下,与实际路径一致。
若文件名不为“_index.md”或“index.md”时,“Pretty URLs”将md文件渲染为目录。导致后果:md文件引用本地图片时,渲染路径比实际路径多了一个与文件名同名的目录名,导致引用图片失败。
Hugo_v0.60的Markdown渲染引擎使用Goldmark,Typora使用GFM’s spec
代码(<code>
标签)/代码块(<pre>
标签)内包含html或js语法时
Typora
Typora内的代码块会屏蔽所有语法,只显示源代码。
Hugo(Goldmark)
config.toml中若设置了unsafe = true
,将会允许md文件使用html和js语法,执行html或js语句的优先级高于代码块,结果执行代码块内的html语句,导致格式错乱。因此,必须慎重开启unsafe。
在列表项中新建块/段落时
Typora成功(参阅严格模式,使用Enter键代替输入空格),Hugo有时失败。
原因一:Hugo的config.toml开启了unsafe = true
原因二:列表项中有代码块(<pre>
标签)
Hugo有时渲染成功,有时渲染失败,暂未明原因。
解决方法:貌似只要一次性完成列表项就能成功,即不要在现有列表项中插入新的块/段落。若需插入,应该是重写列表项内的所有内容。
原因三:列表项中的代码块的扉页语法貌似不能使用yaml语法
在md文件的扉页使用了yaml语法的前提下:
标题锚点的语法
Typora
只能实现页面内跳转(简捷语法:<a href="#标题路径">xx</a>
)、页面跳转(Markdown语法:[替换文本](文件相对路径)
)。
Hugo
Hugo生成的每一个html文件和html文件内的每一个标题在网络上都有唯一的URL,可实现页面内(简捷语法:<a href="#标题网址">xx</a>
)、页面、页面间跳转,建议统一使用Markdown语法:[替换文本](标题网址)
)。
Hugo通过主题将md文件渲染为HTML格式,主题实质是HTML/JavaScript/CSS的集合:
若想自定义(修改)主题,首先定位html文件了解主题的架构、使用浏览器的开发者工具(F12)了解标签元素和其样式,然后遵循此页面新建一个HTML/JavaScript/CSS文件(直接修改主题代码是一个坏习惯):
主题的预设部件(themes/hugo-theme-learn/layouts/partials目录):
在layouts/partials目录内自定义一个同名文件(优先级高于主题预设的部件)。
主题的预设CSS(themes/hugo-theme-learn/static/css目录):
在static/css目录内自定义一个css文件(优先级高于主题预设CSS)。
Hugo没有预设主题,可在Hugo的官方网站(或此GitHub仓库)将目标主题下载(克隆)到Hugo项目根目录内的themes目录中。
- git clone 主题的git地址 themes/新名称
进入themes目录(E:/Hugo/sites/ebook/themes)
- E:\Hugo\sites\ebook>cd themes
安装主题
推荐:learn、docDock(基于learn的移植,最大特色是幻灯片式播放md文件)。
- $ git clone https://github.com/matcornic/hugo-theme-learn.git
- Cloning into 'hugo-theme-learn'...
- remote: Enumerating objects: 2249, done.
-
- Receiving objects: 100% (2249/2249), 13.40 MiB | 11.00 KiB/s, done.
- Resolving deltas: 100% (1224/1224), done.
learn主题的官方文档: https://learn.netlify.com/ 。
learn主题结构:
网站配置文件:配置网站的基本参数
将themes/hugo-theme-learn/exampleSite/config.toml覆盖项目根目录内的config.toml后,进行自定义修改。
网站布局文件:构造网站的HTML结构
themes/hugo-theme-learn/layouts/index.html,文件内调用其它html文件、Hugo的页面变量等。
网站样式文件:渲染HTML标签元素的样式
themes/hugo-theme-learn/static/css,在html文件中引用CSS文件。使用浏览器的开发者工具查看HTML标签元素来源于哪一个CSS文件。
原型文件:内容文件的模板,主要是配置扉页等
themes/hugo-theme-learn/archetypes,learn主题预设了2个原型文件:
chapter.md:构建章节文件(type:chapter)
将其放入archetypes目录内,作为一个通用模板,方便其它主题调用。
default.md:构建文件(type:所有类型)
Hugo的网站配置文件(config.toml)配置网站的整体设置,其初始默认设置非常简单:
- baseURL = "http://example.org/" # 网站URL,运行本地web服务器时不需要此值
- languageCode = "en-us" # 网站语言
- title = "My New Hugo Site" # 网站标题
config.toml自定义修改后的结果:
- baseURL = "http://example.org/"
- DefaultContentLanguage = "zh-cn"
- title = "无边风月"
- theme = "hugo-theme-learn"
-
- [outputs]
- home = [ "HTML", "RSS", "JSON"]
-
- [[menu.shortcuts]]
- name = "<i class='fas fa-user'></i> 简介"
- url = "/about/"
- weight = 11
-
- [[menu.shortcuts]]
- name = "<i class='fas fa-align-justify'></i> 分类"
- url = "/categories/"
- weight = 12
-
- [[menu.shortcuts]]
- name = "<i class='fas fa-bookmark'></i> 标签"
- url = "/tags/"
- weight = 13
-
- [markup]
- [markup.tableOfContents]
- endLevel = 4
- startLevel = 2
- [markup.goldmark.renderer]
- unsafe = true
-
- [params]
- themeVariant = "mine"
- author = "komantao"
- ordersectionsby = "weight"
根据主题的语言包(themes/hugo-theme-learn/i18n)内的文件名称配置网站语言:
- languageCode = "en-us" →→→ DefaultContentLanguage = "zh-cn"
- [params]
- editURL = "" # 在每一个页面的右上角位置添加“Edit this page”按钮
- author = "" # 网站作者名称
- description = "" # 网站描述
- showVisitedLinks = false # 值为true时,菜单栏显示已访问的复选标记
- disableSearch = false # 值为true时,禁用搜索功能,将隐藏搜索栏
- disableAssetsBusting = false # 值为false时,生成新网站后自动清除Javascript and CSS的缓存
- disableInlineCopyToClipBoard = false # 值为false时,允许内联代码的“复制到剪贴板”按钮
- disableShortcutsTitle = false # 值为false时,菜单中快捷键的标题默认设置(等于文章标题)
- disableLanguageSwitchingButton = false # 值为true时,使用多语言网站时,禁用切换语言按钮
- disableBreadcrumb = true # 值为true时,隐藏面包屑导航(指页面顶栏的导航),只显示当前页标题
- disableNextPrev = true # 隐藏“下一页”和“上一页”按钮
- ordersectionsby = "weight" # 在菜单中按“weight”或“title”排序。默认为“weight”
- themeVariant = "" # 配色方案。可以是“red”、“blue”、“green”或自定义
Hugo v_0.60的Markdown渲染库改用Goldmark(放弃了Blackfriday)。
默认情况下,Goldmark禁止原始HTML和潜在危险的链接。若Markdown文件内有内联HTML或JavaScript,则需要在config.toml内开启unsafe:
- [markup]
- [markup.goldmark.renderer]
- unsafe = false # 缺省值为false,值为true时,md文件可使用html和js语法
慎重开启unsafe选项!!!
因为Hugo会执行代码块内的HTML源代码,造成版面格式错乱或其它莫名其妙的问题。
配置TOC目录的层级:
- [markup]
- [markup.tableOfContents]
- endLevel = 4
- startLevel = 1
配置语法高亮(highlight):
- [markup]
- [markup.highlight]
- codeFences = true
- hl_Lines = ""
- lineNoStart = 1
- lineNos = false
- lineNumbersInTable = true
- noClasses = true
- style = "monokai"
- tabWidth = 4
由于learn主题在header.html和footer.html文件中自定义了语法高亮(本地引用highlight.js)插件,覆盖了Hugo的语法高亮。
- [outputs]
- home = [ "HTML", "RSS", "JSON"]
learn主题将使用hugo 20+版本中的最新改进来生成json索引文件,以供lunr.js javascript搜索引擎使用。
Hugo在public文件夹的根目录下生成lunrjs index.json,构建网站(hugo|hugo server
)时,在内部生成它(不会显示在文件系统中)。
在菜单(menu)中定义其他菜单条目(menu.main)或快捷方式(menu.shortcuts)。
在网站配置文件config.toml中添加快捷方式:
- [[menu.shortcuts]]
- name = "<i class='fab fa-github'></i> Github repo"
- identifier = "ds"
- url = "https://github.com/matcornic/hugo-theme-learn" # 使用远程仓库地址
- weight = 10
- [[menu.shortcuts]]
- name = "<i class='fas fa-tags'></i> 标签"
- url = "/tags" # 使用本地地址:tags属性
- weight = 11
- [[menu.shortcuts]]
- name = "<i class='fas fa-camera'></i> 关于"
- url = "/about.html" # 使用本地地址:自定义属性
- weight = 11
url参数值的来源:
使用远程仓库网址
使用扉页中的属性值,例如:tags属性、categories属性
在Markdown文件的扉页中设置tag属性,标签按其插入顺序显示在页面的顶部
- +++
- date = 2018-11-29T08:41:44+01:00
- title = Theme tutorial
- weight = 15
- tags = ["tutorial", "theme"]
- +++
在menu中显示标签
- [[menu.shortcuts]]
- name = "<i class='fas fa-tags'></i> Tags"
- url = "/tags"
- weight = 30
自定义本地内容文件(示例:关于about)
在content根目录内新建一个about.md文件(不需要创建子目录)
在config.toml文件中添加快捷方式,自定义name和url
可以通过更改本地的i18n目录内的语言包配置文件来覆盖(翻译)标题(name)。
示例:在i18n/en.toml文件,添加以下内容
- [Shortcuts-Title]
- other = "<Your value>"
若设置了disableShortcutsTitle=true
,则此标题(name)被禁用。
url参数值的写法由uglyurls参数决定:
uglyurls = true
:丑陋URLs,url应该写为url = "/about.html"
uglyurls = false
:漂亮URLs,url应该写为url = "/about"
learn主题预设的html文件存放路径:themes/hugo-theme-learn/layouts。
内容页面的header标签(包含导航),不会被覆盖。
themes/hugo-theme-learn/layouts/partials/header.html文件:
在内容文件中添加以下信息:
懒得新建html文件,直接添加:
在<head>
标签内添加busuanzi的js插件
- <head>
- <script async src="https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"> </script>
在<div id="body-inner">
标签内添加一个<p>
标签:
- <div id="body-inner">
- {{if and (not .IsHome) (not .Params.chapter)}}
- <br>
- <h1>{{.Title}}</h1>
- {{ if not .Data.Terms }}
- <p class="authorline">
- {{with .Params.author}}
- <i class='fa fa-user'></i> <a href="https://github.com/username/username.github.io">{{ . }}</a>
- {{end}}
- <span> <i class='fa fa-calendar'></i> {{.Date.Format "2006-01-02"}}</span>
- <span> <i class="fa fa-wrench" aria-hidden="true"></i> {{.Lastmod.Format "2006-01-02"}}</span>
- <span> 字数 {{.WordCount}}</span>
- <span id="busuanzi_container_page_pv"> 阅读量 <span id="busuanzi_value_page_pv"></span>次</span>
- </p>
- <br>
- {{end}}
- {{end}}
自定义语法高亮
通过CDN(BootCDN或staticfile.org)在线引用Highlight.js插件。
备注:若Highlight.js插件无法识别编程语言,将无法着色。此时,应该不选择语言或选择近似语言。
在<head>
标签内添加:
- <link href="https://cdn.bootcss.com/highlight.js/9.15.10/styles/zenburn.min.css" rel="stylesheet">
- <script src="https://cdn.bootcss.com/highlight.js/9.15.10/highlight.min.js"></script>
- <script>hljs.initHighlightingOnLoad();</script>
第一行:在线引用配色方案monokai.min.css,learn主题本地使用(themes/hugo-theme-learn/static/css/atom-one-dark-reasonable.css),调用文件themes/hugo-theme-learn/layouts/partials/header.html
第二行:在线引用highlight.js压缩版,learn主题本地使用(themes/hugo-theme-learn/static/js/highlight.pack.js),调用文件themes/hugo-theme-learn/layouts/partials/footer.html
第三行:调用highlight.js进行着色(语法高亮)
因此,若想更改learn主题的语法高亮,只需要修改第一行,即将
- <link href="{{"css/atom-one-dark-reasonable.css" | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet">
修改为:
- <link href="https://cdn.bootcss.com/highlight.js/9.15.10/styles/zenburn.min.css" rel="stylesheet">
代码块添加行号
highlight.js插件本身没有显示行号的功能,百度搜索教程自行添加行号:
themes/hugo-theme-learn/layouts/partials/footer.html的body标签内的末尾位置添加:
- <script type="text/javascript">
- var e = document.querySelectorAll("pre code");
- var i;
- for (i = 0; i < e.length; i++) {
- e[i].innerHTML = "<ul><li>" + e[i].innerHTML.replace(/\n/g, "\n</li><li>") + "\n</li></ul>";
- $("code ul li").last().remove();
- }
- </script>
\n
替换为标签<ul>
和<li>
$("code ul li").last().remove();
删除多增加的一行空行在CSS文件(static/scc/theme-mine.css)内添加:
- /* highlight.js插件的语法高亮 */
- .hljs ul {
- list-style: decimal;
- margin: 0 0 0 40px!important;
- padding: 0
- }
- .hljs li {
- list-style: decimal-leading-zero;
- border-left: 1px solid #111!important;
- padding: 2px 5px!important;
- margin: 0!important;
- line-height: 14px;
- width: 100%;
- box-sizing: border-box
- }
- .hljs li:nth-of-type(even) {
- background-color: rgba(255,255,255,.015);
- color: inherit
- }
list-style: decimal;
是根据<li>
标签自动编号增加“back to top”按钮
在<div id="body-inner">
标签内添加一个<p>
标签和js代码:
- <p id="back-to-top"><i class="fa fa-space-shuttle fa-2x fa-rotate-270" aria-hidden="true"></i></p>
- <script>
- var backButton=$('#back-to-top');
- backButton.hide(); /*首先将#back-to-top隐藏*/
- function backToTop() {
- $('html,body').animate({scrollTop: 0}, 800);
- return false;
- }
- backButton.on('click', backToTop);
- $(window).on('scroll', function () {/*当滚动条的垂直位置大于浏览器所能看到的页面的那部分的高度时,回到顶部按钮就显示 */
- if ($(window).scrollTop() > $(window).height())
- backButton.fadeIn();
- else
- backButton.fadeOut();
- });
- $(window).trigger('scroll');/*触发滚动事件,避免刷新的时候显示回到顶部按钮*/
- </script>
然后在CSS文件中设置样式:
- /* 回到顶部按钮 */
- p#back-to-top{
- position:fixed;
- bottom:6%;
- right:3%;
- }
- p#back-to-top i{
- color:blue;
- display:block;
- z-index: -100;
- }
- p#back-to-top i:hover{
- color:red;
- }
网站图标(在浏览器的标题内显示)。
在layouts/partials目录内新建一个文件,命名favicon.html。然后编写HTML。使用<link>
标签并引用在static文件夹内的图像(假设在static/images目录内)。
- <link rel="shortcut icon" href="/images/favicon.png" type="image/x-icon" />
网站徽标(在页面左上角显示)。
在layouts/partials目录内新建一个文件,命名logo.html。然后编写想要的任何HTML。使用img标签并引用在static文件夹内的图像(假设在static目录内)。
- <a id="logo" href="{{ .Site.BaseURL }}">
- <img class="custom-logo" src="夜空.jpg">
- </a>
左侧菜单的页脚。
- <p>Theme:<a href="https://getgrav.org">Grav</a> and <a href="https://gohugo.io/">Hugo</a></p>
learn主题预设的CSS文件存放路径:themes/hugo-theme-learn/static/css。
预设了3种CSS配色方案(red、blue、green),直接在config.toml修改参数即可使用:
- [params]
- themeVariant = "green"
自定义CSS配色方案:在static/css目录内新建一个CSS文件(文件名使用theme前缀,例如theme-mine.css)。
- :root{
- /* body标签:文章正文 */
- --MAIN-TEXT-color:#323232; /* 缺省颜色 */
- --MAIN-TITLES-TEXT-color: #5e5e5e; /* h2-h3-h4-h5标题的颜色 */
- --MAIN-LINK-color:#1C90F3; /* a标签:链接(links)的颜色 */
- --MAIN-LINK-HOVER-color:#DC143C; /* 悬停在链接时的颜色 */
- --MAIN-ANCHOR-color: #1C90F3; /* color of anchors on titles */
-
- /* nav标签:导航栏(或称侧边栏、菜单栏) */
- /* #sidebar #header-wrapper:导航栏内的header,包括网站图标和搜索栏 */
- --MENU-HEADER-BG-color:#FFFFF0; /* 导航栏内的header的背景颜色 */
- --MENU-HEADER-BORDER-color:#33a1ff; /* 导航栏内的header的边框颜色 */
- --MENU-WIDTH:15em; /* 导航栏相对宽度 */
-
- /* #sidebar .searchbox:导航栏内的搜索栏 */
- --MENU-SEARCH-BG-color:#D3D3D3; /* 搜索栏的背景颜色 */
- --MENU-SEARCH-BOX-color: #33a1ff; /* 搜索栏的边框颜色 */
- --MENU-SEARCH-BOX-ICONS-color: #000000; /* 搜索栏中的图标的颜色 */
-
- /* #sidebar ul.topics > li.parent, #sidebar ul.topics > li.active:活动组件,指被选中的章节或其内容 */
- --MENU-SECTIONS-BG-color:#E0FFFF; /* 导航栏的缺省颜色 */
- --MENU-SECTIONS-LINK-color: #000000; /* 导航栏内链接的颜色 */
- --MENU-SECTIONS-LINK-HOVER-color: #FF0000; /* 导航栏内链接悬停时的颜色 */
- --MENU-SECTIONS-ACTIVE-BG-color:#D3D3D3; /* 活动组件(active section,被选中时)的背景颜色,包含子组件 */
- --MENU-SECTION-ACTIVE-CATEGORY-color: #777; /* 活动组件的颜色 */
- --MENU-SECTION-ACTIVE-CATEGORY-BG-color: #FDF5E6; /* 活动组件的背景颜色 */
-
- --MENU-VISITED-color: #33a1ff; /* Color of 'page visited' icons in menu */
- --MENU-SECTION-HR-color: #20272b; /* Color of <hr> separator in menu */
-
- }
-
- body {
- color: var(--MAIN-TEXT-color) !important;
- }
-
- #body .padding {
- padding: 15px 1rem;
- }
-
- #sidebar {
- width: var(--MENU-WIDTH) !important;
- }
- #body {
- margin-left: var(--MENU-WIDTH) !important;
- }
-
- textarea:focus, input[type="email"]:focus, input[type="number"]:focus, input[type="password"]:focus, input[type="search"]:focus, input[type="tel"]:focus, input[type="text"]:focus, input[type="url"]:focus, input[type="color"]:focus, input[type="date"]:focus, input[type="datetime"]:focus, input[type="datetime-local"]:focus, input[type="month"]:focus, input[type="time"]:focus, input[type="week"]:focus, select[multiple=multiple]:focus {
- border-color: none;
- box-shadow: none;
- }
-
- h1 {
- background: var(--MENU-SECTIONS-BG-color);
- font-weight: 700;
- }
-
- #chapter h1 {
- border-bottom: none;
- }
-
- #chapter p {
- text-align: left;
- }
- h2, h3, h4, h5 {
- color: var(--MAIN-TITLES-TEXT-color) !important;
- }
-
- h2 {
- font-size: 1.8em;
- margin: 20px 0;
- padding-left: 0px;
- font-weight: 700;
- line-height: 1.4;
- background: var(--MENU-HEADER-BORDER-color);
- }
- h3 {
- font-weight: 700;
- font-size: 1.2em;
- line-height: 1.4;
- margin: 10px 0 5px;
- padding-top: 10px;
- }
- h4 {
- font-weight: 700;
- /* text-transform: uppercase; 控制文本的大小写:uppercase 大写 */
- font-size: 1.1em;
- line-height: 1.4;
- margin: 10px 0 5px;
- padding-top: 10px
- }
- h5, h6 {
- font-size: 1em;
- }
-
- a {
- color: var(--MAIN-LINK-color);
- }
-
- .anchor {
- color: var(--MAIN-ANCHOR-color);
- }
-
- a:hover {
- color: var(--MAIN-LINK-HOVER-color);
- }
-
- #sidebar ul li.visited > a .read-icon {
- color: var(--MENU-VISITED-color);
- }
-
- #body a.highlight:after {
- display: block;
- content: "";
- height: 1px;
- width: 0%;
- -webkit-transition: width 0.5s ease;
- -moz-transition: width 0.5s ease;
- -ms-transition: width 0.5s ease;
- transition: width 0.5s ease;
- background-color: var(--MAIN-LINK-HOVER-color);
- }
- #sidebar {
- background-color: var(--MENU-SECTIONS-BG-color);
- }
- #sidebar #header-wrapper {
- background: var(--MENU-HEADER-BG-color);
- color: var(--MENU-SEARCH-BOX-color);
- border-color: var(--MENU-HEADER-BORDER-color);
- }
- #sidebar .searchbox {
- border-color: var(--MENU-SEARCH-BOX-color);
- background: var(--MENU-SEARCH-BG-color);
- }
-
- #sidebar ul.topics > li.parent, #sidebar ul.topics > li.active {
- background: var(--MENU-SECTIONS-ACTIVE-BG-color);
- }
- #sidebar .searchbox * {
- color: var(--MENU-SEARCH-BOX-ICONS-color);
- }
-
- #sidebar a {
- color: var(--MENU-SECTIONS-LINK-color);
- font-weight: 400;
- }
-
- #sidebar a:hover {
- color: var(--MENU-SECTIONS-LINK-HOVER-color) !important;
- }
-
- #sidebar ul li.active > a {
- background: var(--MENU-SECTION-ACTIVE-CATEGORY-BG-color);
- color: var(--MENU-SECTION-ACTIVE-CATEGORY-color) !important;
- }
-
- #sidebar hr {
- border-color: var(--MENU-SECTION-HR-color);
- }
-
- #sidebar ul.topics ul a {
- color: #1E90FF;
- }
-
- #sidebar section#shortcuts {
- background: #DDA0DD;
- }
-
- #body #navigation {
- display: none;
- }
-
- /* 设置TOC */
- #TableOfContents > ul > li > a {
- padding: 0;
- color: #000000;
- }
- #TableOfContents > ul > li > ul > li > a {
- padding: 0 20px;
- }
- #TableOfContents > ul > li > ul > li > ul > li > a {
- padding: 0 25px;
- }
-
- /* 设置代码块 */
- #body-inner pre {
- max-height: 300px;
- overflow: auto;
- padding: 0;
- margin: 0;
- white-space: pre;
- }
-
- #body img, #body .video-container {
- margin: 1rem auto;
- }
-
- /* 设置表格 */
- table th {
- background: #999999;
- text-align: center;
- }
- table th, table td {
- border: 1px solid #000000;
- padding: 0.2rem;
- }
- /* 设置引用 */
- blockquote {
- background: #F5F5F5;
- border-left: 4px solid #0066FF;
- }
自定义配色方案后,在config.toml中配置参数:
- [params]
- themeVariant = "mine"
Hugo-theme-learn主题已加载了Font Awesome库,可以轻松显示Font Awesome中的免费图标(icon)或徽标(logo)。
浏览旧版本的Font Awesome库(v5.12不能预览图标)选择好图标(例如heart)后,复制其HTML后粘贴到Markdown文件中:
- <i class="fas fa-heart"></i>
Hugo-theme-docDock主题教程:
Hugo-theme-docDock主题结构:
网站配置文件:配置网站的基本参数
将themes/hugo-theme-docdock/exampleSite/config.toml覆盖项目根目录内的config.toml后,进行自定义修改。
网站页面布局文件:构建页面的HTML结构
路径:themes/hugo-theme-docdock/layouts。
网站样式文件:渲染HTML标签元素的样式
路径:themes/hugo-theme-docdock/static/css。html文件引用CSS文件,使用浏览器的开发者工具可查看HTML标签元素来源于哪一个CSS文件。
原型文件:themes/hugo-theme-learn/archetypes
learn主题预设了2个原型文件(生成内容文件的模板):
docDock主题移植于learn主题,因此,可参考learn主题的配置。
参考示例自定义修改config.toml为:
- baseURL = "https://kuang.netlify.com/" # 发布网站的URL
- languageCode = "en" # 网站语言
- defaultContentLanguage = "zh-cn" # 没有语言指示符的内容将默认为这种语言
- title = "风月" # 网站名称
- theme = "hugo-theme-docdock" # 启用主题
- enableRobotsTXT = true # 生成robots.txt,告诉搜索引擎允许其抓取所有内容
- enableEmoji = true # 启用表情符号
- hasCJKLanguage = true # true时,自动检测内容中的中文/日语/韩语。这将使.Summary和.WordCount正确识别CJK语言
- enableGitInfo = true # Lastmod项使用Git的最后提交时间
- relativeURLs = true # URL相对于content目录
- canonifyURLs = true # 将相对URL转换为绝对
- paginate = 10 # 分布(pagination)中每页的默认元素数量。但分页失败,建议填写一个较大值,避免渲染失败
- PaginatePath = "page"
- buildDrafts = false # 构建(build)时,true表示包含草稿(drafts)
-
- [outputs]
- home = [ "HTML", "RSS", "JSON"]
-
- [[menu.shortcuts]]
- name = "<i class='fa fa-th'></i> 分类"
- url = "/categories"
- weight = 12
-
- [[menu.shortcuts]]
- name = "<i class='fa fa-tags'></i> 标签"
- url = "/tags"
- weight = 13
-
- [markup]
- [markup.tableOfContents]
- endLevel = 6 # TOC的标题结束层数(H6)
- startLevel = 1 # TOC的标题开始层数(H1)
- [markup.goldmark.renderer]
- unsafe = false
-
- [params]
- author = "komantao" # 作者
- authorsdescribe = "一缕风尘空蒙 一泓月色潋滟" # 作者描述
- description = "学习笔记" # 网站描述,方便SEO
- github = true # 社交链接
- editURL = "" # 顶栏显示“Edit this page”(输入content目录在源代码仓库内的URL)
- themeStyle = "original" # docDock主题预设有2种类型:"original"、"flex"(缺省值)
- themeVariant = "mine" # 主题变体(即CSS配色方案)预设值有:"green"、"gold"、"gray"、"blue"(缺省值),可自定义新的变体
- ordersectionsby = "weight" # 章节(sections)排序:weight(自定义排序权重值)、title(缺省值,按照文档的title排序)
- disableHomeIcon = false # true时,禁止显示网站主页图标;缺省值为false
- disableSearch = false # true时,禁止搜索;缺省值为false
- disableNavChevron = true # true时,隐藏上一页/下一页导航(next/prev chevron);缺省值为false
- highlightClientSide = true # true时,使用highlight.pack.js插件,从而代替hugo默认的chroma highlighter
- menushortcutsnewtab = true # true时,在新的标签页打开菜单项的链接(shortcuts links),但貌似无效;缺省值为false
- disableAssetsBusting = false
- copyrighthtml = "Copyright © 2020 komantao. All Rights Reserved." # 自定义版权信息
- enableGitalk = true
-
- [params.reward] # 设置打赏功能
- enable = true
- wechat = "/images/wechat.png" # 微信二维码
-
- [params.gitalk] # 使用Gitalk设置评论区
- clientID = "xxx" # GitHub应用程序(Gitalk)生成的client ID
- clientSecret = "xxx" # GitHub应用程序(Gitalk)生成的client secret
- repo = "discuss" # 存储评论(comments)的GitHub仓库名
- owner = "xxx" # GitHub仓库的所有者(owner)的GitHub ID
- admin= "xxx" # GitHub仓库的所有者和合作者(collaborators),指对仓库具有写访问权限的用户
- id= "location.pathname" # 页面的唯一ID
- labels= "gitalk" # Github的issue标签
- perPage= 15 # 分页大小(Pagination size),最大为100
- pagerDirection= "last" # 评论排序方向,可用值为'last'和'first'
- createIssueManually= true # false时, 在评论仓库的issue内自动显示管理员登录信息
- distractionFreeMode= false # false时,启用热键(cmd|ctrl + enter)提交评论
paginate
Hugo_v0.6自动分页失败,建议将paginate值设置为一个较大值,避免渲染失败:
ERROR 2020/02/14 11:27:41 failed to render pages: render of “taxonomyTerm” failed: “E:\Hugo\sites\book\themes\hugo-theme-docdock\layouts_default\list.html:7:42”: execute of template failed: template: _default\list.html:8:3: executing “main” at <partial “pagination.html” $paginator>: error calling partial: “E:\Hugo\sites\book\themes\hugo-theme-docdock\layouts\partials\pagination.html:7:42”: execute of template failed: template: partials/pagination.html:7:42: executing “partials/pagination.html” at <.Next.RelPermalink>: can't evaluate field RelPermalink in type *page.Pager
启用highlight.js
- [params]
- highlightClientSide = true
同时,禁用(注释或删除)pygments( 从0.30版本开始,被Chroma替代 )
- # pygmentsCodeFences = true
- # pygmentsStyle = "monokailight"
在导航栏内(<div id="header">
标签)显示网站logo。
新建一个logo.html存入layouts/partials目录
- <a id="logo" href="{{ .Site.BaseURL }}">
- <img class="custom-logo" src="/images/风车.gif"> /* 网站logo图片存放在static/images目录内 */
- </a>
调用logo.html
在themes/hugo-theme-docdock/layouts/partials/original/body-beforecontent.html文件(<div id="header">
标签)内调用logo.html:
- <div id="header">
- {{ partial "logo.html" . }}
导航栏内(<div id="header">
标签)显示作者、作者描述、网站描述和社交链接等。
config.toml中设置选项开关
- [params]
- author = "komantao" # 作者
- authorsdescribe = "一缕风尘空蒙 一泓月色潋滟" # 作者描述
- description = "学习笔记" # 网站描述,方便SEO
- github = true # 社交链接
添加HTML标签
- {{with .Site.Params.author}} /* 添加作者标签 */
- <a>{{ . }}</a>
- {{end}}
- <br/>
- {{with .Site.Params.authorsdescribe}} /* 添加作者描述标签 */
- <span style="white-space: pre;">{{ . }}</span>
- {{end}}
- <br/>
- {{with .Site.Params.github}} /* 添加社交标签 */
- <a href="https://github.com/xxx/xxx.github.io"><i class="fa fa-github" aria-hidden="true"></i></a>
- {{end}}
在导航栏的列表(<ul class="topics">
标签)内增加一个标记,显示为“目录”。
在themes/hugo-theme-docdock/layouts/partials/original/body-beforecontent.html中的<ul class="topics">
标签内新增一个标签:
- <ul class="topics">
- <a>目录:</a>
显示效果:
同理,在导航栏的<section id="shortcuts">
标签内增加一个标题,显示为“其它”并修改为:
- <section id="shortcuts">
- <a>其它:</a>
- {{- range sort . "Weight"}}
- <li class="" role="">
- {{- .Pre -}}
- <a href="{{.URL}}" target="_blank" rel="noopener">{{safeHTML .Name}}</a>
- {{- .Post -}}
- </li>
- {{- end}}
- </section>
<a>
标签内的target="_blank"
,表示新建页面打开链接。若删除,在原页面打开链接docdock主题预设了一个tags首页,点击页面内的标签(区别于点击导航栏内的tags快捷键)弹出的首页,文件路径为:themes/hugo-theme-docdock/layouts/_default/li.html。
在文章开始位置增加以下信息:
添加busuanzi的js插件
在themes/hugo-theme-docdock/layouts/partials/original/head.html文件中添加:
- <script async src="https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"> </script>
设置config.toml
- hasCJKLanguage = true # 若为true,则自动检测内容中的中文/日语/韩语。这将使.Summary和.WordCount正确识别CJK语言
添加html标签
在themes/hugo-theme-docdock/layouts/partials/original/body-beforecontent.html文件中的<div id="body-inner">
标签内添加一个<p>
标签:
- <div id="body-inner">
- {{if and (not .IsHome) (not .Params.chapter)}}
- <br>
- <br>
- <h1>{{.Title}}</h1>
- {{ if not .Data.Terms }}
- <p class="authorline">
- {{with .Params.author}}
- <i class='fa fa-user'></i> <a>{{ . }}</a>
- {{end}}
- <span> <i class='fa fa-calendar'></i> {{.Date.Format "2006-01-02"}}</span>
- <span> <i class="fa fa-wrench" aria-hidden="true"></i> {{.Lastmod.Format "2006-01-02"}}</span>
- <span> 字数 {{.WordCount}}</span>
- <span id="busuanzi_container_page_pv"> 阅读量 <span id="busuanzi_value_page_pv"></span>次</span>
- </p>
- <br>
- {{end}}
- {{end}}
开启Highlight.js
docdock主题已在本地安装了Highlight.js插件,在themes/hugo-theme-docdock/layouts/partials/original/scripts.html文件中调用themes/hugo-theme-docdock/static/js/highlight.pack.js,但只使用了缺省的配色方案。
在config.toml中开启Highlight.js:
- [params]
- highlightClientSide = true
或通过CDN(BootCDN或staticfile.org)在线引用Highlight.js插件。
在themes/hugo-theme-docdock/layouts/partials/original/head.html文件中添加:
- <link href="https://cdn.bootcss.com/highlight.js/9.15.10/styles/zenburn.min.css" rel="stylesheet">
- <script src="https://cdn.bootcss.com/highlight.js/9.15.10/highlight.min.js"></script>
- <script>hljs.initHighlightingOnLoad();</script>
第一行:在线引用zenburn.min.css配色方案
第二行:在线引用highlight.js插件
第三行:调用highlight.js进行着色(语法高亮)
着色(选择配色方案)
若选择了Highlight.js插件不能识别的语言,将会着色失败,从而导致后面的添加行号也失败。解决方法是清空"选择语言"内容,Highlight.js将使用默认着色。
若想更改配色方案,只需要修改第一行:
- <link href="https://cdn.bootcss.com/highlight.js/9.15.10/styles/zenburn.min.css" rel="stylesheet">
代码块添加行号
highlight.js插件本身不能显示行号,百度搜索教程自行添加行号。
在themes/hugo-theme-docdock/layouts/partials/original/body-aftercontent.html文件的{{ partial "custom-content-footer.html" . }}
后面添加:
- <script type="text/javascript">
- var e = document.querySelectorAll("pre code");
- var i;
- for (i = 0; i < e.length; i++) {
- e[i].innerHTML = "<ul><li>" + e[i].innerHTML.replace(/\n/g, "\n</li><li>") + "\n</li></ul>";
- $("code ul li").last().remove();
- }
- </script>
\n
替换为标签<ul>
和<li>
$("code ul li").last().remove();
删除多增加的一行空行themes/hugo-theme-docdock/static/theme-original/variant-mine.css文件内添加:
- /* highlight.js插件的语法高亮 */
- .hljs ul {
- list-style: decimal;
- margin: 0 0 0 40px !important;
- padding: 0;
- }
- .hljs li {
- list-style: decimal-leading-zero;
- border-left: 1px solid #111!important;
- padding: 2px 5px!important;
- margin: 0!important;
- line-height: 14px;
- width: 100%;
- box-sizing: border-box;
- }
- .hljs li:nth-of-type(even) {
- background-color: rgba(255,255,255,.015);
- color: inherit;
- }
- .copy-to-clipboard {
- display: none;
- }
- pre .copy-to-clipboard {
- display: inline-block!important;
- top: 0;
- right: 0;
- }
list-style: decimal;
是根据<li>
标签自动编号复制按钮
docDock主题的代码块已设计了复制按钮(Copy to clipboard)。代码块(<pre code>
标签)设置最大高度(添加滑条)和将复制按钮固定在<pre>
标签内、<code>
标签外(复制按钮不承滑条而滚动):
- /* 设置代码块 */
- #body-inner pre {
- background: black;
- padding: 1.5rem 0 0 0!important; /* 增加顶部边距,为复制按钮预留空间 */
- margin: 0;
- white-space: pre;
- }
- #body-inner pre code {
- max-height: 300px; /* 设置最大高度 */
- overflow: auto; /* 自动滚动 */
- }
- pre .copy-to-clipboard {
- display: inline-block!important;
- top: 0; /* 复制按钮位置 */
- right: 0; /* 复制按钮位置 */
- }
在页面增加“back to top”按钮。
在themes/hugo-theme-docdock/layouts/partials/original/body-aftercontent.html文件的{{ partial "custom-content-footer.html" . }}
后面添加一个<p>
标签和js代码:
- <p id="back-to-top"><i class="fa fa-space-shuttle fa-2x fa-rotate-270" aria-hidden="true"></i></p>
- <script>
- var backButton=$('#back-to-top');
- backButton.hide(); /*首先将#back-to-top隐藏*/
- function backToTop() {
- $('html,body').animate({scrollTop: 0}, 800);
- return false;
- }
- backButton.on('click', backToTop);
- $(window).on('scroll', function () { /*当滚动条的垂直位置大于浏览器所能看到的页面的那部分的高度时,回到顶部按钮就显示 */
- if ($(window).scrollTop() > $(window).height())
- backButton.fadeIn();
- else
- backButton.fadeOut();
- });
- $(window).trigger('scroll'); /*触发滚动事件,避免刷新的时候显示回到顶部按钮*/
- </script>
在themes/hugo-theme-docdock/static/theme-original/variant-mine.css文件内添加:
- /* 回到顶部按钮 */
- p#back-to-top{
- position: fixed;
- bottom: 22%;
- right: 1%;
- }
- p#back-to-top i{
- color: #1E90FF;
- display: block;
- z-index: -100;
- }
- p#back-to-top i:hover{
- color: red;
- }
docdock主题页脚(footer):themes/hugo-theme-docdock/layouts/partials/custom-content-footer.html。
- <footer class=" footline" >
- {{with .Params.LastModifierDisplayName}}
- <i class='fa fa-user'></i> <a href="mailto:{{ $.Params.LastModifierEmail }}">{{ . }}</a> {{with $.Date}} <i class='fa fa-calendar'></i> {{ .Format "2006/01/02" }}{{end}}
- </div>
- {{end}}
在页脚(footer)中增加打赏和版权信息。
config.toml文件增加:
- [params]
- copyrighthtml = "Copyright © 2020 Komantao. All Rights Reserved."
- [params.reward] # 打赏
- enable = true
- wechat = "/images/wechat.png" # 微信收款二维码
在页脚文件末尾添加:
- {{if and (not .IsHome) (not .Params.chapter) (not .Data.Terms)}}
- {{if .Site.Params.reward.enable}}
- <p style="text-align: center">感谢您的赞赏支持:</p>
- <img class="wechat" src="/images/wechat.png" style="max-width:30%">
- {{end}}
- {{ if .Site.Params.copyrighthtml }}
- <div class="text-center" style="text-align: center">{{.Site.Params.CopyrightHTML | safeHTML}}</div>
- {{ end }}
- {{ end }}
在新标签页打开图片。
在themes/hugo-theme-docdock/layouts/partials/original/body-aftercontent.html的<div id="body-inner">
标签末尾位置添加:
- <script type="text/JavaScript" language="javascript">
- <!--给页面中所有img对象添加onclick事件 -->
- function AddImgClickEvent(){
- var objs = document.getElementsByTagName("img");
- for(var i=0;i<objs.length;i++){
- objs[i].onclick=function(){
- window.open(this.src);
- }
- objs[i].style.cursor = "pointer";
- }
- }
- AddImgClickEvent();
- </script>
mine.css命名为variant-mine.css,存放在themes/hugo-theme-docdock/static/theme-original目录内:
- :root{
- /* body标签:文章正文 */
- --MAIN-TEXT-color:#323232; /* 缺省颜色 */
- --MAIN-TITLES-TEXT-color: #5e5e5e; /* h2-h3-h4-h5标题的颜色 */
- --MAIN-LINK-color:#1C90F3; /* a标签:链接(links)的颜色 */
- --MAIN-LINK-HOVER-color:#DC143C; /* 悬停在链接时的颜色 */
- --MAIN-ANCHOR-color: #1C90F3; /* color of anchors on titles */
-
- /* nav标签:导航栏(或称侧边栏、菜单栏) */
- /* #sidebar #header-wrapper:导航栏内的header,包括网站图标和搜索栏 */
- --MENU-HEADER-BG-color:#E0FFFF; /* 导航栏内的header的背景颜色 */
- --MENU-HEADER-BORDER-color:#33a1ff; /* 导航栏内的header的边框颜色 */
- --MENU-WIDTH:16em; /* 导航栏相对宽度 */
-
- /* #sidebar .searchbox:导航栏内的搜索栏 */
- --MENU-SEARCH-BG-color:#D3D3D3; /* 搜索栏的背景颜色 */
- --MENU-SEARCH-BOX-color: #33a1ff; /* 搜索栏的边框颜色 */
- --MENU-SEARCH-BOX-ICONS-color: #000000; /* 搜索栏中的图标的颜色 */
-
- /* #sidebar ul.topics > li.parent, #sidebar ul.topics > li.active:活动组件,指被选中的章节或其内容 */
- --MENU-SECTIONS-BG-color:#E0FFFF; /* 导航栏的缺省颜色 */
- --MENU-SECTIONS-LINK-color: #000000; /* 导航栏内链接的颜色 */
- --MENU-SECTIONS-LINK-HOVER-color: #FF0000; /* 导航栏内链接悬停时的颜色 */
- --MENU-SECTIONS-ACTIVE-BG-color: #87CEFA; /* 活动组件(active section,被选中时)的背景颜色,包含子组件 */
- --MENU-SECTION-ACTIVE-CATEGORY-color: #000000; /* 活动组件的颜色 */
- --MENU-SECTION-ACTIVE-CATEGORY-BG-color: #FDF5E6; /* 活动组件的背景颜色 */
- --MENU-SECTION-HR-color: #20272b; /* 导航栏<hr>分隔符的颜色 */
- }
-
-
- /* body标签 */
- body {
- color: var(--MAIN-TEXT-color) !important;
- font-family: -apple-system,BlinkMacSystemFont,Helvetica Neue,Microsoft YaHei,Source Han Sans CN,Source Han Sans SC,Noto Sans CJK SC,WenQuanYi Micro Hei,sans-serif;
- font-weight: 200;
- font-size: 16px !important;
- }
-
-
- /* 导航栏(侧边栏):nav#sidebar */
- #sidebar {
- max-width: var(--MENU-WIDTH) !important;
- background-color: var(--MENU-SECTIONS-BG-color);
- }
- #sidebar #header-wrapper {
- background: var(--MENU-HEADER-BG-color);
- border-bottom: 3px solid var(--MENU-HEADER-BORDER-color);
- }
- #sidebar #header-wrapper #header a.baselink {
- font-weight: 800;
- font-size: 28px !important;
- }
- #sidebar #header-wrapper #header span {
- color: #b22222;
- }
- #sidebar .searchbox {
- border-color: var(--MENU-SEARCH-BOX-color);
- background: var(--MENU-SEARCH-BG-color);
- }
- #sidebar .searchbox * {
- color: var(--MENU-SEARCH-BOX-ICONS-color);
- }
- #sidebar ul.topics > a, #sidebar ul.topics section#shortcuts > a {
- font-weight: 800;
- font-size: 20px !important;
- }
- #sidebar ul.topics > li.parent, #sidebar ul.topics > li.active {
- background: var(--MENU-SECTIONS-ACTIVE-BG-color);
- }
- #sidebar ul.topics li.active > div > a {
- background: var(--MENU-SECTION-ACTIVE-CATEGORY-BG-color);
- color: var(--MENU-SECTION-ACTIVE-CATEGORY-color) !important;
- font-weight: 800 !important;
- }
- #sidebar a {
- color: var(--MENU-SECTIONS-LINK-color);
- font-weight: 400;
- padding: 0 !important;
- width: calc(100%) !important;
- }
-
- #sidebar a:hover {
- color: var(--MENU-SECTIONS-LINK-HOVER-color) !important;
- }
- #sidebar hr {
- border-color: var(--MENU-SECTION-HR-color);
- }
- #sidebar section#shortcuts {
- border-top: 3px solid var(--MENU-HEADER-BORDER-color);
- }
-
- #sidebar .parent li, #sidebar .active li{
- border-left:1px solid red;
- }
-
- #body .nav{
- width:1.2rem;
- }
-
-
- /* 文章正文:section#sidebar */
- @media only screen and (min-width: 780px) { /* 媒体判断:判断PC浏览器和手机屏幕像素自动调用不同CSS的代码 */
- #body {
- margin-left: 15em!important;
- }
- #body .padding {
- padding: 0.5rem 2rem 0.5rem 2rem;
- }
- #top-github-link {
- position: fixed;
- }
- }
-
- #body a.highlight:after {
- display: block;
- content: "";
- height: 1px;
- width: 0%;
- -webkit-transition: width 0.5s ease;
- -moz-transition: width 0.5s ease;
- -ms-transition: width 0.5s ease;
- transition: width 0.5s ease;
- background-color: var(--MAIN-LINK-HOVER-color);
- }
-
- /* 固定文章顶栏:#top-bar */
- #top-bar {
- width: 100%;
- position: fixed; top: 0;
- z-index: 99;
- background: #FFEBCD;
- margin: 0rem -1rem 1rem;
- }
- #breadcrumbs {
- display: inline-block;
- }
- #top-github-link {
- top: 1.6rem;right: 3rem;
- z-index: 199;
- display: inline-block;
- }
- /* 文章标签:#tags */
- #tags {
- margin-top: 1.8rem;
- }
- #tags a.label {
- background-color: #EE82EE;
- }
- /* 文章顶栏中的TOC:#body div#top-bar div.progress nav#TableOfContents */
- #TableOfContents {
- padding: 2px !important;
- }
- /* 第二层 */
- #TableOfContents > ul > li > ul > li > a {
- padding: 0;
- color: #000000;
- }
- /* 第三层 */
- #TableOfContents > ul > li > ul > li > ul > li > a {
- padding: 0 20px;
- }
- /* 第四层 */
- #TableOfContents > ul > li > ul > li > ul > li > ul > li > a {
- padding: 0 30px;
- color: #FFA500;
- }
- textarea:focus, input[type="email"]:focus, input[type="number"]:focus, input[type="password"]:focus, input[type="search"]:focus, input[type="tel"]:focus, input[type="text"]:focus, input[type="url"]:focus, input[type="color"]:focus, input[type="date"]:focus, input[type="datetime"]:focus, input[type="datetime-local"]:focus, input[type="month"]:focus, input[type="time"]:focus, input[type="week"]:focus, select[multiple=multiple]:focus {
- border-color: none;
- box-shadow: none;
- }
- div#body-inner > p.authorline {
- text-align: center;
- background-color: #E0FFFF;
- border-bottom: 1px dashed #183f81!important;
- }
- h1, h2, h3, h4, h5, h6 {
- color: var(--MAIN-TITLES-TEXT-color) !important;
- font-weight: 700 !important;
- }
- h1 {
- color: red!important;
- }
- h2 {
- font-size: 1.8em;
- margin: 20px 0;
- padding-left: 0px;
- line-height: 1.4;
- }
- h3 {
- font-size: 1.2em;
- line-height: 1.4;
- margin: 10px 0 5px;
- padding-top: 10px;
- }
- h4 {
- /* text-transform: uppercase; 控制文本的大小写:uppercase 大写 */
- font-size: 1.1em;
- line-height: 1.4;
- margin: 10px 0 5px;
- padding-top: 10px
- }
- h5, h6 {
- font-size: 1.2em;
- }
- a {
- color: var(--MAIN-LINK-color);
- }
- .anchor {
- color: var(--MAIN-ANCHOR-color);
- }
- a:hover {
- color: var(--MAIN-LINK-HOVER-color) !important;
- }
-
- /* 设置表格 */
- table th {
- background: #999999;
- text-align: center;
- }
- table th, table td {
- border: 1px solid #000000;
- padding: 0.2rem;
- }
- /* 设置引用 */
- blockquote {
- background: #E0FFFF;
- border-left: 4px solid #0066FF;
- }
- blockquote p,blockquote ul {
- margin: 0.5rem !important;
- }
- /* 设置代码块 */
- #body-inner pre {
- background: black;
- padding: 1.5rem 0 0 0!important;
- margin: 0;
- white-space: pre;
- }
- code {
- white-space:pre-wrap;
- }
- #body-inner pre code {
- max-height: 300px;
- overflow: auto;
- }
- #body img, #body .video-container {
- margin: 1rem auto;
- }
- /* highlight.js插件的语法高亮 */
- .hljs ul {
- list-style: decimal;
- margin: 0 0 0 40px !important;
- padding: 0;
- }
- .hljs li {
- list-style: decimal-leading-zero;
- border-left: 1px solid #111!important;
- padding: 2px 5px!important;
- margin: 0!important;
- line-height: 14px;
- width: 100%;
- box-sizing: border-box;
- }
- .hljs li:nth-of-type(even) {
- background-color: rgba(255,255,255,.015);
- color: inherit;
- }
- .copy-to-clipboard {
- display: none;
- }
- pre .copy-to-clipboard {
- display: inline-block!important;
- top: 0;
- right: 0;
- }
- /* 回到顶部按钮 */
- p#back-to-top{
- position: fixed;
- bottom: 22%;
- right: 1%;
- }
- p#back-to-top i{
- color: #1E90FF;
- display: block;
- z-index: -100;
- }
- p#back-to-top i:hover{
- color: red;
- }
Top Bar,文章页面顶部的导航栏,包含4部分:
页面滚动时固定顶栏:
- /* 固定文章顶栏:#top-bar */
- #top-bar {
- width: 100%;
- position: fixed; top: 0;
- z-index: 99;
- background: #FFEBCD;
- margin: 0rem -1rem 1rem;
- }
- #breadcrumbs {
- display: inline-block;
- }
- #top-github-link {
- top: 1.6rem;right: 3rem;
- z-index: 199;
- display: inline-block;
- }
复制learn主题中的简体中文语言包zh-cn.toml(或新建)到docDock主题的i18n目录内:
- [Search-placeholder]
- other = "搜索..."
- [Clear-History]
- other = "清理历史记录"
- [Attachments-label]
- other = "附件"
- [title-404]
- other = "错误"
- [message-404]
- other = "哎哟。 看起来这个页面不存在 ¯\\_(ツ)_/¯。"
- [Go-to-homepage]
- other = "转到主页"
- [Edit-this-page]
- other = "编辑当前页"
- [Shortcuts-Title]
- other = "更多"
- [Expand-title]
- other = "展开"
原型是创建新页面内容(运行hugo new
命令)时使用的模板,预先配置格式:例如md文件的扉页( front matter)、其它格式等。原型文件应该存放在archetypes目录内。
原型(archetypes/default.md)内的扉页貌似不能进行日期格式转换:
date: {{ .Date }}
,因为之后的日期格式转换基于此date属性。若date: {{.Date.Format "2006-01-02"}}
,将会触发错误:Error: Failed to process archetype file “default.md”:: template: default:3:19: executing “default” at <.Date.format>: can't evaluate field format in type stringdefault.md:将md文件构建为HTML的页面文件(type:缺省)。
- ---
- title: "{{ replace .Name "-" " " | title }}"
- date: {{ .Date }}
- author: "komantao"
- LastModifierDisplayName: "komantao"
- LastModifierEmail: komantao@hotmail.com
- weight: 20
- url: {{ replace .Dir "\\" "/" }}{{ replace .Name "-" " " | title }}.html
- draft: false
- description: "文章描述"
- keywords: [keyword1, keyword2, keyword3]
- tags: [标签1, 标签2]
- categories: [分类1, 分类2]
- ---
- 首页描述。
-
- <!--more-->
- ## 一、概述
-
-
- ## 参考资料
-
- > - []()
- > - []()
- > - []()
-
- ## 操作环境
-
- > - 操作系统:Win 10
- > -
chapter.md:将md文件构建为HTML的章节文件(type:chapter)。
- +++
- title = "{{ replace .Name "-" " " | title }}"
- date = {{ .Date }}
- weight = 5
- chapter = true
- +++
-
- ### 自定义章节序号
-
- # 自定义标题
-
- 章节介绍。
一定要设置chapter = true
或type="chapter"
才能生成章节文件。
slide.md:将md文件构建为HTML的幻灯片文件(type:slide)。
- +++
- title = "Slide title"
- type="slide"
-
- theme = "league"
- [revealOptions]
- transition= 'concave'
- controls= true
- progress= true
- history= true
- center= true
- +++
-
- # Slide 1
-
- ___
-
- ## Slide 1.1
-
- - Turn off alarm
- - Get out of bed
-
- ___
-
- ## Slide 1.2
-
- - Eat eggs
- - Drink coffee
-
- ---
-
- # Slide 2
-
- ___
-
- ## Slide 2.1
-
- - Eat spaghetti
- - Drink wine
-
- ___
-
- ## Slide 2.2
-
- - Get in bed
- -
docDock主题提供了slide插件,必须配合插件才能生成HTML的幻灯片。
内容组织(Content Organization)指存放在content目录内的页面(pages),结构假设为:
- ├─content # 网站源代码目录
- | ├─_index.md # 网站主页(整个网站的简介)
- | ├─posts # 一个名为posts的章节文件夹
- | | ├─_index.md # 章节主页(整个章节的简介)
- | | └─topic # 章节内的子页面内容目录(包含md文件和图片)
- | | | ├─topic.md # 章节内的子页面内容(markdown文件)
- | | | └─123.jpg # topic.md文件引用的本地图片
备注:内容文件若引用图片,Hugo建议将其与内容文件放在同一个目录内。
Hugo中的内容组织的管理依赖于Page Bundles(页面绑定)。Page Bundles包括:
Leaf Bundle(没有子节点)
Branch Bundle(home page、section、taxonomy terms、taxonomy list)
home page:网站主页
section:章节,在content目录内定义的子目录(多个子页面的集合)
content目录下的第一级子目录都是一个section。如果想让任意一个子目录成为section,需要在目录下面定义_index.md文件。 所有的section构成一个section tree。
- content
- └── blog <-- Section, 因为是content的第一级子目录
- ├── funny-cats
- │ ├── mypost.md
- │ └── kittens <-- Section, 因为包含_index.md
- │ └── _index.md
- └── tech <-- Section, 因为包含 _index.md
- └── _index.md
如果section tree 需要可导航,至少最底层的部分需要定义一个_index.md文件。
扉页( front matter)用来配置文章的标题、时间、链接、分类等元信息,提供给模板调用。可使用的格式有:yaml格式(默认格式,使用3个减号-)、toml格式(使用3个加号+)、json格式(使用大括号{})。除了网站主页外,其它内容文件都需要扉页来识别文件类型和编译文件。
- ---
- title: "xxx" # 文章标题
- menuTitle: "xxx" # 文章标题在菜单栏中显示的名称
- description: "xxx" # 文章描述
- keywords: ["Hugo","keyword"] # 关键字描述
- date: "2018-08-20" # 文章创建日期
- tags: [ "tag1", "tag2"] # 自定义标签
- categories: ["cat1","cat2"] # 自定义分类
- weight: 20 # 自定义此页面在章节中的排序优先级(按照数字的正序排序)
- disableToc: "false" # 若值为false(缺省值)时,此页面启用TOC
- pre: "" # 自定义menu标题的前缀
- post: "" # 自定义menu标题的后缀
- chapter: false # 若值为true(缺省值)时,将此页面设置为章节(chapter)
- hidden: false # 若值为true(缺省值)时,此页面在menu中隐藏
- LastModifierDisplayName: "" # 自定义修改者的名称,显示在页脚中
- LastModifierEmail: "" # 自定义修改者的Email,显示在页脚中
- draft: false # true,表示草稿,Hugo将不渲染草稿
- url: # 重置permalink,默认使用文件名
- type: # type与layout参数将改变Hugo寻找该文章模板的顺序
- layout:
- ---
weight属性
pre属性
在菜单栏中的标题前添加前缀:可为数字、文字、图标(Font Awesome库)等。
- +++
- title = "Github repo"
- pre = "<i class='fab fa-github'></i> "
- +++
menuTitle属性
新建网站主页文件
若未创建网站主页,运行hugo server
时会提示创建一个网站主页:
- Customize your own home page
- The site is working. Don't forget to customize this homepage with your own. You typically have 3 choices :
- 1. Create an _index.md document in content folder and fill it with Markdown content
- 2. Create an index.html file in the static folder and fill the file with HTML content
- 3. Configure your server to automatically redirect home page to one your documentation page
使用hugo new XX.md
命令在content目录内新建一个_index.md文件作为网站主页:
- $ hugo new _index.md
- E:\Hugo\sites\ebook\content\_index.md created
编写网站主页文件
章节是包含其他子页面的页面,具有特殊的布局样式:通常仅包含章节序号、章节名称和本章节的简短摘要。
Hugo-theme-learn主题调用chapter.md原型文件来构建章节文件的扉页:
新建章节页面文件(同时新建了章节目录)
- $ hugo new --kind chapter 个人网站/_index.md
- E:\Hugo\sites\ebook\content\个人网站\_index.md created
编写章节主页文件
打开章节主页文件(_index.md),编写内容(关键是设置chapter属性值为true):
- +++
- title = "blog" # 修改标题
- date = 2019-11-28T13:48:56+08:00 # 修改日期
- weight = 5 # 修改排序优先级别
- chapter = true # true,表示此页面是章节页面
- pre = "<b>X. </b>" # 修改在侧边栏显示的前缀
- +++
-
- ### 第二章 # 修改在章节页面显示的章节序号
- # 个人网站 # 修改在章节页面显示的标题
- 介绍制作个人静态网站的各种工具。 # 修改在章节页面显示的简短摘要
网页的效果示例:
docDock主题没有提供chapter.md,但可直接使用learn主题的chapter.md。
在项目根目录中执行hugo new XX.md
命令,会在content目录中自动创建XX.md文件:
- $ hugo new 个人网站/hugo/"hugo.md"
- E:\Hugo\sites\ebook\content\个人网站\hugo\hugo.md created
文件名若有空格,则必需使用双引号括起;否则,可省略双引号
不建议文件名含有空格!!!因为Hugo编译时,会将URL中文件的空格解析为-
,从而导致本地图片链接解析失败。
创建内容文件时应该使用子目录来实现文档分类
若不指定--kind type
,Hugo默认调用archetypes/default.md原型文件来构建内容页面文件的扉页
假设content目录的结构为:
- ├─content # 网站源代码目录
- | ├─_index.md # 网站主页(整个网站的简介)
- | ├─posts # 一个名为posts的章节文件夹
- | | ├─_index.md # 章节主页(整个章节的简介)
- | | └─topic # 章节内的子页面内容目录(包含md文件和图片)
- | | | ├─topic.md # 章节内的子页面内容(markdown文件)
- | | | └─123.jpg # topic.md文件引用的本地图片
假设在md文件引用图片时使用Markdown语法为:
- 
Hugo渲染时默认使用“Pretty URLs”,将md文件渲染为目录,在浏览器的地址栏中显示渲染后的路径(baseURL = “http://example.com/",渲染为本地web服务器http://localhost:1313/)。
开发者工具查看本地图片的渲染地址:
- <a href="http://localhost:1313/posts/topic/topic/123.jpg" data-featherlight="image"><img src="topic/123.jpg" alt="123"></a>
发现图片的渲染路径比实际多了一个与文件名同名的目录。所以,本地图片渲染失败。
解决方法:基本思路是将“Pretty URLs”转换为“Ugly URLs”。
使用“Pretty URLs”时
方法1:使用“Pretty URLs”的文件命名方法
md文件分目录存放,文件名统一命名为index.md或_index.md。
- ├─content # 网站源代码目录
- | ├─_index.md # 网站主页(整个网站的简介)
- | ├─posts # 一个名为posts的章节文件夹
- | | ├─_index.md # 章节主页(整个章节的简介)
- | | └─topic # 章节内的子页面内容目录(包含md文件和图片)
- | | | ├─_index.md # 章节内的子页面内容(markdown文件)
- | | | └─123.jpg # 子页面引用的本地图片
不使用“Pretty URLs”的文件命名方法(md文件名使用个性化命名)时
- ├─content # 网站源代码目录
- | ├─_index.md # 网站主页(整个网站的简介)
- | ├─posts # 一个名为posts的章节文件夹
- | | ├─_index.md # 章节主页(整个章节的简介)
- | | └─topic # 章节内的子页面内容目录(包含md文件和图片)
- | | | ├─topic.md # 章节内的子页面内容(markdown文件)
- | | | └─123.jpg # topic.md文件引用的本地图片
方法2:在md文件的扉页内手动设置url参数
在md文件的扉页中手动设置url为实际路径或“Ugly URLs”
- url: posts/topic # 手动输入md文件的相对路径
- url: posts/topic.html # 手动输入md文件的“Ugly URLs”
缺点:每一个有图片的md文件都需要手动设置url参数。
方法3:在原型文件(archetypes/default.md)设置变量自动获取url参数
自动获取url的实际路径:
- url: {{ .Dir }} # 自动提取md文件的相对路径
在Windows平台下,路径的显示格式为:blog\。本地预览时没问题,发布到网站时,此格式就造成URL乱码(blog%5Chugo.html),导致读取图片失败。
解决方法:
手动改变格式为:blog/
使用replace替换函数:
- url: {{ replace .Dir "\\" "/" }}
\
是一个转义符,因此使用\\
将其转义为普通字符。转义后,将blog\
替换为blog/
缺点:一个目录内只能有一个md文件(否则,多个md文件将会渲染为同一个目录,Hugo只能选择一个)
自动获取“Ugly URLs”:
- url: {{ replace .Dir "\\" "/" }}{{ replace .Name "-" " " | title }}.html
方法4:在网站配置文件config.toml中设置
- [permalinks]
- blog = "/:sections/:slug/" # blog是某个指定的目录名
方法5:愚蠢的方法,图片复制为2份,分别为Markdown语法和Hugo渲染所用
若不设置relativeURLs(默认),静态资源的路径相对于static目录
md文件和本地图片在同一级目录内,目的是将路径简单化
md文件中引用图片时使用Markdown语法
- 
将本地图片复制一份到static目录,按照“Pretty URLs”格式构建路径
例如md文件在content目录的路径为content/posts/topic.md,则其引用图片在static目录的路径为static/posts/topic/123.jpg。
若设置relativeURLs,静态资源的路径相对于content目录
md文件和本地图片在同一级目录内,目的是将路径简单化
md文件中引用图片时使用Markdown语法
- 
将本地图片复制一份到content目录,按照“Pretty URLs”格式构建路径
例如md文件在content目录的路径为content/posts/topic.md,则其引用图片在content目录的路径为content/posts/topic/123.jpg。
在网站配置文件config.toml中设置
- relativeURLs = false => relativeURLs = true
使用“Ugly URLs”时
静态资源的路径相对于content目录,且与Markdown语法使用的路径完全一致。
md文件和本地图片在同一级目录内,目的是将路径简单化
md文件中引用图片时使用Markdown语法
- 
在网站配置文件config.toml中设置
- uglyurls = true
使用“Ugly URLs”渲染content目录后,将md文件渲染为html文件:
- content/posts/_index.md => example.com/posts/index.html
- content/posts/topic/topic.md => example.com/posts/topic/topic.html
此方法破坏了url默认设置(“Pretty URLs”),因此需要修改url渲染失败的功能
搜索config.toml
- [[menu.shortcuts]]
- name = "<i class='fas fa-align-justify'></i> 分类"
- url = "/categories.html" # “Pretty URLs”时,url = "/categories"
- weight = 12
-
- [[menu.shortcuts]]
- name = "<i class='fas fa-bookmark'></i> 标签"
- url = "/tags.html" # “Pretty URLs”时,url = "/tags"
- weight = 13
搜索partials
hugo-theme-learn主题在页面上显示的标签导航使用“Pretty URLs”:
在themes/hugo-theme-learn/layouts/partials/header.html文件中禁用此功能:
- <!-- # 新增,将其转换为注释
- <div id="head-tags">
- {{ partial "tags.html" . }}
- </div>
- --> # 新增
或将其转换为.html(“Ugly URLs”)。(不懂修改模板)
调整图片大小
添加图像的HTTP参数((width、height),值为CSS值(默认为auto):
- 
调整图片显示效果
添加一个CSS类(classes),值为shadow、border等:
- 
Hugo以go语言的html/template库作为模版引擎,将内容通过template渲染成html,模版作为内容和显示视图之间的桥梁。
Hugo有一套模版查找机制,如果找不到与内容完全匹配的模板,它将搜索上一级。直到找到匹配的模板。如果找不到模板,将使用默认模板。
hugo有三种类型的模版:
Single Template:用于渲染页面内容
List Template:用于渲染一组相关内容
一个站点下所有内容或一个目录下的内容(section listings、home page、taxonomy lists、taxonomy terms)。homepage(_index.md),是一个特殊类型的list template,homepage是一个站点所有内容的入口。
partial Template:可理解为模版级别的组件,可以被其他模版引用
通常存放在项目根目录(或主题目录)内的layouts/partial目录。
页面模版查询规则:判断页面是single page还是list page:
Output Format:
Language:
Layout:
可以在页面头部设置front matter:layout,设置页面用指定的模版进行渲染,例如,页面在目录posts(默认section)下面,layout=custom,查找规则如下:
- layouts/posts/custom.html
- layouts/posts/single.html
- layouts/_default/custom.html
- layouts/_default/single.html
type:
如果在页面的头部设置了属性type属性,例如type=event,查找规则如下:
- layouts/event/custom.html
- layouts/event/single.html
- layouts/events/single.html
- layouts/_default/single.html
block:
在父模板中通过{{block “xxx”}}
定义一个块
在子模块中通过{{define “xxx”}}
定义的内容进行替换
模板引用:
方法一:partial(推荐使用)
引入定义的局部模板(位置在themes/layouts/partials或layouts/partials目录内):
- {{ partial "chrome/header.html" . }}
方法二:template
在一些比较老的版本中用于引入定义的局部模版,现在在内部模版中仍然使用。
- {{- xxx -}}
-
用于去除空格
{{- xxx}用于去除{{- 前边的空格、{{ xxx -}用于去除-}}后边的空格、{{- xxx -}}用于去除两边的空格。
Paginator:
.Paginator主要用来构建菜单,只能在homePage、listPage中使用
- {{ range .Paginator.Pages }}
- {{ .Title }}
- {{ end }}
简码:
简码(shortcodes)相当于一些自定义模版,通过在md文档中引用,生成代码片段,类似于一些js框架中的组件
简码必须在themes/layouts/partials或者layouts/partials目录内定义
简码在模版文件中引用是无效的,只能在content目录下的md文件中引用
引用方式
- {{% msshortcodes params1="xxx" %}}**this** is a text{{% /msshortcodes %}}
- {{< msshortcodes params1="xxx" >}} **Yeahhh !** is a text {{< /msshortcodes >}}
taxonomy:
Hugo中通过taxonomy来实现对内容的分组。taxonomy需要在站点配置文件中定义:
- [taxonomies]
- category = "categories"
- tag = "tags"
- series = "series"
变量:
Site:
大部分站点变量定义在站点配置文件中(config.[yaml|toml|json] )
- .Site.Menus:站点下的所有菜单
- .Site.Pages:站点下的所有页面
- .Site.Params: 站点下的参数
Page:
页面级参数都定义在页面头部的front matter中,例如:
- title = "Hugo"
- date = 2018-08-13T18:29:20+08:00
- description = ""
- draft = false
- weight = 10
使用方式
- {{ .Params.xxx }} 或者是 {{ .Site.Params.xxx }}
简码(shortcode)是内容(content)文件中的简单代码段,调用内置或自定义模板,在Markdown文件中使用HTML语法实现某些功能。
Hugo使用Markdown是因为其内容格式简单。但是,Markdown有其不足,有时被迫在Markdown文件中使用纯HTML来扩展用法。但这与Markdown语法的简单性相矛盾。为了避免这种限制,Hugo创建了简码。
简码不能用于模板文件。如果需要在模板中插入简码,则很可能需要 partial template 。
除了Markdown更简洁外,简码可以随时更新以反映新的类、技术或标准。在网站生成时,Hugo简码将轻松合并到您的更改中。您避免了可能很复杂的搜索和替换操作。
Hugo通过简码扩展了Markdown用法(在不破坏Markdown语法简单性的基础上使用HTML语法)。Typora编辑器不能识别简码,即只能通过Hugo渲染后在HTML网页上才能浏览效果。
简码在Markdown文件中的调用语法:
- # 分隔符使用% %,内含的源代码使用Markdown语法(可被渲染,**World**显示为粗体)
- # 从Hugo_V_0.55开始,%作为最外层的分隔符,某些简码不能使用%分隔符,触发错误raw HTML omitted
- {{% shortcodename parameters %}}Hello **World**{{% /shortcodename %}}
- # 分隔符使用< >,内含的源代码使用HTML语法(不可被渲染,**World**显示为**World**)
- {{< shortcodename parameters >}}Hello **World**{{< /shortcodename >}}
shortcodename:简码文件(shortcodename.html)的文件名,需要事先定义
parameters:参数
简码的优先级高于代码块
即使将简码放入代码内,Hugo依然识别出简码。若简码文件没有事先定义,Hugo渲染时会触发错误:failed to extract shortcode: template for shortcode “shortcodename” not found。
若想运行简码,简码的源代码不应该放入代码块内
有的简码可在代码块内运行,有的不行。
若想在代码块内放入简码的源代码,需要破坏简码的语法
例如:在{{
之间添加空格或添加注释符号/* */
;使用时,删除增加的部分。
简码的分隔符有% %
(Hugo_V_0.55后,作为最外层的分隔符)和< >
分隔符和大括号之间不能有空格分隔。
简码参数(shortcodename、parameters)之间、分隔符和简码参数之间由空格分隔
若parameters包含空格,则应该使用引号括起,格式为:name="value"
。
示例:引用Hugo的预设简码figure,构建HTML5的figure标签显示图片
- { {< figure src="/images/风车.gif" title="网站logo" >}}
显示效果(经过Hugo渲染后,在HTML网页才能看到效果):
简码在网页HTML结构中显示的标签为:
- <figure>
- <img src="../images/风车.gif" style="cursor: pointer;"> <figcaption>
- <h4>网站logo</h4>
- </figcaption>
- </figure>
Hugo-theme-learn主题的简码:https://learn.netlify.com/en/shortcodes/。
Hugo-theme-docDock主题的简码:https://docdock.netlify.com/shortcodes。
新建简码时,将模板(shortcodename.html文件)放入项目根目录或主题的layouts/shortcodes目录中,Hugo渲染时,会以此目录作为简码的根目录读取简码的HTML文件。
示例:创建一个折叠代码行的简码
新建简码的HTML文件,假设命名为collapsible.html
- <details>
- <summary style="background-color:#f5f5f5;border:1px solid #ccc;padding:5px;">
- {{ with .Get 0}}{{.}}{{else}}click to expand{{ end }}
- </summary>
- {{.Inner}}
- </details>
在Markdown文件中使用简码collapsible
- { {< collapsible "折叠" >}}
- 折叠行的代码内容1<br/.>
- 折叠行的代码内容2
- { {< /collapsible >}}
显示的效果(经过Hugo渲染后,在HTML网页才能看到效果):
在项目根目录中执行hugo server
命令调用Hugo内置的本地web服务器调试预览博客:
--theme
:指定主题--watch
:修改文件后自动刷新浏览器(v0.15版本后,缺省此参数也可自动刷新)--buildDrafts
:编译草稿文件(扉页中的draft值为true)- $ hugo server --theme=hugo-theme-learn --buildDrafts --watch
- Building sites … WARN 2019/11/27 16:09:27 .File.UniqueID on zero object. Wrap it in if or with: {{ with .File }}{{ .UniqueID }}{{ end }}
-
- | EN
- +------------------+----+
- Pages | 10
- Paginator pages | 0
- Non-page files | 1
- Static files | 77
- Processed images | 0
- Aliases | 0
- Sitemaps | 1
- Cleaned | 0
-
- Total in 75 ms
- Watching for changes in E:\Hugo\sites\ebook\{archetypes,content,data,layouts,static,themes}
- Watching for config changes in E:\Hugo\sites\ebook\config.toml
- Environment: "development"
- Serving pages from memory
- Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
- Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
- Press Ctrl+C to stop
实现:源代码推送到源代码仓库后,自动部署到多个不同的发布网站。
将博客部署到:
Pages网站
Git托管平台免费提供的Pages服务,缺点是必须公开仓库(别人可轻易获取代码)。
GitHub Pages
公开GitHub的发布仓库后,就能免费使用GitHub Pages服务。
服务器在国外,国内访问速度不稳定。而且,GitHub Pages屏蔽了百度爬虫,百度无法爬取GitHub Pages网页。
Gitee Pages
Gitee(国内的Git免费托管平台)提供的免费Pages服务(发布仓库可私有,但需要手机验证),服务器在国内,国内访问速度快,但受各种政策影响体验。
Netlify
Netlify是GitHub Pages + Travis CI的完美结合。Netlify在线克隆GitHub源代码仓库(可私有),持续集成和自动部署(Travis CI功能)到其提供的免费网站(Pages服务),然后还额外提供了众多的免费服务。
缺点是服务器在国外,国内访问速度不稳定,而且不能查看发布仓库。
个人网站
个人在域名提供商(例如freenom)购买域名。在国内CDN提供商注册域名需要公安局备案。
一次提交推送到多个仓库(目的纯粹是为了源代码安全)。
为了源代码安全,应该将源代码推送到不同的git代码仓库(例如GitHub和Gitee):
方法一:推送到GitHub后,在Gitee导入GitHub仓库
手动操作:新建仓库 — 导入已有仓库 — 输入已有仓库的git地址。
方法二:手动多次推送到不同仓库
每一个仓库都手动推送一次:
- git remote add origin <仓库的git地址> # 关联仓库
- git push -u origin master # 推送到仓库
方法三:将一个提交一次性推送到不同仓库
将多个地址添加到origin库后,使用git push origin master
一次性push到多个仓库:
- git remote add origin <仓库1的git地址> # 关联仓库1,别名为origin
- git remote set-url --add origin <仓库2的git地址> # origin仓库添加仓库2
- git remote set-url --add origin <仓库3的git地址> # origin仓库添加仓库3,origin仓库共指向3个不同仓库
- git push -u origin master # 推送到3个不同的仓库
以GitHub为例。
在GitHub创建一个源码仓库
仓库名随意,权限可为私有,用来存储博客的源代码(pbulic目录外的所有文件)。若不需要对源代码进行版本管理,可不需要创建源码仓库。
在GitHub创建一个发布仓库
权限公开,才能开启GitHub Pages服务,用来存储博客的发布内容(pbulic目录)。
使用用户仓库
命名为<username>.github.io
,GitHub Pages的网址为http://username.github.io/。一个帐户只能有一个用户仓库,优点是网址相对简单。
使用项目仓库
命名随意,GitHub Pages的网址为http://username.github.io/xxx。一个帐户可以有多个项目仓库。
Hugo生成发布内容(public目录)
在项目根目录内运行hugo --theme=<themename>
命令(若在config.toml已配置了theme
选项,可直接运行hugo
命令),将发布内容生成到public目录。
- $ hugo
- Building sites … WARN 2020/01/07 21:30:32 .File.BaseFileName on zero object. Wrap it in if or with: {{ with .File }}{{ .BaseFileName }}{{ end }}
-
- | EN
- +------------------+-----+
- Pages | 60
- Paginator pages | 0
- Non-page files | 89
- Static files | 211
- Processed images | 0
- Aliases | 17
- Sitemaps | 1
- Cleaned | 0
-
- Total in 833 ms
在public目录内创建本地仓库
- $ cd public # 进入public目录
- $ git init # 新建本地仓库
- $ git add . # 暂存当前目录(public目录)
- $ git commit -m "first commit" # 提交
将pubilc目录推送到GitHub的发布仓库
- $ git remote add origin git@github.com:username/username.github.io.git
- $ git push -u origin master
GitHub根据发布仓库自动创建GitHub Pages网站,浏览器输入网址(https://username.github.io/)就能访问博客
手动部署(Manual Deployment)是一个重复性劳动,既繁琐又耗时且容易出错。因为部署流程基本固定,所以应该交由CI/CD工具自动完成。
编写代码只是软件开发的一小部分,更多时间往往花在构建(build)和测试(test)上。为了提高软件开发效率,持续集成、持续交付、持续部署工具层出不穷。在GitHub市场上提供了众多的持续集成服务提供商(工具)。
持续集成(Continuous Integration)
是一个开发行为,强调开发人员提交新代码后,立刻进行构建、(单元)测试。根据测试结果,即时发现问题,即时修复。
持续交付(Continuous Delivery)
在持续集成的基础上,将集成后的代码部署到更贴近真实运行环境的“类生产环境”(production-like environments)中。例如,完成单元测试后,可以把代码部署到连接数据库的Staging环境中进行更多的测试。若没有问题,可以继续手动部署到生产环境中。
持续部署(Continuous Deployment)
在持续交付的基础上,将部署到生产环境的过程自动化。
Travis CI是一个使用Ruby语言开发、在线托管、开源的分布式持续集成服务提供商,是CI工具中市场份额最大的一个。Travis CI目前有两个官网:
通过Travis CI部署Hugo或者Hexo博客在配置时可能麻烦一点,但配置好后非常方便好用,特别是对于Hugo这种没有部署插件的静态网站生成器。
GitHub使用Travis CI非常简单,因为GitHub的token具有推送代码的权限,一切都能在线操作。
缺点:公开了发布代码(源代码可私有)。
GitHub创建2个远程仓库
仓库A:存放Hugo的输入文件(public目录外的所有文件)
命名随意,权限可为私有。
仓库B:存放博客发布文件(public目录)
使用用户仓库(<username>.github.io
),权限公开,开启GitHub Pages服务。
GitHub生成个人访问令牌(Personal Access Token)
Travis CI自动部署时,需要push内容到仓库的某个分支,而访问GitHub仓库需要用户授权,授权方式就是用户提供访问令牌给Travis CI。
在GitHub生成token(路径:帐户Settings — Developer settings — Personal access tokens — Generate new token),至少需要勾选 public_repo
权限。建议:勾选repo上的所有项目,别的项目一个都不要选。
配置Travis CI Pro
登录(注册)Travis CI Pro
进入Travis CI官网,登录(注册)Travis CI:
首次登录(注册)时,Travis CI请求关联GitHub:
激活帐户,选择源代码仓库
登录后,进入getting_started页面,点击帐户(页面上方的导航栏最右侧登录头像)内的“Settings”:
进入个人帐户(MY ACCOUNT)页面:
首次使用时,激活“GitHub Apps Integration”。
“GitHub Apps Integration”支持私有和公开仓库,与GitHub交互时提供增强的安全性。
点击“Activate”后,弹出页面:
同步帐户
“GitHub Apps Integration”激活完毕后,Travis返回“MY ACCOUNT”页面,并自动(或点击“Sync account”)显示帐户内的仓库。
激活源代码仓库
指定帐户内的某个仓库为源代码仓库。Travis将根据此激活仓库的提交自动部署到博客网站。点击上图中的仓库列表中某一个,即可进入仓库界面:
仓库的功能菜单项有:
Current:仓库的当前状态
可查看最新构建的日志(log):
Build History:仓库的构建历史
Settings:仓库设置,部署触发条件和添加环境变量(Personal Access Token)
勾选触发条件
General、Auto Cancellation、Config Import等选项,使用默认值即可。
设置环境变量(Environment Variables)
在“Environment Variables”中输入token信息后,点击Add按钮:
设置好的变量在配置文件中以 ${变量名}
来引用
Trigger build:手动触发构建
当源代码仓库已有提交时,可手动触发构建。日常使用时,可忽略此步骤。
弹出界面使用默认值即可:
新建Travis配置文件
配置文件(.travis.yml)告诉Travis CI如何部署博客,一个完整的构建生命周期为:
- Install apt addons # (可选)
- Install cache components # (可选)
- before_install # 安装依赖前
- install # 安装依赖
- before_script # 执行脚本前
- script # 执行脚本
- before_cache(for cleaning up cache) # (可选)
- after_success or after_failure # 执行脚本成功(失败)后
- before_deploy # (可选),部署前
- deploy # (可选),部署
- after_deploy # (可选),部署后
- after_script # 执行脚本后
Travis CI的一次构建分为两个阶段:
在本地项目根目录中新建Travis配置文件(.travis.yml),此文件应该上传到仓库A。如果配置文件不在仓库A中,或者不是有效的YAML,Travis CI将无法构建项目。
使用Python语言(Travis指定语言示例 ,Python耗时比Golang少)配置Travis环境。
- language: python # Travis的语言环境为Python
- python:
- - "3.7" # python版本指定为3.7
- branches: # 分支白名单限制
- only:
- - master # 只有master分支的提交才会触发构建
- env: # 设置环境变量
- global:
- - GH_REF: github.com/username/username.github.io.git # 发布仓库的Git地址(使用HTTPS协议)
- install: # 安装依赖项
- - wget https://github.com/gohugoio/hugo/releases/download/v0.62.2/hugo_0.62.2_Linux-64bit.deb # 手动下载Hugo指定版本
- - sudo dpkg -i hugo*.deb # 安装Hugo版本
- script:
- - hugo # 运行hugo命令,生成发布内容(public目录)
- # 将博客发布内容推送到GitHub的发布仓库(不是源代码仓库)
- after_script:
- - cd ./public
- - git init
- - git config user.name "xxx"
- - git config user.email "xxx@xxx.com"
- - git add .
- - git commit -m "Update Blog By TravisCI With Build $TRAVIS_BUILD_NUMBER"
- - git push --force --quiet "https://$GITHUB_TOKEN@${GH_REF}" master:master
-
- # 将博客发布内容推送到GitHub的源代码仓库的另一个分支(需要时,去掉注释,即#号)
- # deploy:
- # provider: pages # 部署到GitHub Pages网站
- # skip-cleanup: true # 必须为true,否则Travis会删除在构建期间创建的所有文件(即删除了计划上传的文件)
- # local-dir: public # 要推送到GitHub Pages的目录,可以指定为当前目录的绝对路径或相对路径
- # on:
- # branch: master # 博客源代码所在分支
- # target-branch: xxx # 将local-dir强制推送到哪个分支(自定义,名称不能与源代码分支名相同),默认为gh-pages
- # github-token: $GITHUB_TOKEN # $GITHUB_TOKEN是一个变量:名称是Travis定义名称,值是GitHub的personal access token的值
- # fqdn: xxx # 使用自定义域名
- # verbose: true # true,表示显示Travis的log
- # keep-history: true # true,表示保持target-branch分支的提交记录
本地仓库
在本地项目根目录中新建一个本地仓库存放Hugo的输入文件(public目录外的所有文件)。
创建忽略文件
本地仓库不应该包含public目录(Travis会在线生成,可忽略)、themes目录(若自定义了主题,则不能忽略)和resources目录(可忽略)。
忽略文件(.gitignore)内容假设为:
- public/
- resources/
当前项目(假设为book)创建本地仓库并推送到GitHub的仓库A
- $ git init
- Initialized empty Git repository in E:/Hugo/sites/book/.git/
- $ git add .
- $ git commit -m "generator code"
- $ git remote add github git@github.com:username/xxx.git
- $ git push -u github master
持续集成和自动部署
若Travis设置了“提交触发build”,本地仓库的每次推送到仓库A,Travis CI都会得到提示,然后根据仓库A中的配置文件(.travis.yml)自动进行部署,实现了博客的自动持续集成(仓库B根据仓库A的内容自动更新,GitHub Pages网站根据仓库B的内容自动更新)。
简单一句话:只需要将写好的文章推送到GitHub的仓库A,不需要编译、不需要推送到仓库B、 甚至连Hugo都可以不安装(假设使用主题没有自定义)。
缺点:源代码和发布代码都公开了。
方法一:参阅利用Travis CI和Hugo將Blog自動部署到Github Pages。
在GitHub创建一个远程仓库
存放Hugo的输入文件和博客发布文件。命名为<username>.github.io
,权限为公开,开启GitHub Pages服务。
GitHub生成个人访问令牌(TOKEN)和配置Travis CI
步骤同上。
新建Travis CI的配置文件(.travis.yml)
- # https://docs.travis-ci.com/user/deployment/pages/
- # https://docs.travis-ci.com/user/reference/xenial/
- # https://docs.travis-ci.com/user/languages/python/
- # https://docs.travis-ci.com/user/customizing-the-build/
-
- dist: xenial
- language: python
- python:
- - "3.7"
-
- # install - install any dependencies required
- install:
- # install latest release version
- # Github may forbid request from travis container, so use tor proxy
- # - curl -fsL --socks5-hostname 127.0.0.1:9050 https://api.github.com/repos/gohugoio/hugo/releases/latest | sed -r -n '/browser_download_url/{/Linux-64bit.deb/{s@[^:]*:[[:space:]]*"([^"]*)".*@\1@g;p;q}}' | xargs wget
- - wget https://github.com/gohugoio/hugo/releases/download/v0.62.2/hugo_0.62.2_Linux-64bit.deb
- - sudo dpkg -i hugo*.deb
-
- # script - run the build script
- script:
- - hugo
-
- deploy:
- provider: pages
- skip-cleanup: true
- github-token: $token
- email:
- name:
- verbose: true
- keep-history: true
- local-dir: public
- target_branch: master # branch contains blog content
- on:
- branch: code # branch contains Hugo generator code
本地仓库
创建忽略文件
本地仓库不应该包含public目录(Hugo本地编译时产生)、themes目录(存放主题)和resources目录(由主题产生)。
忽略文件(.gitignore)内容假设为:
- public/
- resources/
当前项目(假设为book)创建本地仓库
- $ git init
- Initialized empty Git repository in E:/Hugo/sites/book/.git/
分支A(code分支)
命名为code,存放Hugo的输入文件(博客工程文件,即public目录外的文件)。
- $ git checkout -b code
- # 在code分支
- $ git add .
- $ git commit -m "generator code"
- $ git remote add github git@github.com:username/username.github.io.git
- $ git push -u github code
分支B(master分支)
命名为master,博客发布文件(即public目录)存放在master分支。
- # 在code分支
- $ hugo # 生成public目录
- $ HUGO_TEMP_DIR=$(mktemp -d) # 设置临时变量
- $ cp -R public/* "$HUGO_TEMP_DIR" # public目录复制到临时变量
- $ git checkout --orphan master # 创建master分支
- # 在master分支
- $ rm .git/index # 清除暂存区
- $ git clean -fdx # 清除未跟踪文件,当前目录只剩下.git目录
- $ cp -R "$HUGO_TEMP_DIR"/. . # public目录内容复制到当前目录
- $ git add .
- $ git commit -m 'initial blog content'
- $ git push -u github master
- $ [[ -d "$HUGO_TEMP_DIR" ]] && rm -rf "$HUGO_TEMP_DIR" # 删除临时变量
- # 切换到code分支,以后应该只在code分支
- $ git checkout code
持续集成
如果上述步骤中设置了“提交触发build”,本地仓库的每次推送到code分支,Travis CI会自动进行部署,将上传的博客内容(code分支)更新到仓库的master分支中,实现了博客的持续集成(GitHub Pages网站根据master分支内容自动更新),不再需要关心travis状态。
方法二:
GitHub Pages和Netlify的服务器在国外,国内访问速度慢且稳定性差。解决这一问题的最优解是购买个人域名使用CDN。对于不想购买个人域名的人来说,使用Gitee Pages(码云的Pages服务)是当前的最优解决方案。
码云仓库(可为私有,GitHub的必需公开)开启Pages服务需要绑定手机号(不需要在公安局备案)。码云是国内的Git托管平台,所以在国内访问速度超快(对比GitHub)且稳定。仓库有更新时,Gitee Pages貌似不会自动更新,需要手动更新(GitHub Pages是自动更新)。
Gitee使用Travis CI比较麻烦,因为Gitee的token没有推送代码的权限,所以需要下载Travis CI到本地,然后在本地加密私钥文件或密码,最后使用加密后的密码push。
参阅:travis官网文档、手摸手教你搭建Travis CI持续集成和自动化部署、使用travis-ci自动部署hexo博客、Hexo集成Travis CI。
使用Travis CI部署到Gitee的过程:
源代码仓库是GitHub仓库
因为Travis CI只能使用GitHub帐户注册,因此只能绑定GitHub仓库为源代码仓库。
发布仓库是Gitee仓库
修改Travis配置文件(.travis.yml)中的GH_REF变量(发布仓库,为了区分不同的仓库,名称可自定义命名)的值为Gitee仓库的git地址:
- env: # 设置环境变量
- global:
- - GH_REF: github.com/username/username.github.io.git # GitHub发布仓库的Git地址(使用HTTPS协议)
- #- GE_REF: gitee.com/username/username.git # Gitee发布仓库的Git地址(使用HTTPS协议)
自动验证密码
Gitee的token没有推送代码的权限,所以此命令失效:
- git push --force --quiet "https://$Gitee_TOKEN@${GE_REF}" master:master # 强制推送到Gitee发布仓库
改用其它方式验证密码:
使用https协议,显式添加用户名、密码进行推送
- git push --force --quiet "https://用户名:密码@${GE_REF}" master:master
缺点:彻底暴露Gitee帐户的用户名和密码(即使GitHub仓库是私有),风险极大。
使用ssh协议,使用私钥文件免密推送
- git push --force --quiet "git@gitee.com:用户名/用户名.git" master:master
缺点:需要将本地的私钥文件推送到GitHub仓库,风险极大。
通过加密私钥文件或密码
具体的Travis配置文件(.travis.yml)与GitHub的基本一致
无论是使用token(GitHub,token在Travis CI中显式显示),还是显式使用密码或上传或ssh私钥(Gitee),即使源代码仓库是私有的,也是存在极大风险。
Travis提供了加密服务,可以对密码或者私钥文件进行加密。
本地安装Ruby
Travis客户端使用Ruby语言编写,所以先安装Ruby。(参阅:Ruby 安装 - Windows)
不建议安装Ruby for Windows。因为Windows不支持openssl验证,导致Travis对密钥文件解密时触发错误:The command “openssl xxx -in id_rsa.enc -out ~/.ssh/id_rsa -d” failed and exited with 1 during。
验证Ruby和gem(安装Ruby时自动安装)是否安装成功:
- $ ruby -v
- ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x64-mingw32]
- $ gem -v
- 3.1.2
本地安装Travis客户端
- $ gem install travis
验证是否安装成功:
- $ travis -v
- D:/Program/Ruby/lib/ruby/gems/2.7.0/gems/highline-1.7.10/lib/highline.rb:624: warning: Using the last argument as keyword parameters is deprecated
- 1.8.10
关联GitHub源代码仓库
(克隆GitHub源代码仓库)进入本地工程目录,输入命令:
- $ travis login --auto --pro
- Username:xxx # 输入GitHub帐户名
- Password for xxx: xxx # 输入GitHub帐户密码
- Successfully logged in as xxx!
加密
加密本地系统的私钥文件(~/.ssh/id_rsa文件),使用SSH协议push
- $ travis encrypt-file ~/.ssh/id_rsa --add
- # 下面是命令行打印的日志
- Detected repository as xxx/xxx, is this correct? |yes| yes
- encrypting ~/.ssh/id_rsa for xxx/xxx
- storing result as id_rsa.enc
- storing secure env variables for decryption
- Make sure to add id_rsa.enc to the git repository.
- Make sure not to add ~/.ssh/id_rsa to the git repository.
- Commit all changes to your .travis.yml.
第一行:运行命令,加密~/.ssh/id_rsa文件
第二行:检测Travis绑定的GitHub源代码仓库,若正确,输入yes
第三行:为GitHub源代码仓库加密本地系统的私钥文件
第四行:在本地工程根目录内生成id_rsa.enc文件(已加密),.travis.yml内自动添加(清空所有备注)以下配置信息
- before_install:
- - openssl aes-256-cbc -K $encrypted_xxx_key -iv $encrypted_xxx_iv
- -in id_rsa.enc -out ~\/.ssh/id_rsa -d
实际使用时,要将\
去掉,否则会编译失败。
第五行:存储用于解密的安全环境变量
第六行:将id_rsa.enc文件推送到GitHub源代码仓库
第七行:不能将本地系统的私钥文件推送到GitHub源代码仓库
第八行:.travis.yml的修改推送到GitHub源代码仓库
.travis.yml的最终结果:
- language: python # Travis的语言环境为Python
- python:
- - "3.7" # python版本指定为3.7
- branches: # 设置分支白名单
- only:
- - master # 只有master分支的提交才会触发构建
- addons:
- ssh_known_hosts:
- - gitee.com
- env: # 设置环境变量
- global:
- # - GH_REF: github.com/koman/koman.github.io.git # GitHub发布仓库的Git地址(使用HTTPS协议)
- - GE_REF: gitee.com:koman/koman.git # Gitee发布仓库的Git地址(使用SSH协议)
- before_install: # 加密密码
- - openssl aes-256-cbc -K $encrypted_abf3a382006f_key -iv $encrypted_abf3a382006f_iv -in id_rsa.enc -out ~/.ssh/id_rsa -d
- - eval "$(ssh-agent -s)" # 开启ssh-agent,即允许使用ssh命令
- - chmod 600 ~/.ssh/id_rsa # 给予id_rsa文件权限,避免警告
- - ssh-add ~/.ssh/id_rsa # 将私钥添加到ssh
- install: # 安装依赖项
- - wget https://github.com/gohugoio/hugo/releases/download/v0.62.2/hugo_0.62.2_Linux-64bit.deb # 手动下载Hugo指定版本
- - sudo dpkg -i hugo*.deb # 安装Hugo版本
- script:
- - hugo # 运行hugo命令,生成发布内容(public目录)
- after_script: # 博客发布内容推送到发布仓库
- - cd ./public
- - git init
- - git config user.name "koman"
- - git config user.email "komantao@hotmail.com"
- - git add .
- - git commit -m "Update Blog By TravisCI With Build $DATE"
- # - git push --force --quiet "https://${Github_TOKEN}@${GH_REF}" master:master
- - git push --force --quiet "git@${GE_REF}" master:master
-
- # 博客发布内容推送到GitHub的源代码仓库的另一个分支(需要时,去掉注释,即#号)
- # deploy:
- # provider: pages # 部署到GitHub Pages网站
- # skip-cleanup: true # 必须为true,否则Travis会删除在构建期间创建的所有文件(即删除了计划上传的文件)
- # local-dir: public # 要推送到GitHub Pages的目录,可以指定为当前目录的绝对路径或相对路径
- # on:
- # branch: master # 博客源代码所在分支
- # target-branch: xxx # 将local-dir强制推送到哪个分支(自定义,名称不能与源代码分支名相同),默认为gh-pages
- # github-token: $GITHUB_TOKEN # $GITHUB_TOKEN是一个变量:名称是Travis定义名称,值是GitHub的personal access token的值
- # fqdn: xxx # 使用自定义域名(即不使用GitHub Pages网站)
- # verbose: true # true,表示显示Travis的log
- # keep-history: true # true,表示保持target-branch分支的提交记录
加密密码,使用HTTPS协议push
如果密码中有特殊符号,需要转义:例如@需要转成%40。
- $ travis encrypt gitee_password=xxx --add
.travis.yml文件的global变量增加一个secure字段
- env:
- global:
- - secure: xxxxxx # 加密后的密码
.travis.yml的最终结果:
- language: python
- python:
- - '3.7'
- branches:
- only:
- - master
- env:
- global:
- - GE_REF: gitee.com/xxx/xxx.git
- - secure: xxxxxx
- install:
- - wget https://github.com/gohugoio/hugo/releases/download/v0.62.2/hugo_0.62.2_Linux-64bit.deb
- - sudo dpkg -i hugo*.deb
- script:
- - hugo
- after_script:
- - cd ./public
- - git init
- - git config user.name "xxx"
- - git config user.email "xxx@xxx.com"
- - git add .
- - git commit -m "Update Blog By TravisCI With Build $DATE"
- - git push --force --quiet "https://xxx:${gitee_password}@${GE_REF}" master:master
Netlify是国外一家提供静态网络托管服务的综合平台,专注于静态网站托管的web服务,完美且免费支持ssl、域名绑定、http/2和TLS,官网宣传其是一个工作流(workflow),包含构建一个网站所需的一切。
Netlify的功能:
托管静态资源
与GitHub Pages一样,但比GitHub Pages强多了,而且速度也快。两者的对比在netlify官网有介绍。
将静态网站部署到CDN,加速国内访问
GitHub Pages无法进行CDN加速。Netlify能够使用自带CDN加速服务。
持续部署(Continuous Deployment)
当博客源码提交推送到托管平台后,Netlify就会自动运行build command(自动克隆博客源码仓库,自动判断博客框架,自动运行build命令生成博客发布代码),自动部署到绑定域名。
Netlify更关注于前端(网站或APP)的持续集成与持续部署,这是它与其他持续集成工具最大的区别。而且,Netlify的使用非常简单。
可以添加自定义域名(个人购买的域名)
可以启用免费的TLS证书,启用HTTPS
自带CI、支持重定向、插入代码、打包和压缩JS和CSS、压缩图片、处理图片
重定向(也称URL转发)。GitHub Pages对redirects、重定向(也称URL转发)支持并不友好,如果放弃GitHub Pages提供的username.github.io子域名时很麻烦。对比之下,从username.netlify.com重定向(重定向编码是301或302)至新发布网站时很简单。重定向后,搜索引擎可以清楚识别你的页面已被转移,从而对你的新页面进行重新排名。所以即使哪天Netlify车毁人亡,只要设定好了重定向,你的网站也不会受到任何影响。
登录(注册)Netlify,关联GitHub帐户
Netlify提供邮箱注册和包括GitHub在内的第三方验证登陆(注册)。
选择第三方(GitHub)验证登陆(注册)
GitHub授权验证登陆Netlify
关联GitHub账户
登录后,页面自动(或点击导航栏上方的Netlify图标)跳转到“New site from Git”,点击“New site from Git”:
页面跳转到“Create a new site”,点击GitHub:
Netlify首次关联GitHub仓库时,弹出窗口:
点击“Authorize Netlify by Netlify”同意授权后,Netlify就有权访问GitHub仓库内容。
选择仓库
授权完毕后,页面跳转到“Install Netlify”,选择GitHub的源代码仓库(可为私有仓库):
点击Install后,等待一段时间,页面跳转回“Create a new site”,显示关联后的仓库:
构建选项和部署
点击上图中的已关联仓库,进入第3步骤:
Owner:Netlify自动识别,已绑定了托管平台的仓库
Branch to deploy:被部署分支,存储源代码的分支
Build command:构建命令
Netlify会自动判断博客框架,自动显示命令,可自定义参数。
Publish directory:发布目录,默认为public
show advanced:提示将netlify.toml添加到存储库中,可获得更大的灵活性
在本地项目根目录内新建netlify.toml文件,保存后上传到GitHub的源代码仓库:
- [build]
- publish = "public"
- command = "hugo"
- [context.production.environment]
- HUGO_VERSION = "0.62.2"
- HUGO_ENV = "production"
- HUGO_ENABLEGITINFO = "true"
- [context.split1]
- command = "hugo --enableGitInfo"
- [context.split1.environment]
- HUGO_VERSION = "0.62.2"
- HUGO_ENV = "production"
- [context.deploy-preview]
- command = "hugo -b $DEPLOY_PRIME_URL"
- [context.deploy-preview.environment]
- HUGO_VERSION = "0.62.2"
- [context.branch-deploy]
- command = "hugo -b $DEPLOY_PRIME_URL"
- [context.branch-deploy.environment]
- HUGO_VERSION = "0.62.2"
- [context.next.environment]
- HUGO_ENABLEGITINFO = "true"
Netlify的构建环境使用Unix。
构建并发布网站
前面3个步骤完成后,点击上图中的“Deploy site”按钮(Netlify自动构建并发布博客内容)后,开始构建并发布网站:
网站发布成功后,网站地址:“https://” + 随机生成的子域名 + “.netlify.com”。
美化Netlify子域
默认情况下,基于Netlify子域访问站点。若不喜欢Netlify随机子域且没有购买自定义域名,可以将Netlify子域美化(自定义名称):
自定义域名
点击上上图中的“Set up a custom domain”,进入添加域名页面:
输入已购买的域名(不包含www),点击“Verify”后设置DNS(以GitHub Pages示例):
要求必须拥有域名所有权才能完成所有步骤,所以自定义域名不能使用Pages网站。
由于没有个人域名,此步骤暂停。
网站(Netlify子域)设置
路径:选择网站(Netlify子域)— 导航栏点击“Settings” — Build & deploy — 编辑设置。
设置内容有:持续部署命令、webhooks、构建映像、环境变量、注入代码、资产优化(压缩CSS/JS/图片文件)、预渲染等。
内容管理系统(content management system,简称CMS)是指在一个合作模式下,用于管理工作流程的一套制度。该系统可应用于手工操作中,也可以应用到电脑或网络。作为一种中央储存器(central repository),内容管理系统可将相关内容集中储存并具有群组管理、版本控制等功能。版本控制是内容管理系统的一个主要优势。
Netlify CMS是一款团队的编辑工具,但可以作为个人博客的在线编辑工具,可以随时随地修改、编辑博客内容,而不用考虑多设备同步的问题。
Netlify提供了自定义页面重定向的功能。如果你的域名或者文章结构发生了变化,可以借助重定向功能,将原来的文章URL重定向到现在的地址。
新建一个netlify.toml文件,存放在博客的根目录下,在里面添加以下内容:
- [[redirects]]
- from = "https://原始域名/*"
- to = "https://自定义域名/:splat"
- force = true
Netlify通过API ID绑定GitHub仓库
若删除了GitHub的源代码仓库,即使之后重建(名称一样),Netlify也自动部署失败。因为绑定仓库的API ID已改变,需要重新绑定。
对TOC的分层理解
在config.toml内设置startLevel = 2
的前提下:
<ul>
标签<ul>
标签解决方法:在config.toml内设置startLevel = 1
对嵌套列表的理解
无序列表和有序列表混用时,Hugo正常显示,Netlify有时会格式错乱。添加了netlify.toml文件后,格式错乱问题自动解决。
在web上,越来越多的操作被描述为事件。webhook(网络钩子)是一种web回调或者http的push API,是向APP或者其他应用提供实时信息的一种方式。Webhook在数据产生时立即发送数据,也就是你能实时收到数据。这一种不同于典型的API,需要用了实时性需要足够快的轮询。这无论是对生产还是对消费者都是高效的,唯一的缺点是初始建立困难。webhook是一种实现事件响应的方式,用于在项目发生事件时通知外部服务器。
以Gitee示例演示webhook的用法。
原理:
git push
命令,push代码到Gitee仓库git pull
和重启服务等命令GitHub Pages和Netlify的服务器都部署在海外,在国内访问本博客的速度会比较慢 (Ping 下来100到200多毫秒)。解决这一问题的最优解就是使用CDN。
CDN(Content delivery network或Content distribution network,内容分发网络)是指一种通过互联网互相连接的计算机网络系统,利用最靠近每位用户的服务器,更快、更可靠地将音乐、图片、影片、应用程序及其他文件发送给用户,来提供高性能、可扩展性及低成本的网络内容传递给用户。
简单来说,CDN就是部署在世界各地的缓存服务器,它们会提前缓存网站上的资源,然后当用户想要访问相关资源时,直接从CDN服务器上取就可以了。这样不仅可以增加访问速度、减少访问延迟,还可以减缓网站服务器上的压力。
要使用CDN,需要在域名提供商更改DNS服务器,变为它提供的域名服务器地址。CDN服务提供商有很多,国内的有七牛云、阿里云、腾讯云等,国内的CDN都要求域名在公安局备案。国外的不需要备案。
Cloudflare是全球最大的DNS服务提供商之一 (号称全球最快的DNS1.1.1.1
就是它搞的)。除此之外,还提供CDN、SSL证书、DDos保护等服务,Cloudflare还与百度有合作,在国内部署有大量的节点,还能顺便解决百度爬虫无法抓取GitHub Pages的问题。
在Cloudflare注册一个帐号,注册好后点击“Add site”添加你的网站:
没有个人网站,此步骤暂停。
若使用国内的评论插件,前提是网站需要在公安局备案,因此转向使用国外的评论插件。
官方的GitHub仓库: https://github.com/gitalk/gitalk/。
官方网站:https://gitalk.github.io/
Gitalk是一个基于GitHub Issue和Preact开发的评论插件,支持多种语言 (包括en、zh-CN、zh-TW、es-ES、fr)并自动判断当前语言。最重要的是Gitalk使用的是GitHub Issue的api,不依赖任何第三方平台。也就是说,只要Github不倒闭,你的评论系统就不会被关闭。
原理:Hugo是将Markdown文档按照主题 (包括HTML模板、CSS、JavaScript等) 编译成静态网页。所以只需要将Gitalk作为一个<div>
插入到HTML模板中,然后在config.toml中添加相关配置,就可以实现“评论区”了。
步骤为:
新建一个评论仓库
新建一个仓库(或博客发布仓库)作为存放评论的仓库(The repo to store comments),点击菜单栏中的“Settings”,勾选“Issues”,Gitalk会将评论放在这个仓库的issues里面。
注册Github Application
在GitHub注册一个Oauth Application,让Gitalk有权限操作GitHub上的仓库。
OAuth application的新建页面:
添加模板gitalk.html
在主题的layouts/partials目录中新建gitalk.html文件:
- {{ if .Site.Params.enableGitalk }}
- <div id="gitalk-container"></div>
- <link rel="stylesheet" href="https://unpkg.com/gitalk/dist/gitalk.css">
- <script src="https://unpkg.com/gitalk/dist/gitalk.min.js"></script>
- <script>
- const gitalk = new Gitalk({
- clientID: '{{ .Site.Params.Gitalk.clientID }}',
- clientSecret: '{{ .Site.Params.Gitalk.clientSecret }}',
- repo: '{{ .Site.Params.Gitalk.repo }}',
- owner: '{{ .Site.Params.Gitalk.owner }}',
- admin: ['{{ .Site.Params.Gitalk.owner }}'],
- id: location.pathname, // Ensure uniqueness and length less than 50
- distractionFreeMode: false // Facebook-like distraction free mode
- });
- (function() {
- if (["localhost", "127.0.0.1"].indexOf(window.location.hostname) != -1) {
- document.getElementById('gitalk-container').innerHTML = 'Gitalk comments not available by default when the website is previewed locally.';
- return;
- }
- gitalk.render('gitalk-container');
- })();
- </script>
- {{ end }}
主题(themes/hugo-theme-docdock/layouts/partials/custom-content-footer.html)调用gitalk.html文件,放置位置在版权信息前面:
- {{ partial "gitalk.html" . }}
配置config.toml
在config.toml中添加以下配置(参数名称对应gitalk.html文件中的命名):
- [params]
- enableGitalk = true # true时,开启Gitalk评论插件
- [params.gitalk]
- clientID = "xxx" # GitHub应用程序(Gitalk)生成的client ID
- clientSecret = "xxx" # GitHub应用程序(Gitalk)生成的client secret
- repo = "discuss" # 存储评论(comments)的仓库名
- owner = "xxx" # GitHub仓库的所有者(owner)的GitHub ID
- admin= "xxx" # GitHub仓库的所有者和合作者(collaborators),指对仓库具有写访问权限的用户
- id= "location.pathname" # 页面的唯一ID,标记评论是哪个页面,并且长度小于50
- labels= "gitalk" # Github的issue标签
- perPage= 15 # 分页大小(Pagination size),最大为100
- pagerDirection= "last" # 评论排序方向,可用值为'last'和'first'
- createIssueManually= false # true时, 无干扰模式(在评论仓库的issue内不显示管理员登录信息)
- distractionFreeMode= false # true时,启用热键(cmd|ctrl + enter)提交评论
初始化评论区
设置好后,将博客内容推送到发布网站,首次启用Gitalk需要初始化(运行hugo server
时,gitalk.html文件设置不启用Gitalk)。未初始化时,弹出警告提示如下:
使用注册Github Application时的账号登陆并授权:
授权后进入每一篇博客刷新页面,才能激活每一篇博客的评论区。
SEO(Search Engine Optimization,搜索引擎优化),利用搜索引擎的规则提高网站在有关搜索引擎内的自然排名。目的是让其在行业内占据领先地位,获得品牌收益。
检查网站是否被收录:Google/百度搜索框输入site:yoursite.github.io
。
验证网站:Google搜索引擎、百度搜索引擎。
验证方法:
网站上线后,做SEO时需要检查如下内容:
集成Google Analytics或百度统计
为页面增加header信息,如title和description
sitemap.xml
将网站生成工具自动生成的站点地图的URL提交给Google Webmaster Tools。
robots.txt
阻止搜索引擎爬取网站上的敏感网页。
结构化数据:可以帮助爬虫理解页面内容,参考HTML5的结构化数据
描述(description)
在config.toml中设置网站描述信息:
- [params]
- description = "xxxxxx"
在每篇文章的扉页中设置文章描述信息:
- +++
- description = "Where you should come to find my homepage updates and stuff"
- +++
在themes/hugo-theme-docdock/layouts/partials/original/head.html或themes/hugo-theme-docdock/layouts/partials/original/custom-head.html文件(简称head.html)中添加<meta>
标签:
- <meta name="description" content="{{ with .Description }}{{ . }}{{ else }}{{ with .Site.Params.description }}{{ . }}{{ end }}{{ end }}">
文章关键词(keywords)
在每篇文章的扉页中设置keywords:
- +++
- keywords = [mysite,mysite keyword,Another useful keyword]
- +++
然后,在<head>
标签(head.html)内添加<meta>
标签:
- <meta content="{{ delimit .Keywords ", " }}" name="keywords">
文章标题(title)
每篇文章都应有一个标题,方便搜索引擎收录。Hugo生成的文章会在<head>
标签内自动添加<title>
标签。若无,在文章模板的<head>
标签内添加<title>
标签。
- <title>{{ $isHomePage := eq .Title .Site.Title }}{{ .Title }}{{ if eq $isHomePage false }} - {{ .Site.Title }}{{ end }}</title>
也可以在<meta>
标签中添加标题标签。
- <meta content="{{ $isHomePage := eq .Title .Site.Title }}{{ .Title }}{{ if eq $isHomePage false }} - {{ .Site.Title }}{{ end }}" property="og:title">
进入Google Search Console
打开Google网站站长,点击“SEARCH CONSOLE ”进入:
验证所有权
进入验证页面:
要求下载一个html文件(google××××.html
),将这个html文件保存到hugo站点根目录内的static子目录,提交推送到被验证网站后,回到验证页面点击“验证”。
资源
验证成功后,点击“前往资源页面”:
点”索引”下的”站点地图”,
在”添加新的站点地图”处输入被验证网站的sitemap(自动生成,存放在网站根路径):
等待一天左右就可以搜到了!
打开百度搜索资源平台的链接提交,输入网址:
提交后,百度不保证一定能够收录您提交的链接。
点击“用户中心” — “站点管理” — “添加网站”时,或使用站长工具需要实名认证。
和Google不一样,百度不容许以子目录的方式提交子站点,https://xxx.github.io/xxx/`的形式就不能直接提交了,只能在提交sitemap文件时,提交多个sitemap文件。这样也能勉强让百度收录。
Hugo除了能够制作个人博客网站外,还能制作脑图(mindmap,又称思维导图)和HTML格式的幻灯片(slide)。
参阅:Hugo中使用思维导图。此方法尚未实现。
想要在blog中插入脑图,之前一直都在使用插入图片的方法,这样非常不优雅。
基于百度的kityminder修改为适用于Hugo:
在这里下载插件
在线引用jquery.min.js插件
- <script src="https://cdn.bootcss.com/jquery/3.4.1/jquery.min.js"></script>
通常情况下,主题已具备,不需要另外准备。
在这里下载kityminder.css,改名为kityminder.core.css,放入hugo目录的**static/css/**中
引用文件
在模板的head标签(themes/hugo-theme-docdock/layouts/partials/original/head.html)内引用文件:
- <link href="{{.Site.BaseURL}}css/kityminder.core.css" rel="stylesheet">
- <link href="{{.Site.BaseURL}}css/mindmap.css" rel="stylesheet">
- <script src="{{.Site.BaseURL}}js/kity.min.js"></script>
- <script src="{{.Site.BaseURL}}js/kityminder.core.min.js"></script>
- <script src="https://cdn.bootcss.com/jquery/3.4.1/jquery.min.js"></script></script>
- <script src="{{.Site.BaseURL}}js/mindmap.js"></script>
使用shortcodes(简码)将Markdown渲染为html
在hugo目录layouts/shortcodes下新建一个 html(例如为mind.html):
- <div id="{{ .Get 0 }}" class="mindmap">
- {{- .Inner -}}
- </div>
这个shortcodes非常简单,就是将其中的内容渲染出来套个div标签,加上mindmap的类名。
然后在Markdwon中添加文本
- { {< mind mindid >}}
- - 根目录
- - 一级目录1
- - 二级目录1
- - 二级目录2
- - 一级目录2
- { {< /mind >}}
凡事都不会一帆风顺。Hugo渲染后无显示结果
通过Hugo制作的脑图,实现的功能和样式单一。现改变思路:Hugo引用脑图的HTML文件。此方法的脑图的功能和样式由制作工具决定,缺点是转换的HTML文件容量比较大。
首先,通过专用工具(例如mindmanager)制作脑图,脑图导出为HTML文件
下载mindmanager版本,搜索注册码(目前可用:MP20-345-DP56-7778-919A)破解。制作脑图后,“另存为”时选择保存类型为HTML5交互式导图(*.html)。
然后,Hugo引用脑图导出的HTML文件
假设脑图的HTML文件为Git.html,必须存放在static目录内。避免被Hugo渲染。否则,Hugo渲染脑图文件时会触发错误(命令中存在“-”字符):
Rebuild failed: “E:\xxx\xxx.html:16:1”: template: __E:\xxx\xxx.htmlHTML:16: unexpected bad character U+002D ‘-’ in command
16 < script id="mmap-config” type="text/plain">{{mmap-config}}< /script >
方法一:使用button简码跳转到指定页面显示脑图
优点是布局简洁且不影响当前页面的加载速度(需要时,才点击按钮,在本页面显示脑图的HTML文件内容。缺点是覆盖了本页面(来回切换页面)。
button简码默认在本页跳转到指定页面(onclick="location.href='{{.}}'"
),修改后(onclick="window.open('{{.}}')"
),可在新页跳转到指定页面。
docDock主题的button简码(button.html)的源代码为:
- <!-- Boutton -->
- {{ with .Get "align" }}<center>{{end}}
- <button class="btn {{with .Get "theme"}}btn-{{.}}{{else}}btn-primary{{end}}" type="button" {{ with .Get "href" }} onclick="location.href='{{.}}'"{{end}} >{{.Inner}}</button>
- {{ with .Get "align" }}</center>{{end}}
- <!-- Boutton -->
在Markdown文件中使用button简码:
- { {< button href="/images/Git.html" >}} Git的思维导图 { {< /button >}}
方法二:使用<iframe>
框架跳转到子页面显示脑图
优点是在当前页面显示另一个HTML页面(又称外部页面、子页面)的内容且能自定义CSS;缺点是脑图文件过大,严重影响当前页面的加载速度。
定义一个<iframe>
框架
在当前页面嵌套子页面:
- <iframe id="xxx" name="xxx" frameborder="0" style="display:block;width:100%; height:545px;" src="url"></iframe>
id或name=“xxx”:区分不同的子页面
frameborder="0|1”:0表示无边框;1表示有边框
style="CSS”:设置子页面的CSS
width为子页面的宽,height为子页面的高;可以使用百分比,会自适应父容器的百分比,也可以使用固定的行高列宽:100px,60px。
src="url”:设置子页面的关联url(链接地址),url可为任意文件类型
scrolling="auto|yes|no”:是否显示子页面滚动条,缺省时值为auto
若只打算在Markdown文件中显示脑图
需要在config.toml文件中开启unsafe = true
,url输入脑图的相对路径(相对于当前的Markdown文件)。
若打算在Hugo(个人博客)中显示脑图
新建(<iframe>
框架修改为)一个简码文件(存入layouts/shortcodes目录,假设为mind.html):
- <iframe id="{{ .Get 0 }}" name="{{ .Get 0 }}" frameborder="0" style="display:block;width:100%; height:545px;" src="{{ .Get 1 }}">
- </iframe>
{{ .Get 0 }}
:0表示使用第一个传入参数;1表示使用第二个传入参数Markdown文件使用简码:
- { {< mind mindid "/images/Git.html" >}}
幻灯片,是使用全屏来显示Markdown文件内容的页面。
Markdown文件内容可以呈现为全屏的manifest.js演示文稿。manifest.js使您可以使用HTML创建漂亮的交互式幻灯片。参阅:PRESENT A SLIDE。
在Markdown文件的扉页中设置type="slide"
和[revealOptions]
- +++
- title = "Test slide" # Markdown文件的标题
- type="slide" # Markdown文件的类型:slide(幻灯片)
- theme = "league" # revel.js框架(幻灯片)的主题
- [revealOptions]
- transition= 'concave' # 幻灯片过渡类型值:none|fade|slide|convex|concave|zoom
- controls= true # 显示幻灯片的控制箭头
- progress= true # 显示幻灯片的演示进度条
- history= true # 将每个幻灯片的更改记入浏览器历史记录
- center= true # 滑块垂直对中
- +++
幻灯片定界符
在Markdown文件中为幻灯片演示文稿创建内容时,使用定界符区分每一张幻灯片:
水平幻灯片的定界符:3个减号---
垂直幻灯片的定界符:3个下划线___
通常,垂直幻灯片用于在顶层水平幻灯片下方显示信息。
创建幻灯片内容
使用#
标记标题的层级
- # In the morning
-
-
- 4. 使用HTML语法实现各种功能
-
- reveal.js控制幻灯片的行为和样式,Markdown控制幻灯片的内容,HTML语法控制幻灯片的多媒体功能。Hugo的设置(例如:**config.toml**内的设置、简码等)在幻灯片中无效,可直接使用HTML语法扩展幻灯片的多样化功能。
-
-
-
- ## 参考资料
-
- > 官网:
- >
- > - [Hugo官网](https://gohugo.io/)
- > - [Hugo官网中文镜像](https://s0gohugo0io.icopy.site/ )
- > - [Hugo官方教程(英文)Hugo Docs](https://gohugo.io/documentation/)
- > - [HUGO LEARN THEME](https://learn.netlify.com/en/)
- > - [Travis CI官方文档](https://docs.travis-ci.com/)
- > - [Netlify官方文档](https://docs.netlify.com/)
- >
- > 个人博客:
- >
- > - [Tutorials for the Hugo static site generator](https://kodify.net/hugo-static-site-tutorials/)
- > - [Blog养成记](https://orianna-zzo.github.io/series/blog养成记/)
- > - [本站引用图片的“顺滑”流程](https://rayhy.com/blog/20190301-本站引用图片的顺滑流程/)
- > - [Hugo静态网站生成器中文教程](http://nanshu.wang/post/2015-01-31/)
- > - [Hugo 搭建博客实践](https://creaink.github.io/post/Devtools/Hugo/Hugo-intro.html)
- > - [使用Hugo建个网站](https://lyzhang.me/post/make_a_blog_with_hugo/)
- > - [hugo中文帮助文档](https://hugo.aiaide.com/)
- > - [Hugo学习笔记](https://skyao.io/learning-hugo/)
- > - [苏洋博客](https://soulteary.com/)
- > - [静态网站构建手册-使用Hugo构建个人博客](https://jimmysong.io/hugo-handbook/)
-
- ## 操作环境
-
- > - 操作系统:Win 10
- > - Hugo工具:hugo_0.61.0_Windows-64bit
感谢您的赞赏支持: