forked from drowl87/hextra_mirror
docs: update zh-cn translations
This commit is contained in:
Xin
parent
594b1f190c
commit
9632c4d05a
@ -7,29 +7,29 @@ title: 介绍
|
|||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
## Hextra 是什么？
|
## 什么是 Hextra？
|
||||||
|
|
||||||
Hextra 是一款现代、快速且内置丰富功能的 [Hugo][hugo] 主题，它是用 [Tailwind CSS][tailwind-css] 构建的。该主题旨在创建美观的文档、博客和网站，提供了开箱即用的功能和灵活性以满足各种需求。
|
Hextra 是一个现代、快速且功能齐全的 [Hugo][hugo] 主题，基于 [Tailwind CSS][tailwind-css] 构建。专为构建美观的文档、博客和网站而设计，它提供了开箱即用的功能和灵活性，以满足各种需求。
|
||||||
|
|
||||||
## 功能特点
|
## 特性
|
||||||
|
|
||||||
- **优美的设计** - 受到 Nextra 的启发，Hextra 利用 Tailwind CSS 提供了一种现代设计，使您的网站看起来出色。
|
- **精美设计** - 灵感源自 Nextra，Hextra 利用 Tailwind CSS 提供现代设计，使您的网站脱颖而出。
|
||||||
- **响应式布局和深色模式** - 无论是在移动设备、平板还是桌面上，都表现出色。同时支持深色模式以适应各种光线条件。
|
- **响应式布局与暗黑模式** - 在所有设备上都能完美呈现，从手机、平板到桌面。暗黑模式也得到支持，以适应不同的光照条件。
|
||||||
- **快速和轻量级** - 由 Hugo 驱动，一个轻量级且超快的静态网站生成器，封装在一个单一的二进制文件中，Hextra 保持其占用极小。使用它不需要 Javascript 或 Node.js。
|
- **快速且轻量** - 由 Hugo 驱动，这是一个闪电般快速的静态网站生成器，仅需一个二进制文件，Hextra 保持其占用空间最小。无需 JavaScript 或 Node.js 即可使用。
|
||||||
- **全文搜索** - 内置的离线全文搜索由 FlexSearch 提供支持，无需额外配置。
|
- **全文搜索** - 内置离线全文搜索，由 FlexSearch 提供支持，无需额外配置。
|
||||||
- **功能全面** - 支持 Markdown、语法高亮、LaTeX 数学公式、图表以及 Shortcodes 元素以增强您的内容。目录、面包屑、分页、侧边栏导航等都会自动生成。
|
- **功能齐全** - Markdown、语法高亮、LaTeX 数学公式、图表和 Shortcodes 元素，丰富您的内容。目录、面包屑导航、分页、侧边栏导航等均自动生成。
|
||||||
- **多语言和 SEO 支持** - Hugo 的多语言模式轻松支持多语言网站。对于 SEO 标签、Open Graph 和 Twitter 卡片，也提供了开箱即用的支持。
|
- **多语言与 SEO 就绪** - 通过 Hugo 的多语言模式轻松创建多语言网站。开箱即用支持 SEO 标签、Open Graph 和 Twitter Cards。
|
||||||
|
|
||||||
## 有问题或反馈？
|
## 有问题或反馈？
|
||||||
|
|
||||||
{{< callout emoji="❓" >}}
|
{{< callout emoji="❓" >}}
|
||||||
Hextra 仍在积极开发中。
|
Hextra 仍在积极开发中。
|
||||||
有问题或反馈？请随时[提出问题](https://github.com/imfing/hextra/issues)！
|
有问题或反馈？欢迎[提交问题](https://github.com/imfing/hextra/issues)！
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
## 接下来
|
## 下一步
|
||||||
|
|
||||||
直接进入以下部分开始：
|
立即深入以下部分，开始使用：
|
||||||
|
|
||||||
{{< cards >}}
|
{{< cards >}}
|
||||||
{{< card link="getting-started" title="入门指南" icon="document-text" subtitle="学习如何使用 Hextra 创建网站" >}}
|
{{< card link="getting-started" title="入门指南" icon="document-text" subtitle="学习如何使用 Hextra 创建网站" >}}
|
||||||
@ -38,3 +38,4 @@ Hextra 是一款现代、快速且内置丰富功能的 [Hugo][hugo] 主题，
|
|||||||
[hugo]: https://gohugo.io/
|
[hugo]: https://gohugo.io/
|
||||||
[flex-search]: https://github.com/nextapps-de/flexsearch
|
[flex-search]: https://github.com/nextapps-de/flexsearch
|
||||||
[tailwind-css]: https://tailwindcss.com/
|
[tailwind-css]: https://tailwindcss.com/
|
||||||
|
```
|
||||||
@ -1,15 +1,16 @@
|
|||||||
---
|
---
|
||||||
linkTitle: 高级配置
|
linkTitle: 高级
|
||||||
title: 高级配置
|
title: 高级主题
|
||||||
prev: /docs/guide/shortcodes/tabs
|
prev: /docs/guide/shortcodes/tabs
|
||||||
next: /docs/advanced/multi-language
|
next: /docs/advanced/multi-language
|
||||||
---
|
---
|
||||||
|
|
||||||
此部分提供了 Hextra 的一些高级配置。
|
本节涵盖了一些主题的高级内容。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
{{< cards >}}
|
{{< cards >}}
|
||||||
{{< card link="multi-language" title="多语言" icon="translate" >}}
|
{{< card link="multi-language" title="多语言" icon="translate" >}}
|
||||||
{{< card link="customization" title="定制化" icon="pencil" >}}
|
{{< card link="customization" title="自定义" icon="pencil" >}}
|
||||||
{{< /cards >}}
|
{{< card link="comments" title="评论系统" icon="chat-alt" >}}
|
||||||
|
{{< /cards >}}
|
||||||
@ -1,18 +1,18 @@
|
|||||||
---
|
---
|
||||||
title: 评论系统
|
title: 评论系统
|
||||||
linkTitle: Comments
|
linkTitle: 评论
|
||||||
---
|
---
|
||||||
|
|
||||||
Hextra 支持在你的网站中添加评论系统。
|
Hextra 支持为您的网站添加评论系统。
|
||||||
目前已经支持 [giscus](https://giscus.app/).
|
目前支持 [giscus](https://giscus.app/)。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
## giscus
|
## giscus
|
||||||
|
|
||||||
[giscus](https://giscus.app/) 是由 [GitHub Discussions](https://docs.github.com/en/discussions)驱动的评论系统。Giscus 免费并且开源。
|
[giscus](https://giscus.app/) 是一个由 [GitHub Discussions](https://docs.github.com/en/discussions) 提供支持的评论系统。它是免费且开源的。
|
||||||
|
|
||||||
如需启用 Giscus, 你需要在配置文件中添加以下内容：
|
要启用 giscus，您需要在网站配置文件中添加以下内容：
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
params:
|
params:
|
||||||
@ -21,19 +21,19 @@ params:
|
|||||||
type: giscus
|
type: giscus
|
||||||
|
|
||||||
giscus:
|
giscus:
|
||||||
repo: <repository>
|
repo: <仓库>
|
||||||
repoId: <repository ID>
|
repoId: <仓库 ID>
|
||||||
category: <category>
|
category: <分类>
|
||||||
categoryId: <category ID>
|
categoryId: <分类 ID>
|
||||||
```
|
```
|
||||||
|
|
||||||
Giscus 配置可以参考 [giscus.app](https://giscus.app/)，还可以在那里找到更多详细信息。
|
giscus 的配置可以从 [giscus.app](https://giscus.app/) 网站生成。更多详细信息也可以在那里找到。
|
||||||
|
|
||||||
可以在 front matter 中启用或禁用特定页面的评论：
|
可以在页面的 front matter 中为特定页面启用或禁用评论：
|
||||||
|
|
||||||
```yaml {filename="content/docs/about.md"}
|
```yaml {filename="content/docs/about.md"}
|
||||||
---
|
---
|
||||||
title: About
|
title: 关于
|
||||||
comments: true
|
comments: true
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
@ -3,14 +3,18 @@ title: 自定义 Hextra
|
|||||||
linkTitle: 自定义
|
linkTitle: 自定义
|
||||||
---
|
---
|
||||||
|
|
||||||
Hextra 在 `hugo.yaml` 中提供了一些自定义选项来配置主题。
|
Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，用于配置主题。
|
||||||
本页介绍了可用选项以及如何进一步自定义主题。
|
本页描述了可用的选项以及如何进一步自定义主题。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
## 自定义 CSS
|
## 自定义 CSS
|
||||||
|
|
||||||
要添加自定义 CSS，我们需要在站点中创建一个文件 `assets/css/custom.css`。Hextra 将自动加载该文件，比如自定义字体：
|
要添加自定义 CSS，我们需要在站点中创建一个文件 `assets/css/custom.css`。Hextra 会自动加载此文件。
|
||||||
|
|
||||||
|
### 字体
|
||||||
|
|
||||||
|
内容的字体可以通过以下方式自定义：
|
||||||
|
|
||||||
```css {filename="assets/css/custom.css"}
|
```css {filename="assets/css/custom.css"}
|
||||||
.content {
|
.content {
|
||||||
@ -18,41 +22,190 @@ Hextra 在 `hugo.yaml` 中提供了一些自定义选项来配置主题。
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 主题色
|
### 内联代码元素
|
||||||
|
|
||||||
主题色可以通过设置 `--primary-hue` 变量来自定义：
|
与 `其他文本` 混合的文本颜色可以通过以下方式自定义：
|
||||||
|
|
||||||
|
```css {filename="assets/css/custom.css"}
|
||||||
|
.content code:not(.code-block code) {
|
||||||
|
color: #c97c2e;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 主色调
|
||||||
|
|
||||||
|
主题的主色调可以通过设置 `--primary-hue`、`--primary-saturation` 和 `--primary-lightness` 变量来自定义：
|
||||||
|
|
||||||
```css {filename="assets/css/custom.css"}
|
```css {filename="assets/css/custom.css"}
|
||||||
:root {
|
:root {
|
||||||
--primary-hue: 100deg;
|
--primary-hue: 100deg;
|
||||||
|
--primary-saturation: 90%;
|
||||||
|
--primary-lightness: 50%;
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 代码高亮
|
### 进一步的主题自定义
|
||||||
|
|
||||||
代码高亮风格的详细信息可在 [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html) 中找到。可以使用以下命令生成样式表：
|
可以通过覆盖暴露的 CSS 类来进一步自定义主题。以下是一个自定义页脚元素的示例：
|
||||||
|
|
||||||
|
```css {filename="assets/css/custom.css"}
|
||||||
|
.hextra-footer {
|
||||||
|
/* 样式将应用于页脚元素 */
|
||||||
|
}
|
||||||
|
|
||||||
|
.hextra-footer:is(html[class~="dark"] *) {
|
||||||
|
/* 样式将应用于暗模式下的页脚元素 */
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
以下类可用于自定义主题的各个部分。
|
||||||
|
|
||||||
|
#### 通用
|
||||||
|
|
||||||
|
- `hextra-scrollbar` - 滚动条元素
|
||||||
|
- `content` - 页面内容容器
|
||||||
|
|
||||||
|
#### 短代码
|
||||||
|
|
||||||
|
##### 徽章
|
||||||
|
|
||||||
|
- `hextra-badge` - 徽章元素
|
||||||
|
|
||||||
|
##### 卡片
|
||||||
|
|
||||||
|
- `hextra-card` - 卡片元素
|
||||||
|
- `hextra-card-image` - 卡片图片元素
|
||||||
|
- `hextra-card-icon` - 卡片图标元素
|
||||||
|
- `hextra-card-subtitle` - 卡片副标题元素
|
||||||
|
|
||||||
|
##### 卡片组
|
||||||
|
|
||||||
|
- `hextra-cards` - 卡片网格容器
|
||||||
|
|
||||||
|
##### Jupyter Notebook
|
||||||
|
|
||||||
|
- `hextra-jupyter-code-cell` - Jupyter 代码单元容器
|
||||||
|
- `hextra-jupyter-code-cell-outputs-container` - Jupyter 代码单元输出容器
|
||||||
|
- `hextra-jupyter-code-cell-outputs` - Jupyter 代码单元输出 div 元素
|
||||||
|
|
||||||
|
##### PDF
|
||||||
|
|
||||||
|
- `hextra-pdf` - PDF 容器元素
|
||||||
|
|
||||||
|
##### 步骤
|
||||||
|
|
||||||
|
- `steps` - 步骤容器
|
||||||
|
|
||||||
|
##### 标签页
|
||||||
|
|
||||||
|
- `hextra-tabs-panel` - 标签页面板容器
|
||||||
|
- `hextra-tabs-toggle` - 标签页切换按钮
|
||||||
|
|
||||||
|
##### 文件树
|
||||||
|
|
||||||
|
- `hextra-filetree` - 文件树容器
|
||||||
|
|
||||||
|
##### 文件夹
|
||||||
|
|
||||||
|
- `hextra-filetree-folder` - 文件树文件夹容器
|
||||||
|
|
||||||
|
#### 导航栏
|
||||||
|
|
||||||
|
- `nav-container` - 导航栏容器
|
||||||
|
- `nav-container-blur` - 导航栏模糊元素
|
||||||
|
- `hamburger-menu` - 汉堡菜单按钮
|
||||||
|
|
||||||
|
#### 页脚
|
||||||
|
|
||||||
|
- `hextra-footer` - 页脚元素
|
||||||
|
- `hextra-custom-footer` - 自定义页脚部分容器
|
||||||
|
|
||||||
|
#### 搜索
|
||||||
|
|
||||||
|
- `search-wrapper` - 搜索包装容器
|
||||||
|
- `search-input` - 搜索输入元素
|
||||||
|
- `search-results` - 搜索结果列表容器
|
||||||
|
|
||||||
|
#### 目录
|
||||||
|
|
||||||
|
- `hextra-toc` - 目录容器
|
||||||
|
|
||||||
|
#### 侧边栏
|
||||||
|
|
||||||
|
- `mobile-menu-overlay` - 移动菜单的覆盖元素
|
||||||
|
- `sidebar-container` - 侧边栏容器
|
||||||
|
- `sidebar-active-item` - 侧边栏中的活动项
|
||||||
|
|
||||||
|
#### 语言切换器
|
||||||
|
|
||||||
|
- `language-switcher` - 语言切换按钮
|
||||||
|
- `language-options` - 语言选项容器
|
||||||
|
|
||||||
|
#### 主题切换
|
||||||
|
|
||||||
|
- `theme-toggle` - 主题切换按钮
|
||||||
|
|
||||||
|
#### 代码复制按钮
|
||||||
|
|
||||||
|
- `hextra-code-copy-btn-container` - 代码复制按钮容器
|
||||||
|
- `hextra-code-copy-btn` - 代码复制按钮
|
||||||
|
|
||||||
|
#### 代码块
|
||||||
|
|
||||||
|
- `hextra-code-block` - 代码块容器
|
||||||
|
|
||||||
|
#### 功能卡片
|
||||||
|
|
||||||
|
- `hextra-feature-card` - 功能卡片链接元素
|
||||||
|
|
||||||
|
#### 功能网格
|
||||||
|
|
||||||
|
- `hextra-feature-grid` - 功能网格容器
|
||||||
|
|
||||||
|
#### 面包屑导航
|
||||||
|
|
||||||
|
面包屑导航没有特定的类。
|
||||||
|
|
||||||
|
### 语法高亮
|
||||||
|
|
||||||
|
可用的语法高亮主题列表可在 [Chroma 样式库](https://xyproto.github.io/splash/docs/all.html) 中找到。可以使用以下命令生成样式表：
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
hugo gen chromastyles --style=github
|
hugo gen chromastyles --style=github
|
||||||
```
|
```
|
||||||
|
|
||||||
可将生成的样式添加到自定义 CSS 文件中以覆盖默认代码高亮样式。
|
要覆盖默认的语法高亮主题，可以将生成的样式添加到自定义 CSS 文件中。
|
||||||
|
|
||||||
## 自定义 Script
|
## 自定义脚本
|
||||||
|
|
||||||
你可以添加以下文件以自定义 `script` 添加到每页的 `head` 最后：
|
你可以通过添加以下文件在每个页面的 head 末尾添加自定义脚本：
|
||||||
|
|
||||||
```
|
```
|
||||||
layouts/partials/custom/head-end.html
|
layouts/partials/custom/head-end.html
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## 自定义页脚额外部分
|
||||||
|
|
||||||
|
你可以通过在站点中创建文件 `layouts/partials/custom/footer.html` 来在页脚中添加额外部分。
|
||||||
|
|
||||||
|
```html {filename="layouts/partials/custom/footer.html"}
|
||||||
|
<!-- 你的页脚元素在这里 -->
|
||||||
|
```
|
||||||
|
|
||||||
|
添加的部分将出现在页脚的版权部分之前。
|
||||||
|
你可以使用 [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) 和 [Hugo 模板语法](https://gohugo.io/templates/) 来添加自己的内容。
|
||||||
|
|
||||||
|
页脚部分可用的 Hugo 变量有：`.switchesVisible` 和 `.copyrightVisible`。
|
||||||
|
|
||||||
## 自定义布局
|
## 自定义布局
|
||||||
|
|
||||||
可以在站点的 `layouts` 目录中创建同名文件来覆盖主题的默认布局。
|
可以通过在站点的 `layouts` 目录中创建同名文件来覆盖主题的布局。
|
||||||
例如，要覆盖文档的 `single.html` 布局，在站点中创建文件 `layouts/docs/single.html`。
|
例如，要覆盖文档的 `single.html` 布局，可以在站点中创建文件 `layouts/docs/single.html`。
|
||||||
|
|
||||||
如需或许更多信息，转至 [Hugo Templates](https://gohugo.io/templates/)。
|
更多信息，请参阅 [Hugo 模板文档][hugo-template-docs]。
|
||||||
|
|
||||||
## 进一步定制 Hextra
|
## 进一步自定义
|
||||||
|
|
||||||
没有找到你想修改的内容？在 GitHub 上[创建 Discussion](https://github.com/imfing/hextra/discussions) 或为 Hextra 贡献你的智慧！
|
没有找到你想要的？欢迎 [发起讨论](https://github.com/imfing/hextra/discussions) 或为主题做出贡献！
|
||||||
|
|
||||||
|
[hugo-template-docs]: https://gohugo.io/templates/
|
||||||
@ -1,16 +1,16 @@
|
|||||||
---
|
---
|
||||||
title: "多语言"
|
title: "多语言支持"
|
||||||
weight: 1
|
weight: 1
|
||||||
prev: /docs/advanced
|
prev: /docs/advanced
|
||||||
---
|
---
|
||||||
|
|
||||||
Hextra 支持使用 Hugo 的[多语言模式](https://gohugo.io/content-management/multilingual/) 创建多语言的网站。
|
Hextra 支持使用 Hugo 的[多语言模式](https://gohugo.io/content-management/multilingual/)创建多语言网站。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
## 启用多语言支持
|
## 启用多语言
|
||||||
|
|
||||||
为了使我们的网站支持多语言，我们需要告诉 Hugo 需要支持的语言。 在站点配置文件中添加：
|
要使我们的网站支持多语言，我们需要告诉 Hugo 支持的语言。我们需要在站点配置文件中添加：
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
defaultContentLanguage: en
|
defaultContentLanguage: en
|
||||||
@ -26,9 +26,9 @@ languages:
|
|||||||
weight: 3
|
weight: 3
|
||||||
```
|
```
|
||||||
|
|
||||||
## 按文件名管理翻译
|
## 通过文件名管理翻译
|
||||||
|
|
||||||
Hugo 支持按文件名管理翻译。例如，如果我们有一个英文文件 `content/docs/_index.md`，我们可以创建一个翻译为法语的文件 `content/docs/_index.fr.md`。
|
Hugo 支持通过文件名管理翻译。例如，如果我们有一个英文文件 `content/docs/_index.md`，我们可以创建一个文件 `content/docs/_index.fr.md` 作为法语翻译。
|
||||||
|
|
||||||
{{< filetree/container >}}
|
{{< filetree/container >}}
|
||||||
{{< filetree/folder name="content" >}}
|
{{< filetree/folder name="content" >}}
|
||||||
@ -40,7 +40,7 @@ Hugo 支持按文件名管理翻译。例如，如果我们有一个英文文件
|
|||||||
{{< /filetree/folder >}}
|
{{< /filetree/folder >}}
|
||||||
{{< /filetree/container >}}
|
{{< /filetree/container >}}
|
||||||
|
|
||||||
注意：Hugo 还支持[按内容目录管理翻译](https://gohugo.io/content-management/multilingual/#translation-by-content-directory)。
|
注意：Hugo 还支持[通过内容目录进行翻译](https://gohugo.io/content-management/multilingual/#translation-by-content-directory)。
|
||||||
|
|
||||||
## 翻译菜单项
|
## 翻译菜单项
|
||||||
|
|
||||||
@ -59,16 +59,25 @@ menu:
|
|||||||
weight: 2
|
weight: 2
|
||||||
```
|
```
|
||||||
|
|
||||||
|
并在相应的 i18n 文件中进行翻译：
|
||||||
|
|
||||||
|
```yaml {filename="i18n/fr.yaml"}
|
||||||
|
documentation: Documentation
|
||||||
|
blog: Blog
|
||||||
|
```
|
||||||
|
|
||||||
## 翻译字符串
|
## 翻译字符串
|
||||||
|
|
||||||
要翻译其他地方的字符串，我们需要将翻译添加到相应的 `i18n` 文件中：
|
要翻译其他地方的字符串，我们需要将翻译添加到相应的 i18n 文件中：
|
||||||
|
|
||||||
```yaml {filename="i18n/fr.yaml"}
|
```yaml {filename="i18n/fr.yaml"}
|
||||||
readMore: Lire la suite
|
readMore: Lire la suite
|
||||||
```
|
```
|
||||||
|
|
||||||
## 更多参考
|
主题中使用的字符串列表可以在 `i18n/en.yaml` 文件中找到。
|
||||||
|
|
||||||
- [Hugo Multilingual Mode](https://gohugo.io/content-management/multilingual/)
|
## 了解更多
|
||||||
- [Hugo Multilingual Part 1: Content translation](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
|
|
||||||
- [Hugo Multilingual Part 2: Strings localization](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-2-i18n-string-localization/)
|
- [Hugo 多语言模式](https://gohugo.io/content-management/multilingual/)
|
||||||
|
- [Hugo 多语言第一部分：内容翻译](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
|
||||||
|
- [Hugo 多语言第二部分：字符串本地化](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-2-i18n-string-localization/)
|
||||||
@ -1,49 +1,63 @@
|
|||||||
---
|
---
|
||||||
title: 快速开始
|
title: 入门指南
|
||||||
weight: 1
|
weight: 1
|
||||||
next: /docs/guide
|
next: /docs/guide
|
||||||
prev: /docs
|
prev: /docs
|
||||||
---
|
---
|
||||||
|
|
||||||
## 使用模板快速开始
|
## 从模板快速开始
|
||||||
|
|
||||||
{{< icon "github" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)
|
{{< icon "github" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)
|
||||||
|
|
||||||
通过使用上面的模板仓库，您将能够快速地开始。
|
您可以通过使用上述模板仓库快速入门。
|
||||||
|
|
||||||
<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500">
|
<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500">
|
||||||
|
|
||||||
我们提供了一个 [GitHub Actions 工作流](https://docs.github.com/cn/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)，它可以帮助您自动构建并部署您的网站到 GitHub Pages，并免费托管。
|
我们提供了一个 [GitHub Actions 工作流](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)，可以帮助自动构建并将您的站点部署到 GitHub Pages，并免费托管。
|
||||||
|
更多选项，请查看 [部署站点](../guide/deploy-site)。
|
||||||
|
|
||||||
[🌐 演示 ↗](https://imfing.github.io/hextra-starter-template/)
|
[🌐 演示 ↗](https://imfing.github.io/hextra-starter-template/)
|
||||||
|
|
||||||
## 作为新项目开始
|
## 作为新项目开始
|
||||||
|
|
||||||
### 前提条件
|
有两种主要方式将 Hextra 主题添加到您的 Hugo 项目中：
|
||||||
|
|
||||||
在开始之前，请确保我们已经安装了 [Hugo](https://gohugo.io/)。
|
1. **Hugo 模块（推荐）**：最简单且推荐的方法。[Hugo 模块](https://gohugo.io/hugo-modules/)允许您直接从在线源拉取主题。主题会自动下载并由 Hugo 管理。
|
||||||
请参考 Hugo 的[官方安装指南](https://gohugo.io/installation/)以获取更多详情。
|
|
||||||
|
|
||||||
[Hugo 模块](https://gohugo.io/hugo-modules/)是管理 Hugo 主题的推荐方式。要使用 Hugo 模块，我们需要安装 [Git](https://git-scm.com/) 和 [Go](https://go.dev/)。
|
2. **Git 子模块**：或者，将 Hextra 添加为 [Git 子模块](https://git-scm.com/book/en/v2/Git-Tools-Submodules)。主题由 Git 下载并存储在您项目的 `themes` 文件夹中。
|
||||||
|
|
||||||
### 初始化 Hugo 站点
|
### 将 Hextra 设置为 Hugo 模块
|
||||||
|
|
||||||
|
#### 先决条件
|
||||||
|
|
||||||
|
在开始之前，您需要安装以下软件：
|
||||||
|
|
||||||
|
- [Hugo（扩展版）](https://gohugo.io/installation/)
|
||||||
|
- [Git](https://git-scm.com/)
|
||||||
|
- [Go](https://go.dev/)
|
||||||
|
|
||||||
|
#### 步骤
|
||||||
|
|
||||||
|
{{% steps %}}
|
||||||
|
|
||||||
|
### 初始化一个新的 Hugo 站点
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
hugo new site my-site --format=yaml
|
hugo new site my-site --format=yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
### 通过 Hugo Module 安装
|
### 通过模块配置 Hextra 主题
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
# 初始化 Hugo 模块
|
# 初始化 Hugo 模块
|
||||||
cd my-site
|
cd my-site
|
||||||
hugo mod init github.com/username/my-site
|
hugo mod init github.com/username/my-site
|
||||||
|
|
||||||
# 添加 Hextra
|
# 添加 Hextra 主题
|
||||||
hugo mod get github.com/imfing/hextra
|
hugo mod get github.com/imfing/hextra
|
||||||
```
|
```
|
||||||
|
|
||||||
编辑 `hugo.yaml` 以启用 Hextra：
|
配置 `hugo.yaml` 以使用 Hextra 主题，添加以下内容：
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
module:
|
module:
|
||||||
@ -51,92 +65,128 @@ module:
|
|||||||
- path: github.com/imfing/hextra
|
- path: github.com/imfing/hextra
|
||||||
```
|
```
|
||||||
|
|
||||||
### 通过 Git Submodule 安装
|
### 创建您的内容页面
|
||||||
|
|
||||||
#### 先决条件
|
为主页和文档页面创建新的内容页面：
|
||||||
|
|
||||||
在我们开始之前，你必须先确保以下软件已经安装：
|
|
||||||
|
|
||||||
- [Hugo (extended version)](https://gohugo.io/installation/)
|
|
||||||
- [Git](https://git-scm.com/)
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
|
|
||||||
{{% steps %}}
|
|
||||||
|
|
||||||
### 初始化 Hugo 站点
|
|
||||||
|
|
||||||
```shell
|
|
||||||
hugo new site my-site --format=yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
### 将 Hextra 添加为 Git Submodule
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git submodule add https://github.com/imfing/hextra.git themes/hextra
|
|
||||||
```
|
|
||||||
|
|
||||||
添加以下内容来配置 `hugo.yaml` 以使用 Hextra：
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
theme: hextra
|
|
||||||
```
|
|
||||||
|
|
||||||
### 创建你的第一个内容页
|
|
||||||
|
|
||||||
让我们为主页和文档页面创建一个新的内容页面：
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
hugo new content/_index.md
|
hugo new content/_index.md
|
||||||
hugo new content/docs/_index.md
|
hugo new content/docs/_index.md
|
||||||
```
|
```
|
||||||
|
|
||||||
### 在本地预览站点
|
### 本地预览站点
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
hugo server --buildDrafts --disableFastRender
|
hugo server --buildDrafts --disableFastRender
|
||||||
```
|
```
|
||||||
|
|
||||||
瞧！你现在可以在 `http://localhost:1313/` 看到你的新站点。
|
恭喜，您的新站点预览可在 `http://localhost:1313/` 查看。
|
||||||
|
|
||||||
{{% /steps %}}
|
{{% /steps %}}
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
使用 [CI/CD](https://en.wikipedia.org/wiki/CI/CD) 进行部署时，必须确保在运行 `hugo` 命令之前执行以下命令。
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git submodule update --init
|
|
||||||
```
|
|
||||||
|
|
||||||
如果不运行此命令，theme 中将不会存在 Hextra 文件，进而导致构建失败。
|
|
||||||
|
|
||||||
|
|
||||||
{{% details title="如何更新主题？" %}}
|
{{% details title="如何更新主题？" %}}
|
||||||
|
|
||||||
如需把项目中所有的 Hugo Modules 都升级到最新，在终端中运行此命令：
|
要更新项目中所有 Hugo 模块到最新版本，请运行以下命令：
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
hugo mod get -u
|
hugo mod get -u
|
||||||
```
|
```
|
||||||
|
|
||||||
如需把 Hextra 升级到[最新的发行版本](https://github.com/imfing/hextra/releases), 在终端中运行此命令：
|
要将 Hextra 更新到 [最新发布版本](https://github.com/imfing/hextra/releases)，请运行以下命令：
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
hugo mod get -u github.com/imfing/hextra
|
hugo mod get -u github.com/imfing/hextra
|
||||||
```
|
```
|
||||||
|
|
||||||
如果你需要获得更多信息，参见 [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/#update-all-modules).
|
有关更多详细信息，请参阅 [Hugo 模块](https://gohugo.io/hugo-modules/use-modules/#update-all-modules)。
|
||||||
|
|
||||||
{{% /details %}}
|
{{% /details %}}
|
||||||
|
|
||||||
## 接下来
|
### 将 Hextra 设置为 Git 子模块
|
||||||
|
|
||||||
探索这些文档以便添加更多内容：
|
#### 先决条件
|
||||||
|
|
||||||
|
在开始之前，您需要安装以下软件：
|
||||||
|
|
||||||
|
- [Hugo（扩展版）](https://gohugo.io/installation/)
|
||||||
|
- [Git](https://git-scm.com/)
|
||||||
|
|
||||||
|
#### 步骤
|
||||||
|
|
||||||
|
{{% steps %}}
|
||||||
|
|
||||||
|
### 初始化一个新的 Hugo 站点
|
||||||
|
|
||||||
|
```shell
|
||||||
|
hugo new site my-site --format=yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 将 Hextra 主题添加为 Git 子模块
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git submodule add https://github.com/imfing/hextra.git themes/hextra
|
||||||
|
```
|
||||||
|
|
||||||
|
配置 `hugo.yaml` 以使用 Hextra 主题，添加以下内容：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
theme: hextra
|
||||||
|
```
|
||||||
|
|
||||||
|
### 创建您的内容页面
|
||||||
|
|
||||||
|
为主页和文档页面创建新的内容页面：
|
||||||
|
|
||||||
|
```shell
|
||||||
|
hugo new content/_index.md
|
||||||
|
hugo new content/docs/_index.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### 本地预览站点
|
||||||
|
|
||||||
|
```shell
|
||||||
|
hugo server --buildDrafts --disableFastRender
|
||||||
|
```
|
||||||
|
|
||||||
|
您的新站点预览可在 `http://localhost:1313/` 查看。
|
||||||
|
|
||||||
|
{{% /steps %}}
|
||||||
|
|
||||||
|
|
||||||
|
当使用 [CI/CD](https://en.wikipedia.org/wiki/CI/CD) 部署 Hugo 网站时，确保在运行 `hugo` 命令之前执行以下命令至关重要。
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git submodule update --init
|
||||||
|
```
|
||||||
|
|
||||||
|
如果不运行此命令，主题文件夹将不会被 Hextra 主题文件填充，导致构建失败。
|
||||||
|
|
||||||
|
|
||||||
|
{{% details title="如何更新主题？" %}}
|
||||||
|
|
||||||
|
要更新仓库中所有子模块到最新提交，请运行以下命令：
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git submodule update --remote
|
||||||
|
```
|
||||||
|
|
||||||
|
要将 Hextra 更新到最新提交，请运行以下命令：
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git submodule update --remote themes/hextra
|
||||||
|
```
|
||||||
|
|
||||||
|
有关更多详细信息，请参阅 [Git 子模块](https://git-scm.com/book/en/v2/Git-Tools-Submodules)。
|
||||||
|
|
||||||
|
{{% /details %}}
|
||||||
|
|
||||||
|
## 下一步
|
||||||
|
|
||||||
|
探索以下部分以开始添加更多内容：
|
||||||
|
|
||||||
{{< cards >}}
|
{{< cards >}}
|
||||||
{{< card link="../guide/organize-files" title="Organize Files" icon="document-duplicate" >}}
|
{{< card link="../guide/organize-files" title="组织文件" icon="document-duplicate" >}}
|
||||||
{{< card link="../guide/configuration" title="Configuration" icon="adjustments" >}}
|
{{< card link="../guide/configuration" title="配置" icon="adjustments" >}}
|
||||||
{{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
|
{{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
|
||||||
{{< /cards >}}
|
{{< /cards >}}
|
||||||
@ -7,16 +7,17 @@ sidebar:
|
|||||||
open: true
|
open: true
|
||||||
---
|
---
|
||||||
|
|
||||||
探索以下各节以学习如何使用 Hextra 编写内容：
|
探索以下部分，了解如何使用 Hextra：
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
{{< cards >}}
|
{{< cards >}}
|
||||||
{{< card link="organize-files" title="目录结构" icon="document-duplicate" >}}
|
{{< card link="organize-files" title="文件组织" icon="document-duplicate" >}}
|
||||||
{{< card link="configuration" title="配置" icon="adjustments" >}}
|
{{< card link="configuration" title="配置" icon="adjustments" >}}
|
||||||
{{< card link="markdown" title="Markdown" icon="markdown" >}}
|
{{< card link="markdown" title="Markdown" icon="markdown" >}}
|
||||||
{{< card link="syntax-highlighting" title="代码高亮" icon="sparkles" >}}
|
{{< card link="syntax-highlighting" title="语法高亮" icon="sparkles" >}}
|
||||||
{{< card link="latex" title="LaTeX 公式" icon="variable" >}}
|
{{< card link="latex" title="LaTeX" icon="variable" >}}
|
||||||
{{< card link="diagrams" title="图表" icon="chart-square-bar" >}}
|
{{< card link="diagrams" title="图表" icon="chart-square-bar" >}}
|
||||||
{{< card link="shortcodes" title="短代码" icon="template" >}}
|
{{< card link="shortcodes" title="短代码" icon="template" >}}
|
||||||
{{< /cards >}}
|
{{< card link="deploy-site" title="部署站点" icon="server" >}}
|
||||||
|
{{< /cards >}}
|
||||||
@ -1,33 +1,33 @@
|
|||||||
---
|
---
|
||||||
title: 配置文件
|
title: 配置
|
||||||
weight: 2
|
weight: 2
|
||||||
---
|
---
|
||||||
|
|
||||||
Hugo 从 Hugo 网站根目录下的 `hugo.yaml` 读取配置。
|
Hugo 从您 Hugo 站点根目录下的 `hugo.yaml` 文件中读取配置。
|
||||||
在配置文件中，您可以配置站点的所有选项。
|
配置文件是您可以配置站点所有方面的地方。
|
||||||
你可以在 `exampleSite/hugo.yaml` 中找到此站点的配置文件作为开始。
|
查看此站点的配置文件 [`exampleSite/hugo.yaml`](https://github.com/imfing/hextra/blob/main/exampleSite/hugo.yaml) 在 GitHub 上，以全面了解可用的设置和最佳实践。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
## 导航栏
|
## 导航
|
||||||
|
|
||||||
### 菜单
|
### 菜单
|
||||||
|
|
||||||
右上角的菜单在配置文件的 `menu.main` 中配置：
|
右上角的菜单在配置文件的 `menu.main` 部分中定义：
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
menu:
|
menu:
|
||||||
main:
|
main:
|
||||||
- name: Documentation
|
- name: 文档
|
||||||
pageRef: /docs
|
pageRef: /docs
|
||||||
weight: 1
|
weight: 1
|
||||||
- name: Blog
|
- name: 博客
|
||||||
pageRef: /blog
|
pageRef: /blog
|
||||||
weight: 2
|
weight: 2
|
||||||
- name: About
|
- name: 关于
|
||||||
pageRef: /about
|
pageRef: /about
|
||||||
weight: 3
|
weight: 3
|
||||||
- name: Search
|
- name: 搜索
|
||||||
weight: 4
|
weight: 4
|
||||||
params:
|
params:
|
||||||
type: search
|
type: search
|
||||||
@ -38,55 +38,83 @@ menu:
|
|||||||
icon: github
|
icon: github
|
||||||
```
|
```
|
||||||
|
|
||||||
有几种不同类型的菜单项：
|
有不同类型的菜单项：
|
||||||
|
|
||||||
1. Link to a page in the site with `pageRef`
|
1. 使用 `pageRef` 链接到站点内的页面
|
||||||
```yaml
|
```yaml
|
||||||
- name: Documentation
|
- name: 文档
|
||||||
pageRef: /docs
|
pageRef: /docs
|
||||||
```
|
```
|
||||||
2. Link to an external URL with `url`
|
2. 使用 `url` 链接到外部 URL
|
||||||
```yaml
|
```yaml
|
||||||
- name: GitHub
|
- name: GitHub
|
||||||
url: "https://github.com"
|
url: "https://github.com"
|
||||||
```
|
```
|
||||||
3. Search bar with `type: search`
|
3. 使用 `type: search` 的搜索栏
|
||||||
```yaml
|
```yaml
|
||||||
- name: Search
|
- name: 搜索
|
||||||
params:
|
params:
|
||||||
type: search
|
type: search
|
||||||
```
|
```
|
||||||
4. Icon
|
4. 图标
|
||||||
```yaml
|
```yaml
|
||||||
- name: GitHub
|
- name: GitHub
|
||||||
params:
|
params:
|
||||||
icon: github
|
icon: github
|
||||||
```
|
```
|
||||||
|
|
||||||
这些菜单项可以通过设置 `weight` 进行排序。
|
这些菜单项可以通过设置 `weight` 参数进行排序。
|
||||||
|
|
||||||
|
### 徽标和标题
|
||||||
|
|
||||||
|
要修改默认徽标，编辑 `hugo.yaml` 并在 `static` 目录下添加徽标文件的路径。
|
||||||
|
您还可以更改用户点击徽标时重定向的链接，以及设置徽标的宽度和高度（以像素为单位）。
|
||||||
|
|
||||||
|
```yaml {filename="hugo.yaml"}
|
||||||
|
params:
|
||||||
|
navbar:
|
||||||
|
displayTitle: true
|
||||||
|
displayLogo: true
|
||||||
|
logo:
|
||||||
|
path: images/logo.svg
|
||||||
|
dark: images/logo-dark.svg
|
||||||
|
link: /
|
||||||
|
width: 40
|
||||||
|
height: 20
|
||||||
|
```
|
||||||
|
|
||||||
## 侧边栏
|
## 侧边栏
|
||||||
|
|
||||||
### 主侧边栏
|
### 主侧边栏
|
||||||
|
|
||||||
主侧边栏是自动从 `content` 目录结构生成的。
|
主侧边栏是根据内容目录的结构自动生成的。
|
||||||
有关更多详细信息，转至 [目录结构](/docs/guide/organize-files)。
|
有关更多详细信息，请参阅 [组织文件](/docs/guide/organize-files) 页面。
|
||||||
|
|
||||||
|
要从左侧边栏中排除单个页面，请在页面的 front matter 中设置 `sidebar.exclude` 参数：
|
||||||
|
|
||||||
|
```yaml {filename="content/docs/guide/configuration.md"}
|
||||||
|
---
|
||||||
|
title: 配置
|
||||||
|
sidebar:
|
||||||
|
exclude: true
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
### 额外链接
|
### 额外链接
|
||||||
|
|
||||||
侧边栏的额外链接在配置文件的 `menu.sidebar` 部分中配置：
|
侧边栏的额外链接在配置文件的 `menu.sidebar` 部分中定义：
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
menu:
|
menu:
|
||||||
sidebar:
|
sidebar:
|
||||||
- name: More
|
- name: 更多
|
||||||
params:
|
params:
|
||||||
type: separator
|
type: separator
|
||||||
weight: 1
|
weight: 1
|
||||||
- name: "About"
|
- name: "关于"
|
||||||
pageRef: "/about"
|
pageRef: "/about"
|
||||||
weight: 2
|
weight: 2
|
||||||
- name: "Hugo Docs ↗"
|
- name: "Hugo 文档 ↗"
|
||||||
url: "https://gohugo.io/documentation/"
|
url: "https://gohugo.io/documentation/"
|
||||||
weight: 3
|
weight: 3
|
||||||
```
|
```
|
||||||
@ -95,50 +123,54 @@ menu:
|
|||||||
|
|
||||||
### 目录
|
### 目录
|
||||||
|
|
||||||
目录是根据内容文件中的标题自动生成的，可以在 `front matter` 设置 `toc：false` 来禁用它。
|
目录是根据内容文件中的标题自动生成的。可以通过在页面的 front matter 中设置 `toc: false` 来禁用它。
|
||||||
|
|
||||||
```yaml {filename="content/docs/guide/configuration.md"}
|
```yaml {filename="content/docs/guide/configuration.md"}
|
||||||
---
|
---
|
||||||
title: Configuration
|
title: 配置
|
||||||
toc: false
|
toc: false
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
### 编辑此页链接
|
### 页面编辑链接
|
||||||
|
|
||||||
|
要配置页面编辑链接，我们可以在配置文件中设置 `params.editURL.base` 参数：
|
||||||
|
|
||||||
要配置编辑此页链接，我们可以在配置文件中设置 `params.editURL.base`：
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
params:
|
params:
|
||||||
editURL:
|
editURL:
|
||||||
|
enable: true
|
||||||
base: "https://github.com/your-username/your-repo/edit/main"
|
base: "https://github.com/your-username/your-repo/edit/main"
|
||||||
```
|
```
|
||||||
|
|
||||||
将为每个页面自动生成编辑链接。
|
编辑链接将根据提供的 URL 作为根目录自动为每个页面生成。
|
||||||
如需为特定页面设置编辑链接，可以在页面的 `front matter` 中设置 `editURL`：
|
如果要为特定页面设置编辑链接，可以在页面的 front matter 中设置 `editURL` 参数：
|
||||||
|
|
||||||
```yaml {filename="content/docs/guide/configuration.md"}
|
```yaml {filename="content/docs/guide/configuration.md"}
|
||||||
---
|
---
|
||||||
title: Configuration
|
title: 配置
|
||||||
editURL: "https://example.com/edit/this/page"
|
editURL: "https://example.com/edit/this/page"
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
## Footer
|
|
||||||
|
|
||||||
### 版权声明
|
## 页脚
|
||||||
|
|
||||||
如需修改网站页脚中显示的版权文本，您需要创建一个名为“i18n/en.yaml”的文件。
|
### 版权
|
||||||
在此文件中，填写新的版权文本，像这样：
|
|
||||||
|
要修改网站页脚中显示的版权文本，您需要创建一个名为 `i18n/en.yaml` 的文件。
|
||||||
|
在此文件中，指定您的新版权文本，如下所示：
|
||||||
|
|
||||||
```yaml {filename="i18n/en.yaml"}
|
```yaml {filename="i18n/en.yaml"}
|
||||||
copyright: "© 2024 YOUR TEXT HERE"
|
copyright: "© 2024 您的文本"
|
||||||
```
|
```
|
||||||
你可以在 GitHub 存储库中找到示例 [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) 文件。另外，你可以在版权文本中使用 Markdown 格式。
|
|
||||||
|
作为参考，可以在 GitHub 仓库中找到示例 [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) 文件。此外，您可以在版权文本中使用 Markdown 格式。
|
||||||
|
|
||||||
## 其他
|
## 其他
|
||||||
|
|
||||||
### Favicon
|
### 网站图标
|
||||||
|
|
||||||
如需自定义 [favicon](https://en.wikipedia.org/wiki/Favicon)，请将图标文件放在 `static` 文件夹下以覆盖 [主题中的默认 favicon](https://github.com/imfing/hextra/tree/main/static)：
|
要为您的站点自定义 [网站图标](https://en.wikipedia.org/wiki/Favicon)，请将图标文件放在 `static` 文件夹下，以覆盖 [主题的默认网站图标](https://github.com/imfing/hextra/tree/main/static)：
|
||||||
|
|
||||||
{{< filetree/container >}}
|
{{< filetree/container >}}
|
||||||
{{< filetree/folder name="static" >}}
|
{{< filetree/folder name="static" >}}
|
||||||
@ -154,15 +186,14 @@ copyright: "© 2024 YOUR TEXT HERE"
|
|||||||
{{< /filetree/folder >}}
|
{{< /filetree/folder >}}
|
||||||
{{< /filetree/container >}}
|
{{< /filetree/container >}}
|
||||||
|
|
||||||
在您的项目中包含 `favicon.ico` 和 `favicon.svg` 文件，以确保网站的网站图标正确显示。
|
在您的项目中包含 `favicon.ico`、`favicon.svg` 和 `favicon-dark.svg` 文件，以确保您的站点图标正确显示。
|
||||||
|
|
||||||
虽然 `favicon.ico` 通常适用于较旧的浏览器，但 `favicon.svg` 受到现代浏览器的支持，所以更现代的做法是添加 `favicon-dark.svg` 以便在黑暗模式下提供较好的体验体验。
|
虽然 `favicon.ico` 通常用于旧版浏览器，但 `favicon.svg` 和 `favicon-dark.svg` 受现代浏览器支持。
|
||||||
|
使用 [favicon.io](https://favicon.io/) 或 [favycon](https://github.com/ruisaraiva19/favycon) 等工具生成此类图标。
|
||||||
|
|
||||||
请随意使用 [favicon.io](https://favicon.io/) 或 [favycon](https://github.com/ruisaraiva19/favycon) 等工具来生成这些图标。
|
### 主题配置
|
||||||
|
|
||||||
### 颜色主题配置
|
使用 `theme` 设置来配置默认主题模式和切换按钮，允许访问者在浅色或深色模式之间切换。
|
||||||
|
|
||||||
使用`theme`设置来配置默认主题模式和切换按钮，允许访问者在浅色或深色模式之间切换。
|
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
params:
|
params:
|
||||||
@ -172,18 +203,18 @@ params:
|
|||||||
displayToggle: true
|
displayToggle: true
|
||||||
```
|
```
|
||||||
|
|
||||||
`theme.default` 的可选项：
|
`theme.default` 的选项：
|
||||||
|
|
||||||
- `light` - 仅使用浅色模式
|
- `light` - 始终使用浅色模式
|
||||||
- `dark` - 仅使用神色模式
|
- `dark` - 始终使用深色模式
|
||||||
- `system` - 跟随系统
|
- `system` - 与操作系统设置同步（默认）
|
||||||
|
|
||||||
`theme.displayToggle` 控制显示用于更改主题的切换按钮。
|
`theme.displayToggle` 参数允许您显示一个切换按钮以更改主题。
|
||||||
当设置为“true”时，访问者可以在浅色或深色模式之间切换，覆盖默认设置。
|
当设置为 `true` 时，访问者可以在浅色或深色模式之间切换，覆盖默认设置。
|
||||||
|
|
||||||
### 页宽
|
### 页面宽度
|
||||||
|
|
||||||
页面的宽度可以通过配置文件中的`params.page.width`参数来调整：
|
页面的宽度可以通过配置文件中的 `params.page.width` 参数进行自定义：
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
params:
|
params:
|
||||||
@ -192,36 +223,37 @@ params:
|
|||||||
width: wide
|
width: wide
|
||||||
```
|
```
|
||||||
|
|
||||||
有三个可选项：`full`, `wide`, and `normal`. 默认的页宽模式是 `normal`.
|
有三个可用选项：`full`、`wide` 和 `normal`。默认情况下，页面宽度设置为 `normal`。
|
||||||
|
|
||||||
同样的，导航栏和 `footer` 的宽度也可通过 `params.navbar.width` 和 `params.footer.width` 调整。
|
同样，导航栏和页脚的宽度可以通过 `params.navbar.width` 和 `params.footer.width` 参数进行自定义。
|
||||||
|
|
||||||
### 搜索
|
### 搜索索引
|
||||||
|
|
||||||
默认情况下启用由 [FlexSearch](https://github.com/nextapps-de/flexsearch) 提供全文搜索。
|
默认启用由 [FlexSearch](https://github.com/nextapps-de/flexsearch) 提供的全文搜索。
|
||||||
要自定义搜索索引，请在配置文件中设置 `params.search.flexsearch.index` ：
|
要自定义搜索索引，请在配置文件中设置 `params.search.flexsearch.index` 参数：
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
params:
|
params:
|
||||||
# Search
|
# 搜索
|
||||||
search:
|
search:
|
||||||
enable: true
|
enable: true
|
||||||
type: flexsearch
|
type: flexsearch
|
||||||
|
|
||||||
flexsearch:
|
flexsearch:
|
||||||
# index page by: content | summary | heading | title
|
# 按以下内容索引页面：content | summary | heading | title
|
||||||
index: content
|
index: content
|
||||||
```
|
```
|
||||||
`flexsearch.index` 的可选项：
|
|
||||||
|
|
||||||
- `content` - 全内容搜索
|
`flexsearch.index` 的选项：
|
||||||
- `summary` - 概述 [Hugo Content Summaries](https://gohugo.io/content-management/summaries/)
|
|
||||||
|
- `content` - 页面的完整内容（默认）
|
||||||
|
- `summary` - 页面的摘要，请参阅 [Hugo 内容摘要](https://gohugo.io/content-management/summaries/) 了解更多详细信息
|
||||||
- `heading` - 一级和二级标题
|
- `heading` - 一级和二级标题
|
||||||
- `title` - 仅搜索标题
|
- `title` - 仅包括页面标题
|
||||||
|
|
||||||
要自定义检索分词，请在配置文件中设置`params.search.flexsearch.tokenize`：
|
要自定义搜索分词，请在配置文件中设置 `params.search.flexsearch.tokenize` 参数：
|
||||||
|
|
||||||
```hugo.yaml
|
```yaml {filename="hugo.yaml"}
|
||||||
params:
|
params:
|
||||||
# ...
|
# ...
|
||||||
flexsearch:
|
flexsearch:
|
||||||
@ -229,30 +261,28 @@ params:
|
|||||||
tokenize: forward
|
tokenize: forward
|
||||||
```
|
```
|
||||||
|
|
||||||
[`flexsearch.tokenize`](https://github.com/nextapps-de/flexsearch/#tokenizer-prefix-search)的可选项:
|
[`flexsearch.tokenize`](https://github.com/nextapps-de/flexsearch/#tokenizer-prefix-search) 的选项：
|
||||||
|
|
||||||
- `strict` - 严格单词匹配
|
- `strict` - 索引整个单词
|
||||||
- `forward` - 单词前缀匹配
|
- `forward` - 向前方向逐步索引单词
|
||||||
- `reverse` - 单词前后缀匹配
|
- `reverse` - 双向逐步索引单词
|
||||||
- `full` - 单词子串匹配。
|
- `full` - 索引所有可能的组合
|
||||||
|
|
||||||
> 在默认的分词逻辑下，中文一句话就是一个“单词”
|
要从搜索索引中排除页面，请在页面的 front matter 中设置 `excludeSearch: true`：
|
||||||
|
|
||||||
要从搜索索引中排除页面，更改 front matter 中的 `excludeSearch: true`:
|
|
||||||
|
|
||||||
```yaml {filename="content/docs/guide/configuration.md"}
|
```yaml {filename="content/docs/guide/configuration.md"}
|
||||||
---
|
---
|
||||||
title: Configuration
|
title: 配置
|
||||||
excludeSearch: true
|
excludeSearch: true
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
### Google Analytics
|
### Google Analytics
|
||||||
|
|
||||||
要启用 [Google Analytics](https://marketingplatform.google.com/about/analytics/)，设置 `services.googleAnalytics.ID`:
|
要启用 [Google Analytics](https://marketingplatform.google.com/about/analytics/)，请在 `hugo.yaml` 中设置 `services.googleAnalytics.ID` 标志：
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
services:
|
services:
|
||||||
googleAnalytics:
|
googleAnalytics:
|
||||||
ID: G-MEASUREMENT_ID
|
ID: G-MEASUREMENT_ID
|
||||||
```
|
```
|
||||||
@ -4,32 +4,32 @@ prev: /docs/guide/shortcodes
|
|||||||
next: /docs/advanced
|
next: /docs/advanced
|
||||||
---
|
---
|
||||||
|
|
||||||
Hugo 生成静态站点，允许多种托管方式，你可以自由选择
|
Hugo 生成静态网站，允许灵活的托管选项。
|
||||||
本页将给出部署你的 Hextra 站点的方法
|
本页提供了在各种平台上部署 Hextra 站点的指南。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
|
|
||||||
## GitHub Pages
|
## GitHub Pages
|
||||||
|
|
||||||
[GitHub Pages](https://docs.github.com/pages) 是免费部署和托管网站的推荐方法
|
[GitHub Pages](https://docs.github.com/pages) 是推荐的方式，可以免费部署和托管您的网站。
|
||||||
|
|
||||||
如果您使用以下方式引导该网站 [hextra-starter-template](https://github.com/imfing/hextra-starter-template), 它提供了开箱即用的 GitHub Actions 工作流程，有助于自动部署到 GitHub Pages
|
如果您使用 [hextra-starter-template](https://github.com/imfing/hextra-starter-template) 引导站点，它已经提供了开箱即用的 GitHub Actions 工作流，帮助自动部署到 GitHub Pages。
|
||||||
|
|
||||||
{{% details title="GitHub Actions Configuration" closed="true" %}}
|
{{% details title="GitHub Actions 配置" closed="true" %}}
|
||||||
|
|
||||||
以下是配置来自 [hextra-starter-template](https://github.com/imfing/hextra-starter-template) 的 Workflow 的示例：
|
以下是 [hextra-starter-template](https://github.com/imfing/hextra-starter-template) 的示例配置：
|
||||||
|
|
||||||
```yaml {filename=".github/workflows/pages.yaml"}
|
```yaml {filename=".github/workflows/pages.yaml"}
|
||||||
# 用于构建 Hugo 站点并将其部署到 GitHub Pages 的示例工作流程
|
# 用于构建和部署 Hugo 站点到 GitHub Pages 的示例工作流
|
||||||
name: Deploy Hugo site to Pages
|
name: 部署 Hugo 站点到 Pages
|
||||||
|
|
||||||
on:
|
on:
|
||||||
# 由默认分支触发
|
# 在推送到默认分支时运行
|
||||||
push:
|
push:
|
||||||
branches: ["main"]
|
branches: ["main"]
|
||||||
|
|
||||||
# 允许手动运行
|
# 允许您从 Actions 选项卡手动运行此工作流
|
||||||
workflow_dispatch:
|
workflow_dispatch:
|
||||||
|
|
||||||
# 设置 GITHUB_TOKEN 的权限以允许部署到 GitHub Pages
|
# 设置 GITHUB_TOKEN 的权限以允许部署到 GitHub Pages
|
||||||
@ -38,55 +38,55 @@ permissions:
|
|||||||
pages: write
|
pages: write
|
||||||
id-token: write
|
id-token: write
|
||||||
|
|
||||||
# 仅允许一项并发部署，跳过正在进行的运行和最新排队的运行之间排队的运行
|
# 只允许一个并发部署，跳过在运行中和最新排队之间的运行。
|
||||||
# 但是，不要取消正在进行的运行，因为我们希望完成这些生产部署
|
# 但是，不要取消正在运行的运行，因为我们希望这些生产部署能够完成。
|
||||||
concurrency:
|
concurrency:
|
||||||
group: "pages"
|
group: "pages"
|
||||||
cancel-in-progress: false
|
cancel-in-progress: false
|
||||||
|
|
||||||
# 默认为 bash
|
# 默认使用 bash
|
||||||
defaults:
|
defaults:
|
||||||
run:
|
run:
|
||||||
shell: bash
|
shell: bash
|
||||||
|
|
||||||
jobs:
|
jobs:
|
||||||
# 开始构建
|
# 构建任务
|
||||||
build:
|
build:
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
env:
|
env:
|
||||||
HUGO_VERSION: 0.121.2
|
HUGO_VERSION: 0.138.0
|
||||||
steps:
|
steps:
|
||||||
- name: Checkout
|
- name: 检出
|
||||||
uses: actions/checkout@v4
|
uses: actions/checkout@v4
|
||||||
with:
|
with:
|
||||||
fetch-depth: 0 # 获取 .GitInfo 和 .Lastmod 的所有历史记录
|
fetch-depth: 0 # 获取所有历史记录以支持 .GitInfo 和 .Lastmod
|
||||||
submodules: recursive
|
submodules: recursive
|
||||||
- name: Setup Go
|
- name: 设置 Go
|
||||||
uses: actions/setup-go@v5
|
uses: actions/setup-go@v5
|
||||||
with:
|
with:
|
||||||
go-version: '1.21'
|
go-version: '1.22'
|
||||||
- name: Setup Pages
|
- name: 设置 Pages
|
||||||
id: pages
|
id: pages
|
||||||
uses: actions/configure-pages@v4
|
uses: actions/configure-pages@v4
|
||||||
- name: Setup Hugo
|
- name: 设置 Hugo
|
||||||
run: |
|
run: |
|
||||||
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
|
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
|
||||||
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
|
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
|
||||||
- name: Build with Hugo
|
- name: 使用 Hugo 构建
|
||||||
env:
|
env:
|
||||||
# 最大程度地向后兼容 Hugo 模块
|
# 为了最大程度地兼容 Hugo 模块
|
||||||
HUGO_ENVIRONMENT: production
|
HUGO_ENVIRONMENT: production
|
||||||
HUGO_ENV: production
|
HUGO_ENV: production
|
||||||
run: |
|
run: |
|
||||||
hugo \
|
hugo \
|
||||||
--gc --minify \
|
--gc --minify \
|
||||||
--baseURL "${{ steps.pages.outputs.base_url }}/"
|
--baseURL "${{ steps.pages.outputs.base_url }}/"
|
||||||
- name: Upload artifact
|
- name: 上传工件
|
||||||
uses: actions/upload-pages-artifact@v3
|
uses: actions/upload-pages-artifact@v3
|
||||||
with:
|
with:
|
||||||
path: ./public
|
path: ./public
|
||||||
|
|
||||||
# 开始部署
|
# 部署任务
|
||||||
deploy:
|
deploy:
|
||||||
environment:
|
environment:
|
||||||
name: github-pages
|
name: github-pages
|
||||||
@ -94,7 +94,7 @@ jobs:
|
|||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
needs: build
|
needs: build
|
||||||
steps:
|
steps:
|
||||||
- name: Deploy to GitHub Pages
|
- name: 部署到 GitHub Pages
|
||||||
id: deployment
|
id: deployment
|
||||||
uses: actions/deploy-pages@v4
|
uses: actions/deploy-pages@v4
|
||||||
```
|
```
|
||||||
@ -103,13 +103,13 @@ jobs:
|
|||||||
|
|
||||||
|
|
||||||
{{< callout >}}
|
{{< callout >}}
|
||||||
在仓库设置中将 **Pages** > **Build and deployment** > **Source** 调整为 **GitHub Actions**:
|
在您的仓库设置中，将 **Pages** > **Build and deployment** > **Source** 设置为 **GitHub Actions**：
|
||||||
|
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
默认情况下，上述 GitHub Actions 工作流程 `.github/workflows/pages.yaml` 假定站点部署到 `https://<USERNAME>.github.io/<REPO>/`
|
默认情况下，上述 GitHub Actions 工作流 `.github/workflows/pages.yaml` 假设站点部署到 `https://<USERNAME>.github.io/<REPO>/`。
|
||||||
|
|
||||||
如需部署到 `https://<USERNAME>.github.io/` 修改参数 `--baseURL`:
|
如果您部署到 `https://<USERNAME>.github.io/`，请修改 `--baseURL`：
|
||||||
|
|
||||||
```yaml {filename=".github/workflows/pages.yaml",linenos=table,linenostart=54,hl_lines=[4]}
|
```yaml {filename=".github/workflows/pages.yaml",linenos=table,linenostart=54,hl_lines=[4]}
|
||||||
run: |
|
run: |
|
||||||
@ -118,47 +118,47 @@ run: |
|
|||||||
--baseURL "https://${{ github.repository_owner }}.github.io/"
|
--baseURL "https://${{ github.repository_owner }}.github.io/"
|
||||||
```
|
```
|
||||||
|
|
||||||
如需部署到自己的域，请对应修改 `--baseURL`
|
如果您部署到自己的域名，请相应地更改 `--baseURL` 值。
|
||||||
|
|
||||||
|
|
||||||
## Cloudflare Pages
|
## Cloudflare Pages
|
||||||
|
|
||||||
1. 将您的网站托管在 Git 存储库（例如 GitHub）
|
1. 将您的站点源代码放入 Git 仓库（例如 GitHub）
|
||||||
2. 登录到 [Cloudflare dashboard](https://dash.cloudflare.com/) 并选择你的账户
|
2. 登录 [Cloudflare 仪表板](https://dash.cloudflare.com/) 并选择您的账户
|
||||||
3. 转至在账户主页面中 **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**
|
3. 在账户主页中，选择 **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**
|
||||||
4. 选择你的仓库 **Set up builds and deployments** 提供以下信息：
|
4. 选择仓库，并在 **Set up builds and deployments** 部分提供以下信息：
|
||||||
|
|
||||||
| Configuration | Value |
|
| 配置项 | 值 |
|
||||||
| ----------------- | -------------------- |
|
| ------------------ | -------------------- |
|
||||||
| Production branch | `main` |
|
| 生产分支 | `main` |
|
||||||
| Build command | `hugo --gc --minify` |
|
| 构建命令 | `hugo --gc --minify` |
|
||||||
| Build directory | `public` |
|
| 构建目录 | `public` |
|
||||||
|
|
||||||
如需了解更多内容，见：
|
更多详情，请查看：
|
||||||
- [Deploy a Hugo site](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages).
|
- [部署 Hugo 站点](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages)。
|
||||||
- [Language support and tools](https://developers.cloudflare.com/pages/platform/language-support-and-tools/).
|
- [语言支持和工具](https://developers.cloudflare.com/pages/platform/language-support-and-tools/)。
|
||||||
|
|
||||||
|
|
||||||
## Netlify
|
## Netlify
|
||||||
|
|
||||||
1. 将代码推送到 Git 存储库 (如 GitHub, GitLab)
|
1. 将代码推送到您的 Git 仓库（GitHub、GitLab 等）
|
||||||
2. [导入项目](https://app.netlify.com/start)
|
2. [导入项目](https://app.netlify.com/start) 到 Netlify
|
||||||
3. 如果您不使用[hextra-starter-template][hextra-starter-template], 手动配置以下内容：
|
3. 如果您没有使用 [hextra-starter-template][hextra-starter-template]，请手动配置以下内容：
|
||||||
- C 将构建命令配置为 `hugo --gc --minify`
|
- 将构建命令配置为 `hugo --gc --minify`
|
||||||
- 指定发布目录为 `public`
|
- 指定发布目录为 `public`
|
||||||
- 添加环境变量 `HUGO_VERSION` 并设定为 `0.119.0`
|
- 添加环境变量 `HUGO_VERSION` 并设置为 `0.138.0`，或者将其设置在 `netlify.toml` 文件中
|
||||||
4. 部署
|
4. 部署！
|
||||||
|
|
||||||
转至 [Hugo on Netlify](https://docs.netlify.com/integrations/frameworks/hugo/) 获得更多信息
|
查看 [Netlify 上的 Hugo](https://docs.netlify.com/integrations/frameworks/hugo/) 了解更多详情。
|
||||||
|
|
||||||
|
|
||||||
## Vercel
|
## Vercel
|
||||||
|
|
||||||
1. 将代码推送到 Git 存储库（GitHub、GitLab 等）
|
1. 将代码推送到您的 Git 仓库（GitHub、GitLab 等）
|
||||||
2. 转至 [Vercel Dashboard](https://vercel.com/dashboard) 并导入你的 Hugo 项目
|
2. 前往 [Vercel 仪表板](https://vercel.com/dashboard) 并导入您的 Hugo 项目
|
||||||
3. 配置项目，选择 Hugo 作为 Framework Preset
|
3. 配置项目，选择 Hugo 作为框架预设
|
||||||
4. 覆盖构建命令和安装命令：
|
4. 覆盖构建命令和安装命令：
|
||||||
1. 设置构建命令为 `hugo --gc --minify`
|
1. 将构建命令设置为 `hugo --gc --minify`
|
||||||
2. 将安装命令设置为 `yum install golang`
|
2. 将安装命令设置为 `yum install golang`
|
||||||
|
|
||||||
|
|
||||||
@ -4,15 +4,15 @@ weight: 6
|
|||||||
next: /docs/guide/shortcodes
|
next: /docs/guide/shortcodes
|
||||||
---
|
---
|
||||||
|
|
||||||
目前，Hextra 支持 [Mermaid](#mermaid) 的图表。
|
目前，Hextra 支持使用 [Mermaid](#mermaid) 来绘制图表。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
## Mermaid
|
## Mermaid
|
||||||
|
|
||||||
[Mermaid](https://github.com/mermaid-js/mermaid#readme) 是一个基于 JavaScript 的图表绘制工具，它的文本定义和 Markdown 类似，可在浏览器中动态创建图表。例如：流程图、序列图、饼图等。
|
[Mermaid](https://github.com/mermaid-js/mermaid#readme) 是一个基于 JavaScript 的图表工具，它通过类似 Markdown 的文本定义，在浏览器中动态生成图表。例如，Mermaid 可以渲染流程图、序列图、饼图等。
|
||||||
|
|
||||||
在 Hextra 中使用 Mermaid 就像使用代码块一样简单：
|
在 Hextra 中使用 Mermaid 非常简单，只需编写一个语言设置为 `mermaid` 的代码块：
|
||||||
|
|
||||||
````markdown
|
````markdown
|
||||||
```mermaid
|
```mermaid
|
||||||
@ -24,7 +24,7 @@ graph TD;
|
|||||||
```
|
```
|
||||||
````
|
````
|
||||||
|
|
||||||
将呈现为：
|
将会渲染为：
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
graph TD;
|
graph TD;
|
||||||
@ -34,20 +34,20 @@ graph TD;
|
|||||||
C-->D;
|
C-->D;
|
||||||
```
|
```
|
||||||
|
|
||||||
Sequence diagram：
|
序列图示例：
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
sequenceDiagram
|
sequenceDiagram
|
||||||
participant Alice
|
participant Alice
|
||||||
participant Bob
|
participant Bob
|
||||||
Alice->>John: Hello John, how are you?
|
Alice->>John: 你好 John，最近怎么样？
|
||||||
loop Healthcheck
|
loop 健康检查
|
||||||
John->>John: Fight against hypochondria
|
John->>John: 与疑病症作斗争
|
||||||
end
|
end
|
||||||
Note right of John: Rational thoughts <br/>prevail!
|
Note right of John: 理性思考 <br/>占据上风！
|
||||||
John-->>Alice: Great!
|
John-->>Alice: 很好！
|
||||||
John->>Bob: How about you?
|
John->>Bob: 你怎么样？
|
||||||
Bob-->>John: Jolly good!
|
Bob-->>John: 非常好！
|
||||||
```
|
```
|
||||||
|
|
||||||
如需获取更多信息，转至 [Mermaid Documentation](https://mermaid-js.github.io/mermaid/#/)。
|
更多信息，请参考 [Mermaid 文档](https://mermaid-js.github.io/mermaid/#/)。
|
||||||
@ -1,33 +1,34 @@
|
|||||||
---
|
---
|
||||||
title: "LaTeX 公式"
|
title: "数学公式"
|
||||||
weight: 4
|
weight: 4
|
||||||
math: true
|
math: true
|
||||||
---
|
---
|
||||||
|
|
||||||
$\KaTeX$ 用于呈现 LaTeX 数学表达式。可在 `frontmatter` 将 `math` 设置为 `true` 来启用。
|
$\KaTeX$ 用于渲染 LaTeX 数学表达式。可以通过在页面前置设置中将 `math` 设置为 `true` 来启用它。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
```yaml {filename="Markdown"}
|
```yaml {filename="page.md"}
|
||||||
---
|
---
|
||||||
title: "My Page with LaTeX"
|
title: "我的页面包含 LaTeX"
|
||||||
math: true
|
math: true
|
||||||
---
|
---
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
启用后，KaTeX 中的脚本，样式表和字体将自动包含在你的网站中。这样就可以在 Markdown 内容中使用 LaTeX 数学表达式。
|
启用后，KaTeX 的脚本、样式表和字体将自动包含在您的站点中。您可以在 Markdown 内容中开始使用 LaTeX 数学表达式。
|
||||||
|
|
||||||
## 示例
|
## 示例
|
||||||
|
|
||||||
Markdown 内容支持行内和独立段落的 LaTeX 数学表达式。
|
Markdown 内容中支持内联和独立段落的 LaTeX 数学表达式。
|
||||||
|
|
||||||
### 行内
|
### 内联
|
||||||
|
|
||||||
```markdown {filename="page.md"}
|
```markdown {filename="page.md"}
|
||||||
This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline.
|
这个 $\sigma(z) = \frac{1}{1 + e^{-z}}$ 是内联的。
|
||||||
```
|
```
|
||||||
|
|
||||||
This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline.
|
这个 $\sigma(z) = \frac{1}{1 + e^{-z}}$ 是内联的。
|
||||||
|
|
||||||
### 独立段落
|
### 独立段落
|
||||||
|
|
||||||
@ -35,20 +36,57 @@ This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline.
|
|||||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||||
```
|
```
|
||||||
|
|
||||||
将被渲染为：
|
将渲染为：
|
||||||
|
|
||||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
> 请在 Hugo 配置文件中启用并配置 [passthrough 扩展](https://gohugo.io/content-management/mathematics/)。它保留分隔符内的原始内容，以避免复杂表达式的渲染问题。
|
||||||
|
|
||||||
## 支持的功能
|
```yaml {filename="hugo.yaml"}
|
||||||
|
markup:
|
||||||
|
goldmark:
|
||||||
|
extensions:
|
||||||
|
passthrough:
|
||||||
|
delimiters:
|
||||||
|
block: [['\[', '\]'], ['$$', '$$']]
|
||||||
|
inline: [['\(', '\)']]
|
||||||
|
enable: true
|
||||||
|
```
|
||||||
|
|
||||||
有关支持的符号列表，转至 [KaTeX 支持的公式](https://katex.org/docs/supported.html)。
|
例如，使用对齐环境：
|
||||||
|
|
||||||
## 化学表达式
|
```latex {filename="page.md"}
|
||||||
|
$$
|
||||||
|
\begin{aligned}
|
||||||
|
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||||
|
\nabla \cdot \mathbf{B} &= 0 \\
|
||||||
|
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||||
|
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||||
|
\end{aligned}
|
||||||
|
$$
|
||||||
|
```
|
||||||
|
|
||||||
通过 [mhchem](https://mhchem.github.io/MathJax-mhchem/) 支持化学表达式。
|
将渲染为：
|
||||||
|
|
||||||
行内：$\ce{H2O}$ 是水。
|
$$
|
||||||
|
\begin{aligned}
|
||||||
|
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||||
|
\nabla \cdot \mathbf{B} &= 0 \\
|
||||||
|
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||||
|
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||||
|
\end{aligned}
|
||||||
|
$$
|
||||||
|
|
||||||
|
## 支持的函数
|
||||||
|
|
||||||
|
有关支持的函数列表，请参阅 [KaTeX 支持的函数](https://katex.org/docs/supported.html)。
|
||||||
|
|
||||||
|
## 化学
|
||||||
|
|
||||||
|
通过 [mhchem](https://mhchem.github.io/MathJax-mhchem/) 扩展支持化学表达式。
|
||||||
|
|
||||||
|
内联：$\ce{H2O}$ 是水。
|
||||||
|
|
||||||
独立段落：
|
独立段落：
|
||||||
|
|
||||||
|
|||||||
@ -3,7 +3,7 @@ title: Markdown
|
|||||||
weight: 2
|
weight: 2
|
||||||
---
|
---
|
||||||
|
|
||||||
Hugo 支持 [Markdown](https://en.wikipedia.org/wiki/Markdown) 来书写内容，创建列表等。本页将向你展示一些最常见的 Markdown 语法示例。
|
Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来格式化文本、创建列表等。本页将展示一些最常见的 Markdown 语法示例。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
@ -11,130 +11,171 @@ Hugo 支持 [Markdown](https://en.wikipedia.org/wiki/Markdown) 来书写内容
|
|||||||
|
|
||||||
### 文本样式
|
### 文本样式
|
||||||
|
|
||||||
| Style | Syntax | Example | Output |
|
| 样式 | 语法 | 示例 | 输出 |
|
||||||
| -------- | -------- | ------ | ------ |
|
| -------- | -------- | ------ | ------ |
|
||||||
| Bold | `**bold text**` | `**bold text**` | **bold text** |
|
| 粗体 | `**粗体文本**` | `**粗体文本**` | **粗体文本** |
|
||||||
| Italic | `*italicized text*` | `*italicized text* | *italicized text* |
|
| 斜体 | `*斜体文本*` | `*斜体文本*` | *斜体文本* |
|
||||||
| Strikethrough | `~~strikethrough text~~` | `~~strikethrough text~~` | ~~strikethrough text~~ |
|
| 删除线 | `~~删除线文本~~` | `~~删除线文本~~` | ~~删除线文本~~ |
|
||||||
| Subscript | `<sub></sub>` | `This is a <sub>subscript</sub> text` | This is a <sub>subscript</sub> text |
|
| 下标 | `<sub></sub>` | `这是一个<sub>下标</sub>文本` | 这是一个<sub>下标</sub>文本 |
|
||||||
| Superscript | `<sup></sup>` | `This is a <sup>superscript</sup> text` | This is a <sup>superscript</sup> text |
|
| 上标 | `<sup></sup>` | `这是一个<sup>上标</sup>文本` | 这是一个<sup>上标</sup>文本 |
|
||||||
|
|
||||||
### 引用
|
### 引用块
|
||||||
|
|
||||||
带角标的块引用：
|
带出处的引用块
|
||||||
|
|
||||||
> Don't communicate by sharing memory, share memory by communicating.<br>
|
> 不要通过共享内存来通信，而要通过通信来共享内存。<br>
|
||||||
> — <cite>Rob Pike[^1]</cite>
|
> — <cite>Rob Pike[^1]</cite>
|
||||||
|
|
||||||
[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.
|
[^1]: 以上引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。
|
||||||
|
|
||||||
```markdown {filename=Markdown}
|
```markdown {filename=Markdown}
|
||||||
> Don't communicate by sharing memory, share memory by communicating.<br>
|
> 不要通过共享内存来通信，而要通过通信来共享内存。<br>
|
||||||
> — <cite>Rob Pike[^1]</cite>
|
> — <cite>Rob Pike[^1]</cite>
|
||||||
|
|
||||||
[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.
|
[^1]: 以上引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。
|
||||||
|
```
|
||||||
|
|
||||||
|
### 提示框
|
||||||
|
|
||||||
|
{{< new-feature version="v0.9.0" >}}
|
||||||
|
|
||||||
|
提示框是基于引用块语法的 Markdown 扩展，可用于强调关键信息。
|
||||||
|
支持 [GitHub 风格的提示框](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)。
|
||||||
|
请确保您使用的是最新版本的 Hextra 和 [Hugo v0.134.0](https://github.com/gohugoio/hugo/releases/tag/v0.134.0) 或更高版本。
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> 用户应该知道的有用信息，即使是在浏览内容时。
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> 帮助用户更好地或更轻松地完成任务的建议。
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
> 用户需要了解的关键信息，以实现他们的目标。
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> 需要用户立即注意的紧急信息，以避免问题。
|
||||||
|
|
||||||
|
> [!CAUTION]
|
||||||
|
> 关于某些操作的风险或负面结果的建议。
|
||||||
|
|
||||||
|
```markdown {filename=Markdown}
|
||||||
|
> [!NOTE]
|
||||||
|
> 用户应该知道的有用信息，即使是在浏览内容时。
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> 帮助用户更好地或更轻松地完成任务的建议。
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
> 用户需要了解的关键信息，以实现他们的目标。
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> 需要用户立即注意的紧急信息，以避免问题。
|
||||||
|
|
||||||
|
> [!CAUTION]
|
||||||
|
> 关于某些操作的风险或负面结果的建议。
|
||||||
```
|
```
|
||||||
|
|
||||||
### 表格
|
### 表格
|
||||||
|
|
||||||
表格并非核心 Markdown 规范，但 Hugo 支持开箱即用的表格：
|
表格不是 Markdown 核心规范的一部分，但 Hugo 默认支持它们。
|
||||||
|
|
||||||
| Name | Age |
|
| 姓名 | 年龄 |
|
||||||
|--------|------|
|
|--------|------|
|
||||||
| Bob | 27 |
|
| Bob | 27 |
|
||||||
| Alice | 23 |
|
| Alice | 23 |
|
||||||
|
|
||||||
```markdown {filename=Markdown}
|
```markdown {filename=Markdown}
|
||||||
| Name | Age |
|
| 姓名 | 年龄 |
|
||||||
|--------|------|
|
|--------|------|
|
||||||
| Bob | 27 |
|
| Bob | 27 |
|
||||||
| Alice | 23 |
|
| Alice | 23 |
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Markdown 表格中的内联
|
#### 表格中的内联 Markdown
|
||||||
|
|
||||||
| Italics | Bold | Code |
|
| 斜体 | 粗体 | 代码 |
|
||||||
| -------- | -------- | ------ |
|
| -------- | -------- | ------ |
|
||||||
| *italics* | **bold** | `code` |
|
| *斜体* | **粗体** | `代码` |
|
||||||
|
|
||||||
```markdown {filename=Markdown}
|
```markdown {filename=Markdown}
|
||||||
| Italics | Bold | Code |
|
| 斜体 | 粗体 | 代码 |
|
||||||
| -------- | -------- | ------ |
|
| -------- | -------- | ------ |
|
||||||
| *italics* | **bold** | `code` |
|
| *斜体* | **粗体** | `代码` |
|
||||||
```
|
```
|
||||||
|
|
||||||
### 代码块
|
### 代码块
|
||||||
|
|
||||||
{{< cards >}}
|
{{< cards >}}
|
||||||
{{< card link="../../guide/syntax-highlighting" title="Syntax Highlighting" icon="sparkles" >}}
|
{{< card link="../../guide/syntax-highlighting" title="语法高亮" icon="sparkles" >}}
|
||||||
{{< /cards >}}
|
{{< /cards >}}
|
||||||
|
|
||||||
### 列表
|
### 列表
|
||||||
|
|
||||||
#### 有序列表
|
#### 有序列表
|
||||||
|
|
||||||
1. First item
|
1. 第一项
|
||||||
2. Second item
|
2. 第二项
|
||||||
3. Third item
|
3. 第三项
|
||||||
|
|
||||||
```markdown {filename=Markdown}
|
```markdown {filename=Markdown}
|
||||||
1. First item
|
1. 第一项
|
||||||
2. Second item
|
2. 第二项
|
||||||
3. Third item
|
3. 第三项
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 无序列表
|
#### 无序列表
|
||||||
|
|
||||||
* List item
|
* 列表项
|
||||||
* Another item
|
* 另一个项
|
||||||
* And another item
|
* 再一个项
|
||||||
|
|
||||||
```markdown {filename=Markdown}
|
```markdown {filename=Markdown}
|
||||||
* List item
|
* 列表项
|
||||||
* Another item
|
* 另一个项
|
||||||
* And another item
|
* 再一个项
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 嵌套列表
|
#### 嵌套列表
|
||||||
|
|
||||||
* Fruit
|
* 水果
|
||||||
* Apple
|
* 苹果
|
||||||
* Orange
|
* 橙子
|
||||||
* Banana
|
* 香蕉
|
||||||
* Dairy
|
* 乳制品
|
||||||
* Milk
|
* 牛奶
|
||||||
* Cheese
|
* 奶酪
|
||||||
|
|
||||||
```markdown {filename=Markdown}
|
```markdown {filename=Markdown}
|
||||||
* Fruit
|
* 水果
|
||||||
* Apple
|
* 苹果
|
||||||
* Orange
|
* 橙子
|
||||||
* Banana
|
* 香蕉
|
||||||
* Dairy
|
* 乳制品
|
||||||
* Milk
|
* 牛奶
|
||||||
* Cheese
|
* 奶酪
|
||||||
```
|
```
|
||||||
|
|
||||||
### 图片
|
### 图片
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
```markdown {filename=Markdown}
|
```markdown {filename=Markdown}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
带有标题：
|
带标题：
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
```markdown {filename=Markdown}
|
```markdown {filename=Markdown}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 配置
|
## 配置
|
||||||
|
|
||||||
Hugo 使用 [Goldmark](https://github.com/yuin/goldmark) 解析 Markdown。
|
Hugo 使用 [Goldmark](https://github.com/yuin/goldmark) 进行 Markdown 解析。
|
||||||
Markdown 渲染可以在 `hugo.yaml` 中的 `markup.goldmark` 中配置。以下是Hextra的默认配置：
|
Markdown 渲染可以在 `hugo.yaml` 中的 `markup.goldmark` 下进行配置。
|
||||||
|
以下是 Hextra 的默认配置：
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
markup:
|
markup:
|
||||||
@ -145,11 +186,11 @@ markup:
|
|||||||
noClasses: false
|
noClasses: false
|
||||||
```
|
```
|
||||||
|
|
||||||
如需了解更多选项，转至 [Configure Markup](https://gohugo.io/getting-started/configuration-markup/)。
|
更多配置选项，请参阅 Hugo 文档中的 [配置 Markup](https://gohugo.io/getting-started/configuration-markup/)。
|
||||||
|
|
||||||
## 参考资料
|
## 学习资源
|
||||||
|
|
||||||
* [Markdown Guide](https://www.markdownguide.org/)
|
* [Markdown 指南](https://www.markdownguide.org/)
|
||||||
* [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
|
* [Markdown 速查表](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
|
||||||
* [Markdown Tutorial](https://www.markdowntutorial.com/)
|
* [Markdown 教程](https://www.markdowntutorial.com/)
|
||||||
* [Markdown Reference](https://commonmark.org/help/)
|
* [Markdown 参考](https://commonmark.org/help/)
|
||||||
@ -1,13 +1,13 @@
|
|||||||
---
|
---
|
||||||
title: 目录结构
|
title: 组织文件
|
||||||
weight: 1
|
weight: 1
|
||||||
prev: /docs/guide
|
prev: /docs/guide
|
||||||
---
|
---
|
||||||
|
|
||||||
## 目录结构
|
## 目录结构
|
||||||
|
|
||||||
默认情况下，Hugo 在 `content` 目录中搜索 Markdown 文件，目录的结构决定了网站的最终输出结构。
|
默认情况下，Hugo 会在 `content` 目录中查找 Markdown 文件，目录的结构决定了网站最终的输出结构。
|
||||||
以示例网站为例：
|
以本网站为例：
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
@ -29,7 +29,7 @@ prev: /docs/guide
|
|||||||
{{< /filetree/folder >}}
|
{{< /filetree/folder >}}
|
||||||
{{< /filetree/container >}}
|
{{< /filetree/container >}}
|
||||||
|
|
||||||
每个 `_index.md` 文件都是相应部分的索引页，其他 Markdown 文件则是常规页面。
|
每个 `_index.md` 文件都是对应部分的索引页面。其他 Markdown 文件则是常规页面。
|
||||||
|
|
||||||
```
|
```
|
||||||
content
|
content
|
||||||
@ -45,21 +45,143 @@ content
|
|||||||
└── post-1.md // <- /blog/post-1/
|
└── post-1.md // <- /blog/post-1/
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## 布局
|
||||||
|
|
||||||
|
Hextra 为不同类型的内容提供了三种布局：
|
||||||
|
|
||||||
|
| 布局 | 目录 | 特性 |
|
||||||
|
| :-------- | :------------------ | :----------------------------------------------------------- |
|
||||||
|
| `docs` | `content/docs/` | 适合结构化文档，与本部分相同。 |
|
||||||
|
| `blog` | `content/blog/` | 用于博客文章，包含列表和详细文章视图。 |
|
||||||
|
| `default` | 其他所有目录 | 单页文章视图，无侧边栏。 |
|
||||||
|
|
||||||
|
要将某个部分自定义为与内置布局相同的行为，可以在该部分的 `_index.md` 的前言中指定所需的类型。
|
||||||
|
|
||||||
|
```yaml {filename="content/my-docs/_index.md"}
|
||||||
|
---
|
||||||
|
title: 我的文档
|
||||||
|
cascade:
|
||||||
|
type: docs
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
上述示例配置确保 `content/my-docs/` 中的内容文件默认会被视为文档（`docs` 类型）。
|
||||||
|
|
||||||
## 侧边栏导航
|
## 侧边栏导航
|
||||||
|
|
||||||
侧边栏导航是根据内容组织的字母顺序自动生成的。要手动配置侧边栏顺序，可以在 Markdown 文件的 `frontmatter ` 中使用 `weight` 配置。
|
侧边栏导航会根据内容组织按字母顺序自动生成。要手动配置侧边栏顺序，可以在 Markdown 文件的前言中使用 `weight` 参数。
|
||||||
|
|
||||||
```yaml {filename="content/docs/guide/_index.md"}
|
```yaml {filename="content/docs/guide/_index.md"}
|
||||||
---
|
---
|
||||||
title: Guide
|
title: 指南
|
||||||
weight: 2
|
weight: 2
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
{{< callout emoji="ℹ️">}}
|
{{< callout emoji="ℹ️">}}
|
||||||
建议侧边栏不要太深。如果内容太多，请考虑 **将它们分成多个部分**。
|
建议不要让侧边栏过深。如果你有很多内容，考虑**将它们分成多个部分**。
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
|
## 面包屑导航
|
||||||
|
|
||||||
|
面包屑导航会根据 `/content` 的目录结构自动生成。
|
||||||
|
|
||||||
|
例如，考虑上面[展示的目录结构](#directory-structure)。根据该结构，页面 `/docs/guide/organize-files/` 顶部的面包屑导航会自动显示如下：
|
||||||
|
|
||||||
|
```
|
||||||
|
文档 > 指南 > 组织文件
|
||||||
|
```
|
||||||
|
|
||||||
|
### 自定义面包屑链接标题
|
||||||
|
|
||||||
|
默认情况下，每个面包屑链接是根据页面的 `title` 参数生成的。你可以通过指定 `linkTitle` 来自定义。
|
||||||
|
|
||||||
|
例如，如果我们希望面包屑显示为 `Foo Bar` 而不是 `Organize Files`：
|
||||||
|
|
||||||
|
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||||
|
---
|
||||||
|
linkTitle: Foo Bar
|
||||||
|
title: 组织文件
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
现在会生成以下面包屑：
|
||||||
|
```
|
||||||
|
文档 > 指南 > Foo Bar
|
||||||
|
```
|
||||||
|
|
||||||
|
### 隐藏面包屑
|
||||||
|
|
||||||
|
你可以通过在页面的前言中指定 `breadcrumbs: false` 来完全隐藏面包屑：
|
||||||
|
|
||||||
|
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||||
|
---
|
||||||
|
breadcrumbs: false
|
||||||
|
title: 组织文件
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
## 配置内容目录
|
## 配置内容目录
|
||||||
|
|
||||||
如果需要为的内容使用不同的目录，可以在站点配置文件中设置 [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) 来实现。
|
默认情况下，Hugo 使用根目录 `content/` 来构建网站。
|
||||||
|
如果你需要使用不同的目录来存放内容，例如 `docs/`，可以通过在站点配置文件 `hugo.yaml` 中设置 [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) 参数来实现。
|
||||||
|
|
||||||
|
## 添加图片
|
||||||
|
|
||||||
|
添加图片的最简单方法是将图片文件放在与 Markdown 文件相同的目录中。
|
||||||
|
例如，将图片文件 `image.png` 与 `my-page.md` 文件放在一起：
|
||||||
|
|
||||||
|
{{< filetree/container >}}
|
||||||
|
{{< filetree/folder name="content" >}}
|
||||||
|
{{< filetree/folder name="docs" >}}
|
||||||
|
{{< filetree/file name="my-page.md" >}}
|
||||||
|
{{< filetree/file name="image.png" >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/container >}}
|
||||||
|
|
||||||
|
然后，我们可以使用以下 Markdown 语法将图片添加到内容中：
|
||||||
|
|
||||||
|
```markdown {filename="content/docs/my-page.md"}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
我们还可以利用 Hugo 的 [页面包][page-bundles] 功能将图片文件与 Markdown 文件一起组织。为此，将 `my-page.md` 文件转换为目录 `my-page`，并将内容放入名为 `index.md` 的文件中，然后将图片文件放入 `my-page` 目录中：
|
||||||
|
|
||||||
|
{{< filetree/container >}}
|
||||||
|
{{< filetree/folder name="content" >}}
|
||||||
|
{{< filetree/folder name="docs" >}}
|
||||||
|
{{< filetree/folder name="my-page" >}}
|
||||||
|
{{< filetree/file name="index.md" >}}
|
||||||
|
{{< filetree/file name="image.png" >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/container >}}
|
||||||
|
|
||||||
|
```markdown {filename="content/docs/my-page/index.md"}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
或者，我们也可以将图片文件放在 `static` 目录中，这样所有页面都可以访问这些图片：
|
||||||
|
|
||||||
|
{{< filetree/container >}}
|
||||||
|
{{< filetree/folder name="static" >}}
|
||||||
|
{{< filetree/folder name="images" >}}
|
||||||
|
{{< filetree/file name="image.png" >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< filetree/folder name="content" >}}
|
||||||
|
{{< filetree/folder name="docs" >}}
|
||||||
|
{{< filetree/file name="my-page.md" >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/container >}}
|
||||||
|
|
||||||
|
注意，图片路径以斜杠 `/` 开头，并且相对于静态目录：
|
||||||
|
|
||||||
|
```markdown {filename="content/docs/my-page.md"}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles
|
||||||
@ -5,15 +5,25 @@ prev: /docs/guide/diagrams
|
|||||||
next: /docs/guide/shortcodes/callout
|
next: /docs/guide/shortcodes/callout
|
||||||
---
|
---
|
||||||
|
|
||||||
[Hugo 短代码](https://gohugo.io/content-management/shortcodes/) 是你的内容文件中调用内置或自定义模板的简单片段。
|
[Hugo 短代码](https://gohugo.io/content-management/shortcodes/)是内容文件中的简单片段，用于调用内置或自定义模板。
|
||||||
|
|
||||||
Hextra 提供了一系列美观的短代码以增强你的内容。
|
Hextra 提供了一系列精美的短代码，以增强您的内容。
|
||||||
|
|
||||||
{{< cards >}}
|
{{< cards >}}
|
||||||
{{< card link="callout" title="注意事项" icon="warning" >}}
|
{{< card link="callout" title="标注" icon="warning" >}}
|
||||||
{{< card link="cards" title="卡片" icon="card" >}}
|
{{< card link="cards" title="卡片" icon="card" >}}
|
||||||
|
{{< card link="details" title="详情" icon="chevron-right" >}}
|
||||||
{{< card link="filetree" title="文件树" icon="folder-tree" >}}
|
{{< card link="filetree" title="文件树" icon="folder-tree" >}}
|
||||||
{{< card link="icon" title="图标" icon="badge-check" >}}
|
{{< card link="icon" title="图标" icon="badge-check" >}}
|
||||||
{{< card link="steps" title="步骤" icon="one" >}}
|
{{< card link="steps" title="步骤" icon="one" >}}
|
||||||
{{< card link="tabs" title="标签" icon="collection" >}}
|
{{< card link="tabs" title="标签页" icon="collection" >}}
|
||||||
{{< /cards >}}
|
{{< /cards >}}
|
||||||
|
|
||||||
|
<div style="padding-top:4rem"></div>
|
||||||
|
|
||||||
|
Hugo 和 Hextra 提供的其他短代码：
|
||||||
|
|
||||||
|
{{< cards >}}
|
||||||
|
{{< card link="jupyter" title="Jupyter 笔记本" icon="jupyter" tag="alpha" >}}
|
||||||
|
{{< card link="others" title="其他" icon="view-grid" >}}
|
||||||
|
{{< /cards >}}
|
||||||
@ -1,78 +1,83 @@
|
|||||||
---
|
---
|
||||||
title: 标注
|
title: 提示框组件
|
||||||
|
linkTitle: 提示框
|
||||||
aliases:
|
aliases:
|
||||||
- callouts
|
- 提示框
|
||||||
prev: /docs/guide/shortcodes
|
prev: /docs/guide/shortcodes
|
||||||
---
|
---
|
||||||
|
|
||||||
向读者显示重要信息的内置组件。
|
一个内置组件，用于向读者展示重要信息。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
## Example
|
> [!NOTE]
|
||||||
|
> 自 [v0.9.0](https://github.com/imfing/hextra/releases/tag/v0.9.0) 起支持 [GitHub 风格的提醒](../../markdown#alerts)。
|
||||||
|
> 它利用 Markdown 语法来渲染提示框，确保内容具有更好的可移植性和可读性。
|
||||||
|
|
||||||
|
## 示例
|
||||||
|
|
||||||
{{< callout emoji="👾">}}
|
{{< callout emoji="👾">}}
|
||||||
**标注**是一段旨在吸引注意力的短文本
|
**提示框** 是一段简短的文本，旨在吸引注意力。
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
{{< callout type="info" >}}
|
{{< callout type="info" >}}
|
||||||
**标注**是一段旨在吸引注意力的短文本。
|
**提示框** 是一段简短的文本，旨在吸引注意力。
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
{{< callout type="warning" >}}
|
{{< callout type="warning" >}}
|
||||||
**标注**是一段旨在吸引注意力的短文本。
|
**提示框** 是一段简短的文本，旨在吸引注意力。
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
{{< callout type="error" >}}
|
{{< callout type="error" >}}
|
||||||
**标注**是一段旨在吸引注意力的短文本。
|
**提示框** 是一段简短的文本，旨在吸引注意力。
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
## Usage
|
## 用法
|
||||||
|
|
||||||
### Default
|
### 默认
|
||||||
|
|
||||||
{{< callout emoji="🌐">}}
|
{{< callout emoji="🌐">}}
|
||||||
Hugo 可用于创建各种网站，包括博客、作品集、文档网站等
|
Hugo 可用于创建各种类型的网站，包括博客、作品集、文档站点等。
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
{{</* callout emoji="🌐" */>}}
|
{{</* callout emoji="🌐" */>}}
|
||||||
Hugo 可用于创建各种网站，包括博客、作品集、文档网站等
|
Hugo 可用于创建各种类型的网站，包括博客、作品集、文档站点等。
|
||||||
{{</* /callout */>}}
|
{{</* /callout */>}}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Info
|
### 信息
|
||||||
|
|
||||||
{{< callout type="info" >}}
|
{{< callout type="info" >}}
|
||||||
请访问 GitHub 查看最新版本
|
请访问 GitHub 查看最新版本。
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
{{</* callout type="info" */>}}
|
{{</* callout type="info" */>}}
|
||||||
请访问 GitHub 查看最新版本
|
请访问 GitHub 查看最新版本。
|
||||||
{{</* /callout */>}}
|
{{</* /callout */>}}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Warning
|
### 警告
|
||||||
|
|
||||||
{{< callout type="warning" >}}
|
{{< callout type="warning" >}}
|
||||||
该 API 将在下一版本中弃用
|
此 API 将在下一个版本中弃用。
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
{{</* callout type="warning" */>}}
|
{{</* callout type="warning" */>}}
|
||||||
**标注**是一段旨在吸引注意力的简短文字
|
**提示框** 是一段简短的文本，旨在吸引注意力。
|
||||||
{{</* /callout */>}}
|
{{</* /callout */>}}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Error
|
### 错误
|
||||||
|
|
||||||
{{< callout type="error" >}}
|
{{< callout type="error" >}}
|
||||||
出问题了，要爆炸了
|
出错了，系统即将崩溃。
|
||||||
{{< /callout >}}
|
{{< /callout >}}
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
{{</* callout type="error" */>}}
|
{{</* callout type="error" */>}}
|
||||||
出问题了，要爆炸了
|
出错了，系统即将崩溃。
|
||||||
{{</* /callout */>}}
|
{{</* /callout */>}}
|
||||||
```
|
```
|
||||||
@ -1,65 +1,115 @@
|
|||||||
---
|
---
|
||||||
title: 卡片
|
title: 卡片组件
|
||||||
linkTitle: Cards
|
linkTitle: 卡片
|
||||||
---
|
---
|
||||||
|
|
||||||
## 示例
|
## 示例
|
||||||
|
|
||||||
{{< cards >}}
|
{{< cards >}}
|
||||||
{{< card link="../callout" title="Callout" icon="warning" >}}
|
{{< card link="../callout" title="提示框" icon="warning" >}}
|
||||||
{{< card link="/" title="No Icon" >}}
|
{{< card link="../callout" title="带标签的卡片" icon="tag" tag="自定义标签">}}
|
||||||
|
{{< card link="/" title="无图标" >}}
|
||||||
{{< /cards >}}
|
{{< /cards >}}
|
||||||
|
|
||||||
{{< cards >}}
|
{{< cards >}}
|
||||||
{{< card link="/" title="Image Card" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash Landscape" >}}
|
{{< card link="/" title="图片卡片" image="https://github.com/user-attachments/assets/71b7e3ec-1a8d-4582-b600-5425c6cc0407" subtitle="网络图片" >}}
|
||||||
{{< card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." >}}
|
{{< card link="/" title="本地图片" image="/images/card-image-unprocessed.jpg" subtitle="静态目录下的原始图片。" >}}
|
||||||
{{< card link="/" title="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" >}}
|
{{< card link="/" title="本地图片" image="images/space.jpg" subtitle="资源目录下的图片，由 Hugo 处理。" method="Resize" options="600x q80 webp" >}}
|
||||||
{{< /cards >}}
|
{{< /cards >}}
|
||||||
|
|
||||||
## 使用
|
## 用法
|
||||||
|
|
||||||
```
|
```
|
||||||
{{</* cards */>}}
|
{{</* cards */>}}
|
||||||
{{</* card link="../callout" title="Callout" icon="warning" */>}}
|
{{</* card link="../callout" title="提示框" icon="warning" */>}}
|
||||||
{{</* card link="/" title="No Icon" */>}}
|
{{</* card link="../callout" title="带标签的卡片" icon="tag" tag= "自定义标签" */>}}
|
||||||
|
{{</* card link="/" title="无图标" */>}}
|
||||||
{{</* /cards */>}}
|
{{</* /cards */>}}
|
||||||
```
|
```
|
||||||
|
|
||||||
```
|
```
|
||||||
{{</* cards */>}}
|
{{</* cards */>}}
|
||||||
{{</* card link="/" title="Image Card" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash Landscape" */>}}
|
{{</* card link="/" title="图片卡片" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash 风景" */>}}
|
||||||
{{</* card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." */>}}
|
{{</* card link="/" title="本地图片" image="/images/card-image-unprocessed.jpg" subtitle="静态目录下的原始图片。" */>}}
|
||||||
{{</* card link="/" title="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" */>}}
|
{{</* card link="/" title="本地图片" image="images/space.jpg" subtitle="资源目录下的图片，由 Hugo 处理。" method="Resize" options="600x q80 webp" */>}}
|
||||||
{{</* /cards */>}}
|
{{</* /cards */>}}
|
||||||
```
|
```
|
||||||
|
|
||||||
## 卡片参数
|
## 卡片参数
|
||||||
|
|
||||||
| Parameter | Description |
|
| 参数 | 描述 |
|
||||||
|----------- |---------------------------------------|
|
|----------- |-----------------------------------------------------------------|
|
||||||
| `link` | URL（内部或外部） |
|
| `link` | URL（内部或外部）。 |
|
||||||
| `title` | 卡片的标题 |
|
| `title` | 卡片的标题。 |
|
||||||
| `subtitle` | 字幕标题（支持 Markdown） |
|
| `subtitle` | 卡片的副标题（支持 Markdown）。 |
|
||||||
| `icon` | 图标的名称 |
|
| `icon` | 图标的名称。 |
|
||||||
|
| `tag` | 标签中的文本。 |
|
||||||
|
| `tagColor` | 标签的颜色：`gray`（默认）、`yellow`、`red` 和 `blue`。 |
|
||||||
|
|
||||||
|
## 图片卡片
|
||||||
|
|
||||||
## Image Card
|
此外，卡片支持通过以下参数添加图片并进行处理：
|
||||||
|
|
||||||
此外，该卡还支持通过以下参数添加图像和处理：
|
| 参数 | 描述 |
|
||||||
|
|-----------|--------------------------------------|
|
||||||
|
| `image` | 指定卡片的图片 URL。 |
|
||||||
|
| `method` | 设置 Hugo 的图片处理方法。 |
|
||||||
|
| `options` | 配置 Hugo 的图片处理选项。 |
|
||||||
|
|
||||||
| Parameter | Description |
|
卡片支持三种类型的图片：
|
||||||
|----------- |---------------------------------------------|
|
|
||||||
| `image` | 指定卡片的图像 URL. |
|
|
||||||
| `method` | 设置 Hugo 的图像处理方法。 |
|
|
||||||
| `options` | 配置 Hugo 的图像处理选项。|
|
|
||||||
|
|
||||||
卡片支持三种图像：
|
1. 远程图片：`image` 参数中的完整 URL。
|
||||||
|
2. 静态图片：使用 Hugo `static/` 目录中的相对路径。
|
||||||
|
3. 处理后的图片：使用 Hugo `assets/` 目录中的相对路径。
|
||||||
|
|
||||||
1. 远程图片：完整网址应放置在 image 参数中
|
Hextra 在构建时自动检测是否需要图片处理，并应用 `options` 参数或默认设置（Resize，800x，质量 80，WebP 格式）。
|
||||||
2. 静态图片：使用 Hugo 的 static/ 目录中的相对路径
|
目前支持以下 `method`：`Resize`、`Fit`、`Fill` 和 `Crop`。
|
||||||
3. 处理过的图片：使用 Hugo 的 assets/ 目录中的相对路径
|
|
||||||
|
|
||||||
Hextra 在构建过程中会自动检测图片是否需要处理，并根据需要应用 options 参数或默认设置（缩放，800x，质量 80，WebP 格式）。
|
有关 Hugo 内置图片处理命令、方法和选项的更多信息，请参阅其[图片处理文档](https://gohugo.io/content-management/image-processing/)。
|
||||||
|
|
||||||
它目前支持以下处理方法：Resize（缩放）、Fit（适应）、Fill（填充）和 Crop（裁剪）。
|
## 标签
|
||||||
|
|
||||||
有关 Hugo 内置图像处理命令、方法和选项的更多信息，请参阅他们的 [Image Processing Documentation](https://gohugo.io/content-management/image-processing/).
|
卡片支持添加标签，这对于显示额外的状态信息非常有用。
|
||||||
|
|
||||||
|
{{< cards >}}
|
||||||
|
{{< card link="../callout" title="带默认标签的卡片" tag="标签文本" >}}
|
||||||
|
{{< card link="../callout" title="带错误标签的卡片" tag="标签文本" tagType="error" >}}
|
||||||
|
{{< card link="../callout" title="带信息标签的卡片" tag="标签文本" tagType="info" >}}
|
||||||
|
{{< card link="../callout" title="带警告标签的卡片" tag="标签文本" tagType="warning" >}}
|
||||||
|
{{< card link="/" title="图片卡片" image="https://github.com/user-attachments/assets/71b7e3ec-1a8d-4582-b600-5425c6cc0407" subtitle="网络图片" tag="标签文本" tagType="error" >}}
|
||||||
|
{{< /cards >}}
|
||||||
|
|
||||||
|
```
|
||||||
|
{{</* cards */>}}
|
||||||
|
{{</* card link="../callout" title="带默认标签颜色的卡片" tag="标签文本" */>}}
|
||||||
|
{{</* card link="../callout" title="带红色标签的卡片" tag="标签文本" tagType="error" */>}}
|
||||||
|
{{</* card link="../callout" title="带蓝色标签的卡片" tag="标签文本" tagType="info" */>}}
|
||||||
|
{{</* card link="../callout" title="带黄色标签的卡片" tag="标签文本" tagType="warning" */>}}
|
||||||
|
{{</* /cards */>}}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 列数
|
||||||
|
|
||||||
|
您可以通过将 `cols` 参数传递给 `cards` 短代码来指定卡片的最大列数。请注意，在较小的屏幕上，列仍会折叠。
|
||||||
|
|
||||||
|
{{< cards cols="1" >}}
|
||||||
|
{{< card link="/" title="顶部卡片" >}}
|
||||||
|
{{< card link="/" title="底部卡片" >}}
|
||||||
|
{{< /cards >}}
|
||||||
|
|
||||||
|
{{< cards cols="2" >}}
|
||||||
|
{{< card link="/" title="左侧卡片" >}}
|
||||||
|
{{< card link="/" title="右侧卡片" >}}
|
||||||
|
{{< /cards >}}
|
||||||
|
|
||||||
|
```
|
||||||
|
{{</* cards cols="1" */>}}
|
||||||
|
{{</* card link="/" title="顶部卡片" */>}}
|
||||||
|
{{</* card link="/" title="底部卡片" */>}}
|
||||||
|
{{</* /cards */>}}
|
||||||
|
|
||||||
|
{{</* cards cols="2" */>}}
|
||||||
|
{{</* card link="/" title="左侧卡片" */>}}
|
||||||
|
{{</* card link="/" title="右侧卡片" */>}}
|
||||||
|
{{</* /cards */>}}
|
||||||
|
```
|
||||||
@ -2,42 +2,42 @@
|
|||||||
title: 详情
|
title: 详情
|
||||||
---
|
---
|
||||||
|
|
||||||
用于显示可折叠内容的内置组件。
|
一个内置组件，用于显示可折叠的内容。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
## 示例
|
## 示例
|
||||||
|
|
||||||
{{% details title="Details" %}}
|
{{% details title="详情" %}}
|
||||||
|
|
||||||
这是细节的内容
|
这是详情的内容。
|
||||||
|
|
||||||
Markdown is **supported**.
|
支持 **Markdown**。
|
||||||
|
|
||||||
{{% /details %}}
|
{{% /details %}}
|
||||||
|
|
||||||
{{% details title="Click me to reveal" closed="true" %}}
|
{{% details title="点击我展开" closed="true" %}}
|
||||||
|
|
||||||
默认情况下这将被隐藏
|
默认情况下，这部分内容会被隐藏。
|
||||||
|
|
||||||
{{% /details %}}
|
{{% /details %}}
|
||||||
|
|
||||||
## Usage
|
## 用法
|
||||||
|
|
||||||
````markdown
|
````markdown
|
||||||
{{%/* details title="Details" */%}}
|
{{%/* details title="详情" */%}}
|
||||||
|
|
||||||
这是细节的内容
|
这是详情的内容。
|
||||||
|
|
||||||
**支持** Markdown
|
支持 **Markdown**。
|
||||||
|
|
||||||
{{%/* /details */%}}
|
{{%/* /details */%}}
|
||||||
````
|
````
|
||||||
|
|
||||||
````markdown
|
````markdown
|
||||||
{{%/* details title="Click me to reveal" closed="true" */%}}
|
{{%/* details title="点击我展开" closed="true" */%}}
|
||||||
|
|
||||||
默认情况下这将被隐藏
|
默认情况下，这部分内容会被隐藏。
|
||||||
|
|
||||||
{{%/* /details */%}}
|
{{%/* /details */%}}
|
||||||
````
|
````
|
||||||
@ -1,5 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: 文件树
|
title: 文件树组件
|
||||||
|
linkTitle: 文件树
|
||||||
---
|
---
|
||||||
|
|
||||||
## 示例
|
## 示例
|
||||||
@ -30,4 +31,4 @@ title: 文件树
|
|||||||
{{</* /filetree/folder */>}}
|
{{</* /filetree/folder */>}}
|
||||||
{{</* filetree/file name="hugo.toml" */>}}
|
{{</* filetree/file name="hugo.toml" */>}}
|
||||||
{{</* /filetree/container */>}}
|
{{</* /filetree/container */>}}
|
||||||
```
|
```
|
||||||
@ -2,13 +2,13 @@
|
|||||||
title: 图标
|
title: 图标
|
||||||
---
|
---
|
||||||
|
|
||||||
要内联使用此短代码，需要在配置中启用内联短代码：
|
要在行内使用此短代码，需要在配置中启用行内短代码：
|
||||||
|
|
||||||
```yaml {filename="hugo.yaml"}
|
```yaml {filename="hugo.yaml"}
|
||||||
enableInlineShortcodes: true
|
enableInlineShortcodes: true
|
||||||
```
|
```
|
||||||
|
|
||||||
可用图标列表可以在以下位置找到 [`data/icons.yaml`](https://github.com/imfing/hextra/blob/main/data/icons.yaml).
|
可用图标的列表可以在 [`data/icons.yaml`](https://github.com/imfing/hextra/blob/main/data/icons.yaml) 中找到。
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
@ -25,17 +25,17 @@ enableInlineShortcodes: true
|
|||||||
{{</* icon "github" */>}}
|
{{</* icon "github" */>}}
|
||||||
```
|
```
|
||||||
|
|
||||||
[Heroicons](https://v1.heroicons.com/) v1 轮廓图标开箱即用
|
[Heroicons](https://v1.heroicons.com/) v1 的轮廓图标默认可用。
|
||||||
|
|
||||||
### 如何添加自己的图标
|
### 如何添加自定义图标
|
||||||
|
|
||||||
创建 `data/icons.yaml` 文件，然后按以下格式添加您自己的 SVG 图标：
|
创建 `data/icons.yaml` 文件，然后按照以下格式添加自定义的 SVG 图标：
|
||||||
|
|
||||||
```yaml {filename="data/icons.yaml"}
|
```yaml {filename="data/icons.yaml"}
|
||||||
your-icon: <svg>your icon svg content</svg>
|
your-icon: <svg>your icon svg content</svg>
|
||||||
```
|
```
|
||||||
|
|
||||||
然后可以在短代码中使用它，如下所示：
|
然后可以在短代码中这样使用：
|
||||||
|
|
||||||
```
|
```
|
||||||
{{</* icon "your-icon" */>}}
|
{{</* icon "your-icon" */>}}
|
||||||
@ -43,4 +43,4 @@ your-icon: <svg>your icon svg content</svg>
|
|||||||
{{</* card icon="your-icon" */>}}
|
{{</* card icon="your-icon" */>}}
|
||||||
```
|
```
|
||||||
|
|
||||||
提示：[Iconify Design](https://iconify.design/) 是为您的网站查找 SVG 图标的好地方
|
提示：[Iconify Design](https://iconify.design/) 是寻找网站 SVG 图标的好地方。
|
||||||
79
exampleSite/content/docs/guide/shortcodes/jupyter.zh-cn.md
Normal file
79
exampleSite/content/docs/guide/shortcodes/jupyter.zh-cn.md
Normal file
@ -0,0 +1,79 @@
|
|||||||
|
---
|
||||||
|
title: "Jupyter Notebook 组件"
|
||||||
|
linktitle: "Jupyter Notebook"
|
||||||
|
math: true
|
||||||
|
sidebar:
|
||||||
|
exclude: true
|
||||||
|
---
|
||||||
|
|
||||||
|
{{< callout >}}实验性功能：通过短代码嵌入 Jupyter Notebook。请注意，并非所有单元格类型都受支持。{{< /callout >}}
|
||||||
|
|
||||||
|
[Jupyter Notebook](https://jupyter.org/) 是 [Project Jupyter](https://jupyter.org/) 的一个语言无关的 HTML 笔记本应用程序。它允许你创建和共享包含实时代码、方程、可视化和叙述性文本的文档。
|
||||||
|
|
||||||
|
<!--more-->
|
||||||
|
|
||||||
|
## 使用方法
|
||||||
|
|
||||||
|
### 使用本地笔记本
|
||||||
|
|
||||||
|
要使用 Jupyter Notebook 短代码，你需要在项目中有一个 Jupyter Notebook 文件。类似于如何[添加图片](../../organize-files#add-images)到项目中，你可以将 Jupyter Notebooks 添加到 `assets` 文件夹。
|
||||||
|
|
||||||
|
{{< filetree/container >}}
|
||||||
|
{{< filetree/folder name="assets" >}}
|
||||||
|
{{< filetree/file name="notebook.ipynb" >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< filetree/folder name="content" >}}
|
||||||
|
{{< filetree/folder name="docs" >}}
|
||||||
|
{{< filetree/file name="my-page.md" >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/container >}}
|
||||||
|
|
||||||
|
使用 `jupyter` 短代码将 Jupyter Notebook 包含在页面中：
|
||||||
|
|
||||||
|
```markdown {filename="content/docs/my-page.md"}
|
||||||
|
---
|
||||||
|
title: 我的页面
|
||||||
|
math: true
|
||||||
|
---
|
||||||
|
|
||||||
|
{{%/* jupyter "notebook.ipynb" */%}}
|
||||||
|
```
|
||||||
|
|
||||||
|
或者，你可以利用 Hugo 的[页面包][page-bundles]功能将 Jupyter Notebooks 与 Markdown 文件一起组织。
|
||||||
|
|
||||||
|
{{< filetree/container >}}
|
||||||
|
{{< filetree/folder name="content" >}}
|
||||||
|
{{< filetree/folder name="docs" >}}
|
||||||
|
{{< filetree/folder name="my-page" >}}
|
||||||
|
{{< filetree/file name="index.md" >}}
|
||||||
|
{{< filetree/file name="notebook.ipynb" >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/folder >}}
|
||||||
|
{{< /filetree/container >}}
|
||||||
|
|
||||||
|
```markdown {filename="content/docs/my-page/index.md"}
|
||||||
|
---
|
||||||
|
title: 我的页面
|
||||||
|
math: true
|
||||||
|
---
|
||||||
|
|
||||||
|
{{%/* jupyter "notebook.ipynb" */%}}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 使用远程笔记本
|
||||||
|
|
||||||
|
你也可以通过提供笔记本文件的 URL 来使用远程笔记本。例如，要在页面中包含 [What is the Jupyter Notebook](https://github.com/jupyter/notebook/blob/main/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb) 笔记本，你可以使用以下短代码：
|
||||||
|
|
||||||
|
```
|
||||||
|
{{%/* jupyter "https://raw.githubusercontent.com/jupyter/notebook/main/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb" */%}}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 示例笔记本
|
||||||
|
|
||||||
|
{{< callout type="info" >}}以下是包含在项目 assets 文件夹中的笔记本文件示例。{{< /callout >}}
|
||||||
|
|
||||||
|
{{% jupyter "example.ipynb" %}}
|
||||||
|
|
||||||
|
[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles
|
||||||
77
exampleSite/content/docs/guide/shortcodes/others.zh-cn.md
Normal file
77
exampleSite/content/docs/guide/shortcodes/others.zh-cn.md
Normal file
@ -0,0 +1,77 @@
|
|||||||
|
---
|
||||||
|
title: 其他短代码
|
||||||
|
linkTitle: 其他
|
||||||
|
sidebar:
|
||||||
|
exclude: true
|
||||||
|
---
|
||||||
|
|
||||||
|
{{< callout emoji="ℹ️" >}}
|
||||||
|
其中一些是 Hugo 内置的短代码。
|
||||||
|
这些短代码被认为不太稳定，可能会随时更改。
|
||||||
|
{{< /callout >}}
|
||||||
|
|
||||||
|
## 徽章
|
||||||
|
|
||||||
|
```
|
||||||
|
{{</* badge "徽章" */>}}
|
||||||
|
```
|
||||||
|
|
||||||
|
结果：
|
||||||
|
|
||||||
|
{{< badge "徽章" >}}
|
||||||
|
|
||||||
|
变体：
|
||||||
|
|
||||||
|
```
|
||||||
|
{{</* badge content="信息" type="info" */>}}
|
||||||
|
{{</* badge content="警告" type="warning" */>}}
|
||||||
|
{{</* badge content="错误" type="error" */>}}
|
||||||
|
```
|
||||||
|
|
||||||
|
结果：
|
||||||
|
|
||||||
|
{{< badge content="信息" type="info" >}}
|
||||||
|
{{< badge content="警告" type="warning" >}}
|
||||||
|
{{< badge content="错误" type="error" >}}
|
||||||
|
|
||||||
|
带链接和图标：
|
||||||
|
|
||||||
|
```
|
||||||
|
{{</* badge content="发布" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
|
||||||
|
```
|
||||||
|
|
||||||
|
结果：
|
||||||
|
|
||||||
|
{{< badge content="发布" link="https://github.com/imfing/hextra/releases" icon="github" >}}
|
||||||
|
|
||||||
|
## YouTube
|
||||||
|
|
||||||
|
嵌入 YouTube 视频。
|
||||||
|
|
||||||
|
```
|
||||||
|
{{</* youtube 视频ID */>}}
|
||||||
|
```
|
||||||
|
|
||||||
|
结果：
|
||||||
|
|
||||||
|
{{< youtube id=dQw4w9WgXcQ loading=lazy >}}
|
||||||
|
|
||||||
|
更多信息，请参阅 [Hugo 的 YouTube 短代码](https://gohugo.io/content-management/shortcodes/#youtube)。
|
||||||
|
|
||||||
|
## PDF
|
||||||
|
|
||||||
|
使用 PDF 短代码，您可以在内容中嵌入 PDF 文件。
|
||||||
|
|
||||||
|
```
|
||||||
|
{{</* pdf "https://example.com/sample.pdf" */>}}
|
||||||
|
```
|
||||||
|
|
||||||
|
您也可以将 PDF 文件放在项目目录中并使用相对路径。
|
||||||
|
|
||||||
|
```
|
||||||
|
{{</* pdf "path/to/file.pdf" */>}}
|
||||||
|
```
|
||||||
|
|
||||||
|
示例：
|
||||||
|
|
||||||
|
{{< pdf "https://upload.wikimedia.org/wikipedia/commons/1/13/Example.pdf" >}}
|
||||||
@ -2,7 +2,7 @@
|
|||||||
title: 步骤
|
title: 步骤
|
||||||
---
|
---
|
||||||
|
|
||||||
A built-in component to display a series of steps.
|
一个内置组件，用于显示一系列步骤。
|
||||||
|
|
||||||
## 示例
|
## 示例
|
||||||
|
|
||||||
@ -23,20 +23,25 @@ A built-in component to display a series of steps.
|
|||||||
{{% /steps %}}
|
{{% /steps %}}
|
||||||
|
|
||||||
|
|
||||||
## 使用
|
## 用法
|
||||||
|
|
||||||
将 Markdown h3 标题放入 `steps` 短代码中。
|
{{< callout emoji="ℹ️" >}}
|
||||||
|
请注意，此短代码**仅适用于 Markdown 内容**。
|
||||||
|
如果将 HTML 内容或其他短代码作为步骤内容，可能无法按预期渲染。
|
||||||
|
{{< /callout >}}
|
||||||
|
|
||||||
|
在 `steps` 短代码中放置 Markdown 的 h3 标题。
|
||||||
|
|
||||||
```
|
```
|
||||||
{{%/* steps */%}}
|
{{%/* steps */%}}
|
||||||
|
|
||||||
### Step 1
|
### 第一步
|
||||||
|
|
||||||
This is the first step.
|
这是第一步。
|
||||||
|
|
||||||
### Step 2
|
### 第二步
|
||||||
|
|
||||||
This is the second step.
|
这是第二步。
|
||||||
|
|
||||||
{{%/* /steps */%}}
|
{{%/* /steps */%}}
|
||||||
```
|
```
|
||||||
@ -7,54 +7,54 @@ next: /docs/guide/deploy-site
|
|||||||
|
|
||||||
{{< tabs items="JSON,YAML,TOML" >}}
|
{{< tabs items="JSON,YAML,TOML" >}}
|
||||||
|
|
||||||
{{< tab >}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{< /tab >}}
|
{{< tab >}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{< /tab >}}
|
||||||
{{< tab >}}**YAML**: YAML is a human-readable data serialization language.{{< /tab >}}
|
{{< tab >}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{< /tab >}}
|
||||||
{{< tab >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}}
|
{{< tab >}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{< /tab >}}
|
||||||
|
|
||||||
{{< /tabs >}}
|
{{< /tabs >}}
|
||||||
|
|
||||||
## 使用
|
## 用法
|
||||||
|
|
||||||
### 默认情况下
|
### 默认
|
||||||
|
|
||||||
```
|
```
|
||||||
{{</* tabs items="JSON,YAML,TOML" */>}}
|
{{</* tabs items="JSON,YAML,TOML" */>}}
|
||||||
|
|
||||||
{{</* tab */>}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{</* /tab */>}}
|
{{</* tab */>}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{</* /tab */>}}
|
||||||
{{</* tab */>}}**YAML**: YAML is a human-readable data serialization language.{{</* /tab */>}}
|
{{</* tab */>}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{</* /tab */>}}
|
||||||
{{</* tab */>}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{</* /tab */>}}
|
{{</* tab */>}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{</* /tab */>}}
|
||||||
|
|
||||||
{{</* /tabs */>}}
|
{{</* /tabs */>}}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 指定索引
|
### 指定选中索引
|
||||||
|
|
||||||
使用 `defaultIndex` 属性指定选定的选项卡。索引从 0 开始。
|
使用 `defaultIndex` 属性来指定选中的标签页。索引从 0 开始。
|
||||||
|
|
||||||
```
|
```
|
||||||
{{</* tabs items="JSON,YAML,TOML" defaultIndex="1" */>}}
|
{{</* tabs items="JSON,YAML,TOML" defaultIndex="1" */>}}
|
||||||
|
|
||||||
{{</* tab */>}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{</* /tab */>}}
|
{{</* tab */>}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{</* /tab */>}}
|
||||||
{{</* tab */>}}**YAML**: YAML is a human-readable data serialization language.{{</* /tab */>}}
|
{{</* tab */>}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{</* /tab */>}}
|
||||||
{{</* tab */>}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{</* /tab */>}}
|
{{</* tab */>}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{</* /tab */>}}
|
||||||
|
|
||||||
{{</* /tabs */>}}
|
{{</* /tabs */>}}
|
||||||
```
|
```
|
||||||
|
|
||||||
默认为 `YAML`
|
默认情况下，`YAML` 标签页将被选中。
|
||||||
|
|
||||||
{{< tabs items="JSON,YAML,TOML" defaultIndex="1" >}}
|
{{< tabs items="JSON,YAML,TOML" defaultIndex="1" >}}
|
||||||
|
|
||||||
{{< tab >}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{< /tab >}}
|
{{< tab >}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{< /tab >}}
|
||||||
{{< tab >}}**YAML**: YAML is a human-readable data serialization language.{{< /tab >}}
|
{{< tab >}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{< /tab >}}
|
||||||
{{< tab >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}}
|
{{< tab >}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{< /tab >}}
|
||||||
|
|
||||||
{{< /tabs >}}
|
{{< /tabs >}}
|
||||||
|
|
||||||
|
|
||||||
### 使用 Markdown
|
### 使用 Markdown
|
||||||
|
|
||||||
还支持包括代码块的 Markdown 语法：
|
Markdown 语法，包括代码块，也受支持：
|
||||||
|
|
||||||
````
|
````
|
||||||
{{</* tabs items="JSON,YAML,TOML" */>}}
|
{{</* tabs items="JSON,YAML,TOML" */>}}
|
||||||
@ -65,7 +65,7 @@ next: /docs/guide/deploy-site
|
|||||||
```
|
```
|
||||||
{{</* /tab */>}}
|
{{</* /tab */>}}
|
||||||
|
|
||||||
... add other tabs similarly
|
... 类似地添加其他标签页
|
||||||
|
|
||||||
{{</* /tabs */>}}
|
{{</* /tabs */>}}
|
||||||
````
|
````
|
||||||
@ -90,4 +90,4 @@ next: /docs/guide/deploy-site
|
|||||||
```
|
```
|
||||||
{{< /tab >}}
|
{{< /tab >}}
|
||||||
|
|
||||||
{{< /tabs >}}
|
{{< /tabs >}}
|
||||||
@ -1,10 +1,10 @@
|
|||||||
---
|
---
|
||||||
title: "代码高亮"
|
title: "语法高亮"
|
||||||
weight: 3
|
weight: 3
|
||||||
---
|
---
|
||||||
|
|
||||||
Hugo 使用 [Chroma](https://github.com/alecthomas/chroma)，一种纯 Golang 实现的代码高亮渲染器。
|
Hugo 使用 [Chroma](https://github.com/alecthomas/chroma)，这是一个用纯 Go 编写的通用语法高亮器，用于语法高亮。
|
||||||
建议对 Markdown 内容中的代码块使用反引号，例如：
|
建议在 Markdown 内容中使用反引号来标记代码块。例如：
|
||||||
|
|
||||||
<!--more-->
|
<!--more-->
|
||||||
|
|
||||||
@ -15,18 +15,18 @@ def say_hello():
|
|||||||
```
|
```
|
||||||
````
|
````
|
||||||
|
|
||||||
将呈现为：
|
将会渲染为：
|
||||||
|
|
||||||
```python
|
```python
|
||||||
def say_hello():
|
def say_hello():
|
||||||
print("Hello!")
|
print("Hello!")
|
||||||
```
|
```
|
||||||
|
|
||||||
## 特性
|
## 功能
|
||||||
|
|
||||||
### 文件名
|
### 文件名
|
||||||
|
|
||||||
要向代码块添加文件名或标题，请设置 `filename`：
|
要为代码块添加文件名或标题，请设置 `filename` 属性：
|
||||||
|
|
||||||
````markdown {filename="Markdown"}
|
````markdown {filename="Markdown"}
|
||||||
```python {filename="hello.py"}
|
```python {filename="hello.py"}
|
||||||
@ -40,9 +40,27 @@ def say_hello():
|
|||||||
print("Hello!")
|
print("Hello!")
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 文件链接
|
||||||
|
|
||||||
|
{{< new-feature version="v0.9.2" >}}
|
||||||
|
|
||||||
|
你可以使用 `base_url` 属性提供一个基础 URL，它将与文件名结合生成一个链接。
|
||||||
|
|
||||||
|
如果文件名指定了文件在基础路径中的位置，则可以包含相对路径。
|
||||||
|
|
||||||
|
````markdown {filename="Markdown"}
|
||||||
|
```go {base_url="https://github.com/imfing/hextra/blob/main/",filename="exampleSite/hugo.work"}
|
||||||
|
go 1.20
|
||||||
|
```
|
||||||
|
````
|
||||||
|
|
||||||
|
```go {base_url="https://github.com/imfing/hextra/blob/main/",filename="exampleSite/hugo.work"}
|
||||||
|
go 1.20
|
||||||
|
```
|
||||||
|
|
||||||
### 行号
|
### 行号
|
||||||
|
|
||||||
如需设置行号，将 `linenos` 设置为 `table`，并将 `linenostart` 设置为起始行号：
|
要设置行号，请将 `linenos` 属性设置为 `table`，并可选地设置 `linenostart` 为起始行号：
|
||||||
|
|
||||||
````markdown {filename="Markdown"}
|
````markdown {filename="Markdown"}
|
||||||
```python {linenos=table,linenostart=42}
|
```python {linenos=table,linenostart=42}
|
||||||
@ -58,7 +76,7 @@ def say_hello():
|
|||||||
|
|
||||||
### 高亮行
|
### 高亮行
|
||||||
|
|
||||||
显示高亮行，设置 `hl_lines` 为行号：
|
要高亮特定行，请将 `hl_lines` 属性设置为行号列表：
|
||||||
|
|
||||||
````markdown {filename="Markdown"}
|
````markdown {filename="Markdown"}
|
||||||
```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}
|
```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}
|
||||||
@ -78,12 +96,19 @@ def main():
|
|||||||
say_hello()
|
say_hello()
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
### 复制按钮
|
### 复制按钮
|
||||||
|
|
||||||
默认情况下，代码块复制按钮已自动启用。
|
默认情况下，代码块启用了复制按钮。可以通过修改站点配置文件来更改其行为：
|
||||||
|
|
||||||
|
```yaml {linenos=table,linenostart=42,filename="hugo.yaml"}
|
||||||
|
params:
|
||||||
|
highlight:
|
||||||
|
copy:
|
||||||
|
enable: true
|
||||||
|
# hover | always
|
||||||
|
display: hover
|
||||||
|
```
|
||||||
|
|
||||||
## 支持的编程语言
|
## 支持的语言
|
||||||
|
|
||||||
如需了解支持的编程语言，转至 [Chroma's documentation](https://github.com/alecthomas/chroma#supported-languages)。
|
有关支持的语言列表，请参阅 [Chroma 文档](https://github.com/alecthomas/chroma#supported-languages)。
|
||||||
Loading…
x
Reference in New Issue
Block a user