配置 Apollo
Posted on :: documentation

这篇文章由 Apollo 主题作者 Matthias 的文章 Configuring Apollo 翻译而来。

站点配置

Search (build_search_index)

启用或禁用博客的搜索功能。

  • 类型：布尔值
  • 默认值：false
  • 用法：build_search_index = false

启用后，系统将为您的博客生成搜索索引，允许访客搜索特定内容。 此外，导航栏中将显示一个搜索按钮。

请按以下方式配置搜索功能：

build_search_index = true

[search]
include_title = true
include_description = true
include_path = true
include_content = true
index_format = "elasticlunr_json"

Theme Mode (theme)

设置博客的配色方案。

  • 类型：字符串
  • 选项：
    • "light"：始终使用浅色主题
    • "dark"：始终使用深色主题
    • "auto"：自动使用系统主题
    • "toggle"：显示一个按钮，用于在浅色和深色主题之间切换
    • "toggle-auto"：显示一个按钮，用于在浅色、深色和自动（系统默认）主题之间循环切换
  • 默认值："toggle"
  • 用法：theme = "toggle"

菜单

用于定义博客的导航菜单项。

  • 类型：对象数组
  • 默认值：[]
  • 用法：
    menu = [
  { name = "/posts", url = "/posts", weight = 1 },
  { name = "/projects", url = "/projects", weight = 2 },
  { name = "/about", url = "/about", weight = 3 },
  { name = "/tags", url = "/tags", weight = 4 },
]

徽标

定义网站徽标图像文件。

  • 类型：字符串
  • 用法：
    logo = "site_logo.svg"

Socials

定义社交媒体链接。

  • 类型：对象数组
  • 默认值：[]
  • 用法：
    socials = [
  { name = "twitter", url = "https://twitter.com/not_matthias", icon = "twitter" },
  { name = "github", url = "https://github.com/not-matthias/", icon = "github" },
]

如果在配置文件的 [markdown] 部分将 external_links_target_blank 设置为 true，社交媒体链接将在新标签页中打开。

目录 (toc)

启用或禁用文章的目录。

  • 类型：布尔值
  • 默认值：true
  • 用法：toc = true

启用后，系统将为文章生成目录，方便读者浏览较长的文章。

注意：此功能会为您的网站添加额外的 JavaScript 代码。

CDN 使用（use_cdn）

决定是否为资源使用内容分发网络（CDN）。

  • 类型：布尔值
  • 默认值：false
  • 用法：use_cdn = false

当设置为 true 时，主题将尝试从 CDN 加载资源，这可以改善来自不同地理位置的访客的加载速度。

网站图标（favicon）

指定博客网站图标图片的路径。

  • 类型：字符串
  • 默认值："/icon/favicon.png"
  • 用法：favicon = "/icon/favicon.png"

此设置用于指定网站浏览器标签页中显示的小图标。

自定义样式表（stylesheets）

允许您向博客添加自定义样式表。

  • 类型：位于 static 目录中的文件数组
  • 默认值：[]
  • 用法：
    stylesheets = [
  "custom.css",           # static/custom.css
  "/css/another.css"      # static/css/another.css
]

代码美化样式 (fancy_code)

启用代码块的增强样式。

  • 类型：布尔型
  • 默认值：true
  • 用法：fancy_code = true

此选项会添加语言标签和复制按钮。

动态注释 (dynamic_note)

允许在内容中创建可折叠的注释区域。

  • 类型：布尔值
  • 默认值：true
  • 用法：dynamic_note = true

启用后，您可以在博客文章中创建可展开/折叠的笔记板块。

Character Shortcodes

我们支持自定义角色短代码，用于在博客文章中添加对话和互动角色。您可以通过 短代码 使用它们：

{{ /* character(name="character-name", body="Character dialogue text") */ }}

以下是支持的参数：

  • name（可选）：角色的标识符。用于确定样式和外观。
  • body（可选）：角色的对话文本。支持内联短代码。
  • position（可选）：将角色定位在左侧或右侧。取值："left" 或默认值（right）
