目录

主题文档 - 内容

了解如何在 LoveIt 主题中快速, 直观地创建和组织内容.

内容组织

以下是一些方便你清晰管理和生成文章的目录结构建议:

  • 保持博客文章存放在 content/posts 目录, 例如: content/posts/我的第一篇文章.md
  • 保持简单的静态页面存放在 content 目录, 例如: content/about.md
  • 本地资源组织
本地资源引用

LoveIt 新增 | 0.2.10

有三种方法来引用图片音乐等本地资源:

  1. 使用页面包中的页面资源. 你可以使用适用于 Resources.GetMatch 的值或者直接使用相对于当前页面目录的文件路径来引用页面资源.
  2. 将本地资源放在 assets 目录中, 默认路径是 /assets. 引用资源的文件路径是相对于 assets 目录的.
  3. 将本地资源放在 static 目录中, 默认路径是 /static. 引用资源的文件路径是相对于 static 目录的.

引用的优先级符合以上的顺序.

在这个主题中的很多地方可以使用上面的本地资源引用, 例如 链接, 图片, image shortcode, music shortcode 和前置参数中的部分参数.

页面资源或者 assets 目录中的图片处理会在未来的版本中得到支持. 非常酷的功能!

前置参数

Hugo 允许你在文章内容前面添加 yaml, toml 或者 json 格式的前置参数.

注意
不是所有的以下前置参数都必须在你的每篇文章中设置. 只有在文章的参数和你的 网站设置 中的 page 部分不一致时才有必要这么做.

这是一个前置参数例子:

 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
---
title: "我的第一篇文章"
subtitle: ""
date: 2020-03-04T15:58:26+08:00
lastmod: 2020-03-04T15:58:26+08:00
draft: true
author: ""
authorLink: ""
description: ""
license: ""
images: []

tags: []
categories: []
featuredImage: ""
featuredImagePreview: ""
twemoji: false
lightgallery: true
ruby: true
fraction: true
fontawesome: true
linkToMarkdown: true
rssFullText: false

toc:
  enable: true
  auto: true
code:
  copy: true
  # ...
math:
  enable: true
  # ...
mapbox:
  accessToken: ""
  # ...
share:
  enable: true
  # ...
comment:
  enable: true
  # ...
library:
  css:
    # someCSS = "some.css"
    # 位于 "assets/"
    # 或者
    # someCSS = "https://cdn.example.com/some.css"
  js:
    # someJS = "some.js"
    # 位于 "assets/"
    # 或者
    # someJS = "https://cdn.example.com/some.js"
seo:
  images: []
  # ...
---
  • title: 文章标题.

  • subtitle: LoveIt 新增 | 0.2.0 文章副标题.

  • date: 这篇文章创建的日期时间. 它通常是从文章的前置参数中的 date 字段获取的, 但是也可以在 网站配置 中设置.

  • lastmod: 上次修改内容的日期时间.

  • draft: 如果设为 true, 除非 hugo 命令使用了 --buildDrafts/-D 参数, 这篇文章不会被渲染.

  • author: 文章作者.

  • authorLink: 文章作者的链接.

  • description: 文章内容的描述.

  • license: 这篇文章特殊的许可.

  • images: 页面图片, 用于 Open Graph 和 Twitter Cards.

  • tags: 文章的标签.

  • categories: 文章所属的类别.

  • featuredImage: 文章的特色图片.

  • featuredImagePreview: 用在主页预览的文章特色图片.

  • hiddenFromHomePage: 如果设为 true, 这篇文章将不会显示在主页上.

  • hiddenFromSearch: LoveIt 新增 | 0.2.0 如果设为 true, 这篇文章将不会显示在搜索结果中.

  • twemoji: LoveIt 新增 | 0.2.0 如果设为 true, 这篇文章会使用 twemoji.

  • lightgallery: 如果设为 true, 文章中的图片将可以按照画廊形式呈现.

  • ruby: LoveIt 新增 | 0.2.0 如果设为 true, 这篇文章会使用 上标注释扩展语法.

  • fraction: LoveIt 新增 | 0.2.0 如果设为 true, 这篇文章会使用 分数扩展语法.

  • fontawesome: LoveIt 新增 | 0.2.0 如果设为 true, 这篇文章会使用 Font Awesome 扩展语法.

  • linkToMarkdown: 如果设为 true, 内容的页脚将显示指向原始 Markdown 文件的链接.

  • rssFullText: LoveIt 新增 | 0.2.4 如果设为 true, 在 RSS 中将会显示全文内容.

  • toc: LoveIt 更改 | 0.2.9网站配置 中的 params.page.toc 部分相同.

  • code: LoveIt 新增 | 0.2.0网站配置 中的 params.page.code 部分相同.

  • math: LoveIt 更改 | 0.2.0网站配置 中的 params.page.math 部分相同.

  • mapbox: LoveIt 新增 | 0.2.0网站配置 中的 params.page.mapbox 部分相同.

  • share: 和 网站配置 中的 params.page.share 部分相同.

  • comment: LoveIt 更改 | 0.2.0网站配置 中的 params.page.comment 部分相同.

  • library: LoveIt 新增 | 0.2.7网站配置 中的 params.page.library 部分相同.

  • seo: LoveIt 新增 | 0.2.10网站配置 中的 params.page.seo 部分相同.

技巧

LoveIt 新增 | 0.2.10

featuredImagefeaturedImagePreview 支持本地资源引用的完整用法.

如果带有在前置参数中设置了 name: featured-imagename: featured-image-preview 属性的页面资源, 没有必要在设置 featuredImagefeaturedImagePreview:

