FixIt
FixIt

主题文档 - 内容

Lruihao Lruihao 收录于  文档
    约 3791 字   预计阅读 8 分钟   - 次阅读  
/zh-cn/theme-documentation-content/featured-image.jpg

了解如何在 FixIt 主题中快速，直观地创建和组织内容。

1 内容组织

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

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

FixIt 0.2.10 | 新增

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

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

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

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

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

2 前置参数

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

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

  • title: 文章标题

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

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

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

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

  • author: 文章作者

  • authorLink: 文章作者的链接

  • authorEmail: FixIt 0.2.14 | 新增 文章作者的邮箱

  • description: 文章内容的描述

  • keywords: 文章内容的关键词

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

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

  • tags: 文章的标签

  • categories: 文章所属的类别

  • featuredImage: 文章的特色图片

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

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

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

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

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

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

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

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

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

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

  • pageStyle: FixIt 0.2.13 | 新增 页面样式，详见 页面宽度

  • gravatarForce: FixIt 0.2.14 | 新增 强制使用 Gravatar 作为作者头像

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

  • expirationReminder: FixIt 0.2.13 | 新增 和 网站配置 中的 params.page.expirationReminder 部分相同

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

  • edit: FixIt 0.2.14 | 新增 和 网站配置 中的 params.page.edit 部分相同

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

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

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

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

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

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

  • type: 页面渲染模板，详见 页面模板

  • menu: 详见 添加内容到菜单

  • password: FixIt 0.2.15 | 新增 加密页面内容的密码，详见 主题文档 - 内容加密

  • message: FixIt 0.2.15 | 新增 加密提示信息，详见 主题文档 - 内容加密

  • repost: FixIt 0.2.15 | 新增 和 网站配置 中的 params.page.repost 部分相同

技巧

FixIt 0.2.10 | 新增

featuredImage 和 featuredImagePreview 支持 本地资源引用 的完整用法。

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

1
2
3
4
5

resources:
- name: featured-image
  src: featured-image.jpg
- name: featured-image-preview
  src: featured-image-preview.jpg

FixIt 0.2.12 | 新增

FixIt 主题内嵌了一些 原型，在使用以下命令创建新内容时生效，会自动带入常用的前置参数：

1
2

hugo new posts/foo.md
hugo new --kind post-bundle posts/bar/

这是一个前置参数例子：

 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

---
title: "我的第一篇文章"
subtitle: ""
date: 2020-03-04T15:58:26+08:00
lastmod: 2020-03-04T15:58:26+08:00
draft: true
author: ""
authorLink: ""
authorEmail: ""
description: ""
keywords: ""
license: ""
images: []

tags: []
categories: []
featuredImage: ""
featuredImagePreview: ""

hiddenFromHomePage: false
hiddenFromSearch: false
twemoji: false
lightgallery: true
ruby: true
fraction: true
fontawesome: true
linkToMarkdown: true
rssFullText: false
pageStyle: "normal"
gravatarForce: false

toc:
  enable: true
  auto: true
expirationReminder:
  enable: false
  # ...
code:
  copy: true
  # ...
edit:
  enable: false
  # ...
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: []
  # ...
---

3 页面模板

一般情况，你不需要设置 type 参数，因为 Hugo 和 FixIt 会帮你选择。但是 FixIt 主题提供了一些特殊的模板给用户使用。

友情链接

FixIt 0.2.12 | 新增

在前置参数中设置 type: "friends"，并在 yourSite/data/ 目录下创建 friends.yml，其内容格式如下：

1
2
3
4
5

# 朋友/站点信息例子
- nickname: 朋友名字
  avatar: 朋友头像
  url: 站点链接
  description: 对朋友或其站点的说明
技巧

你可以使用以下命令快速创建友情链接页面：

1

hugo new friends/index.md

离线页面

FixIt 0.2.12 | 新增 详见 PWA 支持

在前置参数中设置 type: "offline"，并在 config.toml 中开启 enablePWA：

1
2
3
4

[params]
  # enable PWA
  # 开启 PWA 支持
  enablePWA = true
技巧

你可以使用以下命令快速创建离线页面：

1

hugo new offline/index.md

4 内容摘要

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

/zh-cn/theme-documentation-content/summary.zh-cn.png
文章摘要预览

自动摘要拆分

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

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

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

手动摘要拆分

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

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

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

前置参数摘要

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

使用文章描述作为摘要

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

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

摘要选择的优先级顺序

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

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

5 Markdown 基本语法

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

6 Markdown 扩展语法

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

Emoji 支持

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

数学公式

FixIt 基于 $ \KaTeX $ 提供数学公式的支持。

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

技巧
有一份 $ \KaTeX $ 中支持的 $ \TeX $ 函数 清单。

公式块

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

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-} $$

字符注音或者注释

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

1

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

呈现的输出效果如下：

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

分数

FixIt 0.2.0 | 新增

FixIt 主题支持一种 分数 Markdown 扩展语法：

1
2
3

[浅色]/[深色]

[99]/[100]

呈现的输出效果如下：

浅色/深色

90/100

Font Awesome

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

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

1
2
3

去露营啦！:(fa-solid fa-campground fa-fw): 很快就回来。

真开心！:(fa-regular fa-grin-tears):

呈现的输出效果如下：

去露营啦！ 很快就回来。

真开心！

转义字符

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

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

1

{?X} -> X

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

1

{?:}joy:

呈现的输出效果如下：

:joy: 而不是 😂

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

另一个例子是：

1

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

呈现的输出效果如下：

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

感谢
本文档中 v0.2.10 版本之前的内容，感谢原作者 Dillon 编写修订。
更新于 2022-07-23  a089d1a
CC BY-NC 4.0
阅读原始文档编辑此页
 内容, Markdown
返回 | 主页