hooded

这难道不令人惊叹吗？

hooded

是的！而且它真的非常容易使用

hooded

我们甚至可以在代码中使用多行：

fn main() {
  println!("Hey there!");
}

锚点链接

您可以在 _index.md 中添加以下内容来创建锚点链接：

insert_anchor_links = "heading"

分类法排序

您可以通过以下配置对分类法页面进行排序：

[extra.taxonomies]
sort_by = "page_count"         # e.g. name, page_count
reverse = true

sort_by 参数会直接传递给 sort_by 函数：

{% set sort_by = config.extra.taxonomies.sort_by | default(value="name") %}
{% set terms = terms | default(value=[]) | sort(attribute=sort_by) %}

{% if config.extra.taxonomies.reverse | default(value=false) %}
    {% set terms = terms | reverse %}
{% endif %}

{% for term in terms %}
    <li>
        <a href="{{ term.permalink | safe }}">
            {{ term.name }} ({{ term.pages | length }} post{{ term.pages | length | pluralize }})
        </a>
    </li>
{% endfor %}

可能的值包括 TaxonomyTerm 对象 中的任何内容：

name: String;
slug: String;
path: String;
permalink: String;
pages: Array<Page>;
page_count: Number;

示例：

  • name：按名称排序
  • page_count：按页面计数排序

Analytics

启用或禁用分析跟踪：

[extra.analytics]
enabled = false

启用分析功能后，请配置 GoatCounter 或 Umami。

GoatCounter

配置 GoatCounter 分析：

[extra.analytics.goatcounter]
user = "your_user"           # 您的 GoatCounter 用户名
host = "example.com"         # 可选：自定义主机

Umami 分析

配置 Umami 分析：

[extra.analytics.umami]
website_id = "43929cd1-1e83...."                    # 您的 Umami 网站 ID
host_url = "https://stats.mywebsite.com"            # 可选：自定义主机 URL

Fediverse 作者署名

启用 Fediverse 作者署名功能，为 Fediverse 平台添加元标签：

[extra]
fediverse = true
fediverse_creator = "@[email protected]"
  • 类型：布尔型
  • 默认值：false
  • 用法：fediverse = true

启用此选项后，会在您网站的 HTML 头部添加一个 fediverse:creator 元标签，允许 Fediverse 平台将内容归因于您的账户。请将 fediverse_creator 设置为您在 Fediverse 中的用户名，格式为 @user@instance。

页面配置

源代码（repo_view）

您想链接到博客文章的源代码吗？您可以在博客文章的 [extra] 部分中启用 repo_view。

[extra]
repo_view = true
repo_url = "https://github.com/not-matthias/apollo/tree/main/content" # 或者在此处添加仓库

repo_url 可以在 [extra] 部分或您的 config.toml 中设置。

MathJax (mathjax)

启用 MathJax 以渲染数学公式。

  • 类型：布尔型
  • 默认值：false

MathJax 可以全局启用（在每个页面加载）或按页面启用（仅在需要时加载）。

按页面启用：添加到文章的前置元数据中

+++
title = "我的数学笔记"

[extra]
mathjax = true
+++

全局：添加到你的 config.toml 中

[extra]
mathjax = true

当 MathJax 处于活动状态时，内联 $...$ 数学表达式始终处于启用状态。

完整示例请参见 math-symbol.md。

Comments (comment)

用于启用或禁用帖子的评论系统。

  • 类型：布尔值
  • 默认值：false
  • 用法：comment = false

在文章的 [extra] 部分将 comment = true 设置为真后，请将 Giscus 提供的脚本保存至 templates/_giscus_script.html。 启用后，读者即可在您的博客文章下发表评论。此功能需针对每篇单独的文章进行设置，不支持在更高层级进行配置。

配置示例请参见 content/posts/configuration.md：

+++
title = "配置 Apollo"

