diff --git a/exampleSite/content/docs/advanced/comments.zh-cn.md b/exampleSite/content/docs/advanced/comments.zh-cn.md new file mode 100644 index 00000000..9a506581 --- /dev/null +++ b/exampleSite/content/docs/advanced/comments.zh-cn.md @@ -0,0 +1,39 @@ +--- +title: 评论系统 +linkTitle: Comments +--- + +Hextra 支持在你的网站中添加评论系统。 +目前已经支持 [giscus](https://giscus.app/). + + + +## giscus + +[giscus](https://giscus.app/) 是由 [GitHub Discussions](https://docs.github.com/en/discussions)驱动的评论系统。Giscus 免费并且开源。 + +如需启用 Giscus, 你需要在配置文件中添加以下内容: + +```yaml {filename="hugo.yaml"} +params: + comments: + enable: false + type: giscus + + giscus: + repo: + repoId: + category: + categoryId: +``` + +Giscus 配置可以参考 [giscus.app](https://giscus.app/),还可以在那里找到更多详细信息。 + +可以在 front matter 中启用或禁用特定页面的评论: + +```yaml {filename="content/docs/about.md"} +--- +title: About +comments: true +--- +``` diff --git a/exampleSite/content/docs/advanced/customization.zh-cn.md b/exampleSite/content/docs/advanced/customization.zh-cn.md index eeec03d1..bb3f9d79 100644 --- a/exampleSite/content/docs/advanced/customization.zh-cn.md +++ b/exampleSite/content/docs/advanced/customization.zh-cn.md @@ -30,10 +30,10 @@ Hextra 在 `hugo.yaml` 中提供了一些自定义选项来配置主题。 ### 代码高亮 -代码高亮风格的详细信息可在 [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html) 中找到。 可以使用以下命令生成样式表: +代码高亮风格的详细信息可在 [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html) 中找到。可以使用以下命令生成样式表: -```bash -$ hugo gen chromastyles --style=github +```shell +hugo gen chromastyles --style=github ``` 可将生成的样式添加到自定义 CSS 文件中以覆盖默认代码高亮样式。 @@ -55,4 +55,4 @@ layouts/partials/custom/head-end.html ## 进一步定制 Hextra -没有找到你想修改的东西?在 GitHub 上[创建 Issues](https://github.com/imfing/hextra/issues) 或为 Hextra 贡献你的智慧! +没有找到你想修改的内容?在 GitHub 上[创建 Discussion](https://github.com/imfing/hextra/discussions) 或为 Hextra 贡献你的智慧! diff --git a/exampleSite/content/docs/getting-started.zh-cn.md b/exampleSite/content/docs/getting-started.zh-cn.md index a18818a8..1e4c8130 100644 --- a/exampleSite/content/docs/getting-started.zh-cn.md +++ b/exampleSite/content/docs/getting-started.zh-cn.md @@ -26,23 +26,21 @@ prev: /docs [Hugo 模块](https://gohugo.io/hugo-modules/)是管理 Hugo 主题的推荐方式。要使用 Hugo 模块,我们需要安装 [Git](https://git-scm.com/) 和 [Go](https://go.dev/)。 -{{% steps %}} - ### 初始化 Hugo 站点 -```bash -$ hugo new site my-site --format=yaml +```shell +hugo new site my-site --format=yaml ``` -### 通过模块配置 Hextra 主题 +### 通过 Hugo Module 安装 ```shell # 初始化 Hugo 模块 -$ cd my-site -$ hugo mod init github.com/username/my-site +cd my-site +hugo mod init github.com/username/my-site # 添加 Hextra -$ hugo mod get github.com/imfing/hextra +hugo mod get github.com/imfing/hextra ``` 编辑 `hugo.yaml` 以启用 Hextra: @@ -53,31 +51,92 @@ module: - 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 -$ hugo new content/_index.md -$ hugo new content/docs/_index.md +hugo new content/_index.md +hugo new content/docs/_index.md ``` ### 在本地预览站点 ```shell -$ hugo server --buildDrafts --disableFastRender +hugo server --buildDrafts --disableFastRender ``` 瞧!你现在可以在 `http://localhost:1313/` 看到你的新站点。 {{% /steps %}} + + + +使用 [CI/CD](https://en.wikipedia.org/wiki/CI/CD) 进行部署时,必须确保在运行 `hugo` 命令之前执行以下命令。 + +```shell +git submodule update --init +``` + +如果不运行此命令,theme 中将不会存在 Hextra 文件,进而导致构建失败。 + + +{{% details title="如何更新主题?" %}} + +如需把项目中所有的 Hugo Modules 都升级到最新,在终端中运行此命令: + +```shell +hugo mod get -u +``` + +如需把 Hextra 升级到[最新的发行版本](https://github.com/imfing/hextra/releases), 在终端中运行此命令: + +```shell +hugo mod get -u github.com/imfing/hextra +``` + +如果你需要获得更多信息,参见 [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/#update-all-modules). + +{{% /details %}} + ## 接下来 -你可以探索以下部分来添加更多内容: +探索这些文档以便添加更多内容: {{< cards >}} - {{< card link="../guide/organize-files" title="目录结构" icon="document-duplicate" >}} - {{< card link="../guide/configuration" title="配置文件指南" icon="adjustments" >}} + {{< card link="../guide/organize-files" title="Organize Files" icon="document-duplicate" >}} + {{< card link="../guide/configuration" title="Configuration" icon="adjustments" >}} {{< card link="../guide/markdown" title="Markdown" icon="markdown" >}} {{< /cards >}} diff --git a/exampleSite/content/docs/guide/configuration.zh-cn.md b/exampleSite/content/docs/guide/configuration.zh-cn.md index 6b0c58ef..f2d6c187 100644 --- a/exampleSite/content/docs/guide/configuration.zh-cn.md +++ b/exampleSite/content/docs/guide/configuration.zh-cn.md @@ -38,7 +38,7 @@ menu: icon: github ``` -有几种不同类型的菜单项: +有几种不同类型的菜单项: 1. Link to a page in the site with `pageRef` ```yaml @@ -122,3 +122,118 @@ title: Configuration editURL: "https://example.com/edit/this/page" --- ``` +## Footer + +### 版权声明 + +如需修改网站页脚中显示的版权文本,您需要创建一个名为“i18n/en.yaml”的文件。 +在此文件中,填写新的版权文本,像这样: + +```yaml {filename="i18n/en.yaml"} +copyright: "© 2023 YOUR TEXT HERE" +``` +你可以在 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): + +{{< filetree/container >}} + {{< filetree/folder name="static" >}} + {{< filetree/file name="android-chrome-192x192.png" >}} + {{< filetree/file name="android-chrome-512x512.png" >}} + {{< filetree/file name="apple-touch-icon.png" >}} + {{< filetree/file name="favicon-16x16.png" >}} + {{< filetree/file name="favicon-32x32.png" >}} + {{< filetree/file name="favicon-dark.svg" >}} + {{< filetree/file name="favicon.ico" >}} + {{< filetree/file name="favicon.svg" >}} + {{< filetree/file name="site.webmanifest" >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +在您的项目中包含 `favicon.ico` 和 `favicon.svg` 文件,以确保网站的网站图标正确显示。 + +虽然 `favicon.ico` 通常适用于较旧的浏览器,但 `favicon.svg` 受到现代浏览器的支持,所以更现代的做法是添加 `favicon-dark.svg` 以便在黑暗模式下提供较好的体验体验。 + +请随意使用 [favicon.io](https://favicon.io/) 或 [favycon](https://github.com/ruisaraiva19/favycon) 等工具来生成这些图标。 + +### 颜色主题配置 + +使用`theme`设置来配置默认主题模式和切换按钮,允许访问者在浅色或深色模式之间切换。 + +```yaml {filename="hugo.yaml"} +params: + theme: + # light | dark | system + default: system + displayToggle: true +``` + +`theme.default` 的可选项: + +- `light` - 仅使用浅色模式 +- `dark` - 仅使用神色模式 +- `system` - 跟随系统 + +`theme.displayToggle` 控制显示用于更改主题的切换按钮。 +当设置为“true”时,访问者可以在浅色或深色模式之间切换,覆盖默认设置。 + +### 页宽 + +页面的宽度可以通过配置文件中的`params.page.width`参数来调整: + +```yaml {filename="hugo.yaml"} +params: + page: + # full (100%), wide (90rem), normal (1280px) + width: wide +``` + +有三个可选项:`full`, `wide`, and `normal`. 默认的页宽模式是 `normal`. + +同样的,导航栏和 `footer` 的宽度也可通过 `params.navbar.width` 和 `params.footer.width` 调整。 + +### 搜索 + +默认情况下启用由 [FlexSearch](https://github.com/nextapps-de/flexsearch) 提供全文搜索。 +要自定义搜索索引,请在配置文件中设置 `params.search.flexsearch.index` : + +```yaml {filename="hugo.yaml"} +params: + # Search + search: + enable: true + type: flexsearch + + flexsearch: + # index page by: content | summary | heading | title + index: content +``` +`flexsearch.index` 的可选项: + +- `content` - 全内容搜索 +- `summary` - 概述 [Hugo Content Summaries](https://gohugo.io/content-management/summaries/) +- `heading` - 一级和二级标题 +- `title` - 仅搜索标题 + +要从搜索索引中排除页面,更改 front matter 中的 `excludeSearch: true`: + +```yaml {filename="content/docs/guide/configuration.md"} +--- +title: Configuration +excludeSearch: true +--- +``` + +### Google Analytics + +要启用 [Google Analytics](https://marketingplatform.google.com/about/analytics/),设置 `services.googleAnalytics.ID`: + +```yaml {filename="hugo.yaml"} +services: + googleAnalytics: + ID: G-MEASUREMENT_ID +```