主题文档 - 内容

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

1 内容组织

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

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

2 作者配置

我们鼓励你在 mysite/data/authors 下创建你的作者个人资料 author_name.toml. 在你的资料中, 你可以添加个人链接, 邮箱, 以及支持 i18n 的姓名.

以下是 Alice.toml 的示例:

link = "https://alice.example.com"
email = "alice@example.com"
name = "Alice"
[zh-cn]
    name = "爱丽丝"

在创建作者个人资料后, 您可以在文章的前置参数中指定您的姓名. 之后, 该文章将自动著上你的名字, 并可以根据作者进行分类.

---
authors: [Alice]
---

您也可以为一篇文章注明多个作者.

---
authors: [Alice, Bob, Catherine]
---

3 前置参数

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

这是一个前置参数例子:

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

tags: []
categories: []
series: []
series_weight: 1
seriesNavigation: true
featuredImage: ""
featuredImagePreview: ""

hiddenFromHomePage: false
hiddenFromSearch: false
twemoji: false
lightgallery: true
ruby: true
fraction: true
linkToMarkdown: true
linkToSource: false
linkToEdit: false
linkToReport: false
rssFullText: false
license: ''

toc:
  enable: true
  auto: true
code:
  copy: true
  # ...
table:
  sort: 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: []
  # ...
outdatedArticleReminder:
  enable: false
  # ...
sponsor:
  enable: false
  # ...
related:
  enable: false
  count: 5
---

• title: 文章标题.

• subtitle: 文章副标题.

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

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

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

• authors: 文章作者.

• description: 文章内容的描述.

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

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

• tags: 文章的标签.

• categories: 文章所属的类别.

• series: 文章所属的系列.

• series_weight: 自定义文章在系列中的位置.

• seriesNavigation: 是否使用系列导航.

• featuredImage: 文章的特色图片.

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

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

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

• twemoji: 如果设为 true, 这篇文章会使用 twemoji.

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

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

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

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

• linkToSource: 如果设为 false, 则关闭页脚 view source 的链接. 你可以将其设置为一个指向文章原始文件的链接. 使用魔法变量 {path} 来获取文章的相对路径, 这篇文章的 {path} 是 posts/theme-documentation-content/index.en.md.

• linkToEdit: 如果设为 false, 则关闭页脚 编辑此页 的链接. 你可以将其设置为一个用于编辑这个页面的链接. 使用魔法变量 {path} 来获取这篇文章的相对路径, 这篇文章的 {path} 是 posts/theme-documentation-content/index.zh-cn.md.

• linkToReport: 如果设为 false, 则关闭页脚 报告问题 的链接. 你可以将其设置为一个用于报告此页面中错误的链接. 使用魔法变量 {path} 来获取文章的相对路径, 这篇文章的 {path} 是 posts/theme-documentation-content/index.en.md, 使用 {title} 来获取文章的标题, 这篇文章的 {title} 为 Theme Documentation - Content, 使用 {url} 来获取文章的链接, 这篇文章的 {url} 为 https://hugodoit.pages.dev/theme-documentation-content/.

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

• enableLastMod: 如果设为 true，在文章的顶部将会显示上次修改内容的日期时间.

• enableWordCount: 如果设为 true, 在文章的顶部将会显示文章的字数.

• enableReadingTime: 如果设为 true, 在文章的顶部将会显示文章的阅读时间.

• license: 许可协议信息 (支持 HTML 格式).

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

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

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

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

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

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

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

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

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

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

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

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

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

4 内容摘要

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

4.1 自动摘要拆分

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

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

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

4.2 手动摘要拆分

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

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

4.3 前置参数摘要

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

4.4 使用文章描述作为摘要

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

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

4.5 摘要选择的优先级顺序

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

1. 如果文章中有 <!--more--> 摘要分隔符, 但分隔符之前没有内容, 则使用描述作为摘要.
2. 如果文章中有 <!--more--> 摘要分隔符, 则将按照手动摘要拆分的方法获得摘要.
3. 如果文章前置参数中有摘要变量, 那么将以该值作为摘要.
4. 按照自动摘要拆分方法.

5 Markdown 基本语法

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

6 Markdown 扩展语法

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

6.1 Emoji 支持

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

6.2 数学公式

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

在你的 网站配置 中添加如下设置来启用数学公式支持：

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true
        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['\[', '\]']]
          inline = [['\(', '\)']]
[params]
  [page]
    [page.math]
      enable = true
      blockLeftDelimiter = '\['
      blockRightDelimiter = '\]'
      inlineLeftDelimiter = '\('
      inlineRightDelimiter = '\)'
      copyTex = true
      mhchem = true

6.2.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 ]

6.2.2 行内公式

默认的行内公式分割符是 \( \)：

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

呈现的输出效果如下:

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

6.2.3 Copy-tex

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

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

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

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

6.2.4 mhchem

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

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

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

\[ \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-} ]

6.3 字符注音或者注释

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

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

呈现的输出效果如下:

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

6.4 分数

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

[浅色]/[深色]

[99]/[100]

呈现的输出效果如下:

^浅色/_深色

⁹⁰/₁₀₀

6.5 Blockquotes

DoIt 支持 GitHub 风格的引用块：

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

呈现的输出效果如下：