[extra]
comment = true
+++

可以通过 template/_giscus_script.html 像这样配置 utterances 中的评论：

<script
  src="https://utteranc.es/client.js"
  repo="YOUR_NAME/YOUR_REPO"
  issue-term="pathname"
  theme="github-light"
  crossorigin="anonymous"
  async
></script>

卡片页面

cards.html 模板允许您以卡片格式显示项目列表。这非常适合展示项目，但也适用于任何您希望以视觉上吸引人的方式展示的项目列表。

要创建卡片页面，您需要在内容目录（例如 content/projects）中创建一个 _index.md 文件。建议使用以下前置信息：

+++
title = "Projects"
sort_by = "weight"
template = "cards.html"
[extra]
cards_columns = 3
card_media_height = 200
+++
  • cards_columns：设置确切的列数（2、3、4），或省略以使用默认的 2 列布局
  • card_media_height：以像素为单位控制卡片媒体区域的高度（默认：300）

列表中的每个项目应为同一目录下的独立 Markdown 文件。支持以下前置信息：

  • title：项目的标题。
  • description：项目的简短描述。
  • weight：项目在页面上的显示顺序。
  • local_image：项目缩略图的本地图片路径。更多详情请参阅 本地图片 章节。
  • local_video：项目缩略图的本地视频路径。更多详情请参阅 本地视频 部分。
  • remote_video：用于项目缩略图的远程视频 URL。
  • link_to：卡片应链接到的 URL。

演讲页面

要创建演讲页面，您需要在 content/talks 目录下创建一个 _index.md 文件。建议使用以下前置信息：

+++
title = "Talks"
sort_by = "date"
template = "talks.html"
+++

每场演讲应作为独立的 Markdown 文件保存在 content/talks 目录中。支持以下前置信息：

  • title：演讲的标题。
  • description：演讲的简短描述。
  • date：演讲的日期（显示为日历图标）。
  • local_image：用于项目缩略图的本地图片路径。更多详情请参阅 本地图片 部分。
  • video：包含演讲视频 link 和 thumbnail 的映射对象。
  • organizer：包含活动组织者 name 和 link 的映射对象（显示为位置图标）。
  • slides：演示文稿幻灯片的 URL。
  • code：源代码的 URL。

Local Image

local_image 前置参数允许您指定本地图片的路径，该图片将用作页面的缩略图。这对于社交媒体预览以及其他需要代表性图片的场合特别有用。

local_image 的路径解析规则如下：

  • 若路径以 / 开头，则视为从 content 目录开始的绝对路径。例如，local_image = "/projects/project-1.jpg" 将解析为 content/projects/project-1.jpg。
  • 若路径不以 / 开头，则视为相对路径。主题会将 section.path 附加到 local_image 路径的前面。例如，如果您所在的页面路径为 content/posts/my-post/index.md，且设置了 local_image = "thumbnail.png"，主题将查找位于 posts/my-post/thumbnail.png 的图片。

Local Video

local_video 前置元数据参数允许您指定本地视频文件的路径，该视频将作为页面的缩略图显示。这对于展示包含动态内容的项目特别有用。

local_video 的路径解析方式与 local_image 相同：

  • 如果路径以 / 开头，则将其视为从 content 目录开始的绝对路径。例如，local_video = "/projects/demo.mp4" 将解析为 content/projects/demo.mp4。
  • 如果路径不以 / 开头，则将其视为相对路径。主题会将 section.path 附加到 local_video 路径的前面。例如，若您当前所在页面位于 content/projects/my-project/index.md，且设置了 local_video = "demo.webm"，主题将从 projects/my-project/demo.webm 路径查找视频。

远程视频

remote_video 前置元数据参数允许您指定远程视频文件的 URL，该视频将作为页面的缩略图显示。

使用示例：

[extra]
remote_video = "https://example.com/videos/demo.mp4"

浏览器会自动检测视频格式，因此您无需担心指定 MIME 类型。

Table of Contents