1
2
3
4
5
resources:
- name: featured-image
  src: featured-image.jpg
- name: featured-image-preview
  src: featured-image-preview.jpg

内容摘要

LoveIt 主题使用内容摘要在主页中显示大致文章信息。Hugo 支持生成文章的摘要.

文章摘要预览 ▲ 文章摘要预览

自动摘要拆分

默认情况下, Hugo 自动将内容的前 70 个单词作为摘要.

你可以通过在 网站配置 中设置 summaryLength 来自定义摘要长度.

如果您要使用 CJK中文/日语/韩语 语言创建内容, 并且想使用 Hugo 的自动摘要拆分功能,请在 网站配置 中将 hasCJKLanguage 设置为 true.

手动摘要拆分

另外, 你也可以添加 <!--more--> 摘要分割符来拆分文章生成摘要.

摘要分隔符之前的内容将用作该文章的摘要.

注意
请小心输入<!--more--> ; 即全部为小写且没有空格.

前置参数摘要

你可能希望摘要不是文章开头的文字. 在这种情况下, 你可以在文章前置参数的 summary 变量中设置单独的摘要.

使用文章描述作为摘要

你可能希望将文章前置参数中的 description 变量的内容作为摘要.

你仍然需要在文章开头添加 <!--more--> 摘要分割符. 将摘要分隔符之前的内容保留为空. 然后 LoveIt 主题会将你的文章描述作为摘要.

摘要选择的优先级顺序

由于可以通过多种方式指定摘要, 因此了解顺序很有用. 如下:

  1. 如果文章中有 <!--more--> 摘要分隔符, 但分隔符之前没有内容, 则使用描述作为摘要.
  2. 如果文章中有 <!--more--> 摘要分隔符, 则将按照手动摘要拆分的方法获得摘要.
  3. 如果文章前置参数中有摘要变量, 那么将以该值作为摘要.
  4. 按照自动摘要拆分方法.
注意
不建议在摘要内容中包含富文本块元素, 这会导致渲染错误. 例如代码块, 图片, 表格等.

Markdown 基本语法

这部分内容在 Markdown 基本语法页面 中介绍.

Markdown 扩展语法

LoveIt 主题提供了一些扩展的语法便于你撰写文章.

Emoji 支持

这部分内容在 Emoji 支持页面 中介绍.

数学公式

LoveIt 基于 $ \KaTeX $ 提供数学公式的支持.

在你的 网站配置 中的 [params.math] 下面设置属性 enable = true, 并在文章的前置参数中设置属性 math: true来启用数学公式的自动渲染.

技巧

公式块

默认的公式块分割符是 $$/$$\\[/\\]:

1
2
3
$$ c = \pm\sqrt{a^2 + b^2} $$

\\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\]

呈现的输出效果如下:

$$ c = \pm\sqrt{a^2 + b^2} $$

\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \]

行内公式

默认的行内公式分割符是 $/$\\(/\\):

1
$ c = \pm\sqrt{a^2 + b^2} $ 和 \\( f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\)

呈现的输出效果如下:

$ c = \pm\sqrt{a^2 + b^2} $ 和 \( f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \)

技巧
你可以在 网站配置 中自定义公式块和行内公式的分割符.

Copy-tex

Copy-tex 是一个 $ \KaTeX $ 的插件.

通过这个扩展, 在选择并复制 $ \KaTeX $ 渲染的公式时, 会将其 $ \LaTeX $ 源代码复制到剪贴板.

在你的 网站配置 中的 [params.math] 下面设置属性 copyTex = true 来启用 Copy-tex.

选择并复制上一节中渲染的公式, 可以发现复制的内容为 LaTeX 源代码.

mhchem

mhchem 是一个 $ \KaTeX $ 的插件.

通过这个扩展, 你可以在文章中轻松编写漂亮的化学方程式.

在你的 网站配置 中的 [params.math] 下面设置属性 mhchem = true 来启用 mhchem.

1
2
3
$$ \ce{CO2 + C -> 2 CO} $$

$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$

呈现的输出效果如下:

$$ \ce{CO2 + C -> 2 CO} $$

$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$

字符注音或者注释

LoveIt 主题支持一种 字符注音或者注释 Markdown 扩展语法:

1
[Hugo]^(一个开源的静态网站生成工具)

呈现的输出效果如下:

Hugo一个开源的静态网站生成工具

分数

LoveIt 新增 | 0.2.0

LoveIt 主题支持一种 分数 Markdown 扩展语法:

1
2
3
[浅色]/[深色]

[99]/[100]

呈现的输出效果如下:

浅色/深色

90/100

Font Awesome

LoveIt 主题使用 Font Awesome 作为图标库. 你同样可以在文章中轻松使用这些图标.

Font Awesome 网站 上获取所需的图标 class.

1
2
3
去露营啦! :(fas fa-campground fa-fw): 很快就回来.

真开心! :(far fa-grin-tears):

呈现的输出效果如下:

去露营啦!  很快就回来.

真开心!

转义字符

在某些特殊情况下 (编写这个主题文档时 ), 你的文章内容会与 Markdown 的基本或者扩展语法冲突, 并且无法避免.

转义字符语法可以帮助你渲染出想要的内容:

1
{?X} -> X

例如, 两个 : 会启用 emoji 语法. 但有时候这不是你想要的结果. 可以像这样使用转义字符语法:

1
{?:}joy:

呈现的输出效果如下:

:joy: 而不是 😂

技巧
这个方法可以间接解决一个还未解决的 Hugo 的 issue.

另一个例子是:

1
[link{?]}(#escape-character)

呈现的输出效果如下:

[link](#escape-character) 而不是 link.