From 14b2c546fd5e70b5c32fa9d699e070e73aa80c97 Mon Sep 17 00:00:00 2001 From: rpeng Date: Wed, 10 Jan 2024 02:33:45 +0800 Subject: [PATCH] docs: Add Chinese documentation for github page. --- .../config/_default/languages.zh-CN.toml | 25 ++ exampleSite/config/_default/menus.zh-CN.toml | 56 ++++ exampleSite/content/_index.zh-cn.md | 29 ++ exampleSite/content/docs/_index.zh-cn.md | 22 ++ .../advanced-customisation/index.zh-cn.md | 182 ++++++++++ .../content/docs/configuration/index.zh-cn.md | 185 ++++++++++ .../docs/content-examples/index.zh-cn.md | 316 ++++++++++++++++++ .../content/docs/front-matter/index.zh-cn.md | 51 +++ .../docs/getting-started/index.zh-cn.md | 244 ++++++++++++++ .../docs/homepage-layout/index.zh-cn.md | 53 +++ .../docs/hosting-deployment/index.zh-cn.md | 148 ++++++++ .../content/docs/installation/index.zh-cn.md | 173 ++++++++++ .../content/docs/partials/index.zh-cn.md | 114 +++++++ .../content/docs/shortcodes/index.zh-cn.md | 236 +++++++++++++ .../content/docs/version-2/_index.zh-cn.md | 97 ++++++ .../docs/version-2/upgrade/index.zh-cn.md | 223 ++++++++++++ exampleSite/content/samples/_index.zh-cn.md | 18 + .../content/samples/charts/index.zh-cn.md | 85 +++++ .../diagrams-flowcharts/index.zh-cn.md | 92 +++++ .../content/samples/emoji/index.zh-cn.md | 19 ++ .../content/samples/external/index.zh-cn.md | 14 + .../content/samples/icons/index.zh-cn.md | 84 +++++ .../content/samples/markdown/index.zh-cn.md | 149 +++++++++ .../mathematical-notation/index.zh-cn.md | 46 +++ .../samples/placeholder-text/index.zh-cn.md | 39 +++ .../samples/rich-content/index.zh-cn.md | 37 ++ exampleSite/content/tags/_index.zh-CN.md | 9 + .../content/tags/advanced/_index.zh-CN.md | 7 + exampleSite/content/users/index.zh-cn.md | 70 ++++ 29 files changed, 2823 insertions(+) create mode 100644 exampleSite/config/_default/languages.zh-CN.toml create mode 100644 exampleSite/config/_default/menus.zh-CN.toml create mode 100644 exampleSite/content/_index.zh-cn.md create mode 100644 exampleSite/content/docs/_index.zh-cn.md create mode 100644 exampleSite/content/docs/advanced-customisation/index.zh-cn.md create mode 100644 exampleSite/content/docs/configuration/index.zh-cn.md create mode 100644 exampleSite/content/docs/content-examples/index.zh-cn.md create mode 100644 exampleSite/content/docs/front-matter/index.zh-cn.md create mode 100644 exampleSite/content/docs/getting-started/index.zh-cn.md create mode 100644 exampleSite/content/docs/homepage-layout/index.zh-cn.md create mode 100644 exampleSite/content/docs/hosting-deployment/index.zh-cn.md create mode 100644 exampleSite/content/docs/installation/index.zh-cn.md create mode 100644 exampleSite/content/docs/partials/index.zh-cn.md create mode 100644 exampleSite/content/docs/shortcodes/index.zh-cn.md create mode 100644 exampleSite/content/docs/version-2/_index.zh-cn.md create mode 100644 exampleSite/content/docs/version-2/upgrade/index.zh-cn.md create mode 100644 exampleSite/content/samples/_index.zh-cn.md create mode 100644 exampleSite/content/samples/charts/index.zh-cn.md create mode 100644 exampleSite/content/samples/diagrams-flowcharts/index.zh-cn.md create mode 100644 exampleSite/content/samples/emoji/index.zh-cn.md create mode 100644 exampleSite/content/samples/external/index.zh-cn.md create mode 100644 exampleSite/content/samples/icons/index.zh-cn.md create mode 100644 exampleSite/content/samples/markdown/index.zh-cn.md create mode 100644 exampleSite/content/samples/mathematical-notation/index.zh-cn.md create mode 100644 exampleSite/content/samples/placeholder-text/index.zh-cn.md create mode 100644 exampleSite/content/samples/rich-content/index.zh-cn.md create mode 100644 exampleSite/content/tags/_index.zh-CN.md create mode 100644 exampleSite/content/tags/advanced/_index.zh-CN.md create mode 100644 exampleSite/content/users/index.zh-cn.md diff --git a/exampleSite/config/_default/languages.zh-CN.toml b/exampleSite/config/_default/languages.zh-CN.toml new file mode 100644 index 00000000..31cba1cf --- /dev/null +++ b/exampleSite/config/_default/languages.zh-CN.toml @@ -0,0 +1,25 @@ +languageCode = "zh-CN" +languageName = "简体中文" +languageDirection = "ltr" +weight = 2 + +title = "Congo" +copyright = "© 2023 Congo contributors" + +[params] + dateFormat = "2006年1月2日" + + mainSections = ["samples"] + description = "一款基于Tailwindcss的强大且轻量的Hugo主题" + +[author] + name = "Congo" + image = "img/author.jpg" + headline = "非凡的主题！" + bio = "这是一个作者简介示例，虽然这里有一张狗的库存照片，但实际上这篇文章是由人创建的。 :dog:" + links = [ + { x-twitter = "https://twitter.com/" }, + { facebook = "https://facebook.com/" }, + { linkedin = "https://linkedin.com/" }, + { youtube = "https://youtube.com/" }, + ] diff --git a/exampleSite/config/_default/menus.zh-CN.toml b/exampleSite/config/_default/menus.zh-CN.toml new file mode 100644 index 00000000..9b585851 --- /dev/null +++ b/exampleSite/config/_default/menus.zh-CN.toml @@ -0,0 +1,56 @@ +# -- Main Menu -- +# The main menu is displayed in the header at the top of the page. +# Acceptable parameters are name, pageRef, page, url, title, weight. +# +# The simplest menu configuration is to provide: +# name = The name to be displayed for this menu link +# pageRef = The identifier of the page or section to link to +# +# By default the menu is ordered alphabetically. This can be +# overridden by providing a weight value. The menu will then be +# ordered by weight from lowest to highest. + +[[main]] + name = "文档" + pageRef = "docs" + weight = 10 + +[[main]] + name = "示例" + pageRef = "samples" + weight = 20 + +[[main]] + name = "用户" + pageRef = "users" + weight = 30 + +[[main]] + name = "GitHub" + url = "https://github.com/jpanther/congo" + weight = 40 + [main.params] + icon = "github" + showName = false + target = "_blank" + +[[main]] + identifier = "搜索" + weight = 99 + [main.params] + action = "search" + +[[main]] + identifier = "语言" + weight = 100 + [main.params] + action = "locale" + +# -- Footer Menu -- +# The footer menu is displayed at the bottom of the page, just before +# the copyright notice. Configure as per the main menu above. + +# [[footer]] +# name = "标签" +# pageRef = "tags" +# weight = 10 diff --git a/exampleSite/content/_index.zh-cn.md b/exampleSite/content/_index.zh-cn.md new file mode 100644 index 00000000..35f52bc2 --- /dev/null +++ b/exampleSite/content/_index.zh-cn.md @@ -0,0 +1,29 @@ +--- +title: "欢迎使用Congo! :tada:" +description: "这是一个基于Hugo的主题Congo示例。" +--- + +{{< lead >}} +一款基于Tailwindcss的强大且轻量Hugo主题 +{{< /lead >}} + +这是一个完全使用Congo构建的演示站点。它还包含一个完整的 [主题文档]({{< ref "docs" >}}) 集。Congo是灵活的，非常适合静态基于页面的内容（就像你看到的这个演示）或具有最新文章的传统博客。 + +
+ + {{< icon "triangle-exclamation" >}} + + + 这是一个 page 布局的示例. + + +
+ +{{< figure src="festivities.svg" class="m-auto mt-6 max-w-prose" >}} + +探索 [示例页面]({{< ref "samples" >}}) 以感受Congo的强大功能。如果你喜欢该主题，请在 [Github](https://github.com/jpanther/congo) 上查看该项目，或阅读 [安装指南]({{< ref "docs/installation" >}}) 开始使用。 diff --git a/exampleSite/content/docs/_index.zh-cn.md b/exampleSite/content/docs/_index.zh-cn.md new file mode 100644 index 00000000..a2158e5e --- /dev/null +++ b/exampleSite/content/docs/_index.zh-cn.md @@ -0,0 +1,22 @@ +--- +title: "文档" +description: "了解如何使用Congo及其功能。" + +cascade: + showDate: false + showAuthor: false + showSummary: true + invertPagination: true +--- + +{{< lead >}} +简单而强大。了解如何使用Congo及其功能。 +{{< /lead >}} + +![Screenshots of Congo on an iPhone, iPad and MacBook](screenshot.png) + +该部分包含关于Congo的所有必要信息。如果您是新手，请查看 [安装]({{< ref "docs/installation" >}}) 指南以开始，或访问 [示例]({{< ref "samples" >}}) 部分查看Congo的功能。 + +特别感谢 [Katerina Limpitsouni](https://ninalimpi.com) 为这些文档中使用的出色插图！ + +--- diff --git a/exampleSite/content/docs/advanced-customisation/index.zh-cn.md b/exampleSite/content/docs/advanced-customisation/index.zh-cn.md new file mode 100644 index 00000000..92b71eb7 --- /dev/null +++ b/exampleSite/content/docs/advanced-customisation/index.zh-cn.md @@ -0,0 +1,182 @@ +--- +title: "高级定制" +date: 2020年8月8日 +draft: false +description: "学习如何手动构建 Congo。" +summary: "Congo 支持高级定制，包括修改底层的 Tailwind 配置，手动构建主题以及提供自定义 CSS。" +slug: "advanced-customisation" +tags: ["高级", "CSS", "文档"] +--- + +有许多方法可以对 Congo 进行高级更改。阅读以下内容，了解可以定制的内容以及实现所需结果的最佳方式。 + +如果您需要进一步的建议，请在 [GitHub 讨论区](https://github.com/jpanther/congo/discussions) 上发表您的问题。 + +## Hugo 项目结构 + +在深入了解之前，首先简要介绍一下[Hugo 项目结构](https://gohugo.io/getting-started/directory-structure/)和管理内容以及主题定制的最佳实践。 + +{{< alert >}} +**总结：**永远不要直接编辑主题文件。只在 Hugo 项目的子目录中进行定制，而不要在主题目录本身进行定制。 +{{< /alert >}} + +Congo 的构建旨在充分利用所有标准 Hugo 实践。它被设计为允许定制和覆盖主题的所有方面，而无需更改任何核心主题文件。这样一来，您可以在完全控制网站的外观和感觉的同时，获得无缝的升级体验。 + +为了实现这一点，您永远不应直接调整主题文件中的任何文件。无论您是使用 Hugo 模块安装，作为 git 子模块或手动将主题包含在您的 `themes/` 目录中，都应始终保持这些文件不变。 + +调整任何主题行为的正确方式是使用 Hugo 强大的[文件查找顺序](https://gohugo.io/templates/lookup-order/)。总体而言，查找顺序确保您在项目目录中包含的任何文件将自动优先于任何主题文件。 + +例如，如果您想要覆盖 Congo 中的主文章模板，您只需创建自己的 `layouts/_default/single.html` 文件并将其放置在项目的根目录。该文件将覆盖主题中的 `single.html`，而无需更改主题本身。这适用于任何主题文件 - HTML 模板、局部、短代码、配置文件、数据、资产等。 + +只要遵循这个简单的做法，您就始终能够更新主题（或测试不同的主题版本），而不必担心会丢失任何自定义更改。 + +## 颜色方案 + +Congo 默认提供了许多颜色方案。要更改基本的颜色方案，您可以设置 `colorScheme` 主题参数。请参阅 [入门指南]({{< ref "getting-started#colour-schemes" >}}) 部分，了解内置方案的更多信息。 + +除了默认方案之外，您还可以创建自己的方案，并根据自己的喜好重新设计整个网站。通过在 `assets/css/schemes/` 文件夹中放置 `.css` 文件来创建方案。创建文件后，只需在主题配置中按名称引用即可。 + +Congo 定义了一个贯穿整个主题使用的三种颜色的调色板。这三种颜色分别被定义为 `neutral`、`primary` 和 `secondary` 变体，每种颜色包含十个色调。 + +由于 Tailwind CSS 3.0 使用不透明度计算颜色值的方式，方案中指定的颜色需要[符合特定格式](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo)，即提供红色、绿色和蓝色颜色值。 + +```css +:root { + --color-primary-500: 139, 92, 246; +} +``` + +此示例为 `primary-500` 颜色定义了一个 CSS 变量，其红色值为 `139`，绿色值为 `92`，蓝色值为 `246`。 + +使用现有的主题样式表作为模板。您可以自定义自己的颜色，但是为了一些灵感，请查看官方的 [Tailwind 颜色调色板参考](https://tailwindcss.com/docs/customizing-colors#color-palette-reference)。 + +## 覆盖样式表 + +有时您需要添加自定义样式以为自己的 HTML 元素设置样式。Congo 提供了允许您在自己的 CSS 样式表中覆盖默认样式的场景。只需在项目的 `assets/css/` 文件夹中创建一个 `custom.css` 文件。 + +`custom.css` 文件将由 Hugo 进行最小化，并在所有其他主题样式之后自动加载，这意味着自定义文件中的任何内容都将覆盖默认值。 + +### 调整字体大小 + +更改网站的字体大小是覆盖默认样式表的一个示例。Congo 使此变得简单，因为它在整个主题中使用了从基本 HTML 字体大小派生的缩放字体大小。默认情况下，Tailwind 将默认大小设置为 `12pt`，但可以更改为您喜欢的任何值。 + +使用上述[说明]({{< ref "#overriding-the-stylesheet" >}})创建一个 `custom.css` 文件，并添加以下 CSS 声明： + +```css +/* Increase the default font size */ +html { + font-size: 13pt; +} +``` + +只需更改此一个值，您网站上的所有字体大小就会调整为匹配这个新大小。因此，要增加使用的整体字体大小，请将值设置为大于 `12pt`。同样，要减小字体大小，请将值设置为小于 `12pt`。 + +## 从源代码构建主题 CSS + +如果您想进行重大更改，可以利用 Tailwind CSS 的 JIT 编译器从头开始重新构建整个主题 CSS。如果您想要调整 Tailwind 配置或向主样式表添加额外的 Tailwind 类，这将非常有用。 + +{{< alert >}} +**注意：** 手动构建主题仅适用于高级用户。 +{{< /alert >}} + +让我们逐步了解构建 Tailwind CSS 的过程。 + +### Tailwind 配置 + +为了生成一个仅包含实际使用的 Tailwind 类的 CSS 文件，JIT 编译器需要扫描所有 HTML 模板和 Markdown 内容文件，以检查标记中存在哪些样式。编译器通过查看主题目录根目录中包含的 `tailwind.config.js` 文件来执行此操作： + +```js +// themes/congo/tailwind.config.js + +module.exports = { + content: [ + "./layouts/**/*.html", + "./content/**/*.{html,md}", + "./themes/congo/layouts/**/*.html", + "./themes/congo/content/**/*.{html,md}", + ], + + // and more... +}; +``` + +这个默认配置已经包含了这些内容路径，以便您可以轻松生成自己的 CSS 文件，而无需修改它，只要您遵循特定的项目结构。换句话说，**您必须将 Congo 作为子目录包含在项目中，即 `themes/congo/`**。这意味着您不能轻松使用 Hugo 模块来安装主题，而必须选择 git 子模块（推荐）或手动安装路线。[安装文档]({{< ref "installation" >}})解释了如何使用这两种方法之一安装主题。 + +### 项目结构 + +为了充分利用默认配置，您的项目结构应该长得像下面这个样子... + +```shell +. +├── assets +│ └── css +│ └── compiled +│ └── main.css # this is the file we will generate +├── config # site config +│ └── _default +├── content # site content +│ ├── _index.md +│ ├── projects +│ │ └── _index.md +│ └── blog +│ └── _index.md +├── layouts # custom layouts for your site +│ ├── partials +│ │ └── extend-article-link.html +│ ├── projects +│ │ └── list.html +│ └── shortcodes +│ └── disclaimer.html +└── themes + └── congo # git submodule or manual theme install +``` + +这个例子的结构添加了一个新的 `projects` 内容类型，具有自己的自定义布局，以及一个自定义短代码和扩展部分。只要项目遵循这个结构，唯一需要做的就是重新编译 `main.css` 文件。 + +### 安装依赖项 + +为了使这个工作，你需要切换到 `themes/congo/` 目录并安装项目的依赖项。对于这一步骤，你的本地机器上需要 [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install)。 + +```shell +cd themes/congo +npm install +``` + +### 运行 Tailwind 编译器 + +在安装了依赖项之后，唯一需要做的就是使用 [Tailwind CLI](https://v2.tailwindcss.com/docs/installation#using-tailwind-cli) 调用 JIT 编译器。返回到你的 Hugo 项目的根目录，执行以下命令： + +```shell +cd ../.. +./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit +``` + +由于涉及到路径，这是一个有点丑陋的命令，但基本上你是在调用 Tailwind CLI 并传递 Tailwind 配置文件的位置（我们上面看到的文件），主题的 `main.css` 文件的位置，以及你想要放置编译后的 CSS 文件的位置（它将放在你的 Hugo 项目的 `assets/css/compiled/` 文件夹中）。 + +配置文件将自动检查你的项目中的所有内容和布局，以及主题中的所有内容，并构建一个新的 CSS 文件，其中包含你的网站所需的所有 CSS。由于 Hugo 处理文件层次结构的方式，这个文件在你的项目中现在将自动覆盖主题自带的文件。 + +每当你更改布局并需要新的 Tailwind CSS 样式时，只需重新运行该命令并生成新的 CSS 文件。你也可以在命令的末尾添加 `-w` 以在监视模式下运行 JIT 编译器。 + +### 创建构建脚本 + +为了完全完成这个解决方案，你可以通过为这些命令添加别名，或者像我一样，在你的项目根目录添加一个包含必要脚本的 `package.json` 文件，来简化整个过程... + +```js +// package.json + +{ + "name": "my-website", + "version": "1.0.0", + "description": "", + "scripts": { + "server": "hugo server -b http://localhost -p 8000", + "dev": "NODE_ENV=development ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w", + "build": "NODE_ENV=production ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit" + }, + // and more... +} +``` + +现在，当你想要设计你的网站时，你可以调用 `npm run dev`，编译器将在监视模式下运行。当你准备部署时，运行 `npm run build`，你将得到一个干净的 Tailwind CSS 构建。 + +🙋‍♀️ 如果你需要帮助，请随时在 [GitHub Discussions](https://github.com/jpanther/congo/discussions) 上提问。 diff --git a/exampleSite/content/docs/configuration/index.zh-cn.md b/exampleSite/content/docs/configuration/index.zh-cn.md new file mode 100644 index 00000000..76f8feb0 --- /dev/null +++ b/exampleSite/content/docs/configuration/index.zh-cn.md @@ -0,0 +1,185 @@ +--- +title: "基本配置" +date: 2020-08-14 +draft: false +description: "Congo中所有可使用的设定变量" +summary: "探索一下 Congo 中所有的站点、语言和主题配置变量，以及如何用于自定义你的项目。" +slug: "configuration" +tags: ["config", "docs"] +--- + +Congo 是一个高度可定制的主题，利用一些最新的 Hugo 特性来简化配置过程。 + +该主题附带了一个默认配置，让你可以快速启动一个基本的博客或静态网站。 + +> 主题附带的配置文件采用 TOML 格式，因为这是 Hugo 的默认语法。如果你愿意，可以将配置转换为 YAML 或 JSON。 + +每个文件中都有默认主题配置的文档，因此你可以自由调整设置以满足你的需求。 + +{{< alert >}} +正如在[安装说明]({{< ref "/docs/installation#set-up-theme-configuration-files" >}})中所述，你应该通过修改 Hugo 项目的 `config/_default/` 文件夹中的文件来调整主题配置，并删除项目根目录中的 `config.toml` 文件。 +{{< /alert >}} + +## 网站配置 + +Congo主题全面遵循标准 Hugo 配置变量，但是有一些特定的配置项需要进行设置以获得最佳体验。 + +网站配置通过 `config/_default/config.toml` 文件管理。下表概述了 Congo 主题所使用的所有设置。 + +请注意，此表中提供的变量名使用点表示法来简化 TOML 数据结构（即 `outputs.home` 指的是 `[outputs] home`）。 + + +|名称|默认值|描述| +|---|---|---| +|`theme`|`"congo"`|使用 Hugo 模块方法安装时，应删除此配置值。对于所有其他安装类型，必须将其设置为 `congo`，以使主题正常运行。| +|`baseURL`|_未设置_|网站根目录的 URL。| +|`defaultContentLanguage`|`"en"`|此值确定主题组件和内容的默认语言。有关受支持的语言代码，请参阅下面的[语言和国际化](#language-and-i18n)部分。| +|`enableRobotsTXT`|`true`|启用时，在站点根目录将创建一个 `robots.txt` 文件，允许搜索引擎爬取整个站点。如果你更喜欢提供自己制作的 `robots.txt`，请设置为 `false` 并将文件放置在 `static` 目录中。为了完全控制，你可以提供一个[自定义布局]({{< ref "content-examples#custom-layouts" >}})来生成此文件。| +|`paginate`|`10`|在文章列表中每页列出的文章数。| +|`summaryLength`|`0`|在[front matter]({{< ref "front-matter" >}})中未提供摘要时，用于生成文章摘要的字数。值为 `0` 将使用第一句。当摘要被隐藏时，此值无效。| +|`outputs.home`|`["HTML", "RSS", "JSON"]`|生成站点的输出格式。Congo 需要 HTML、RSS 和 JSON 才能使所有主题组件正常工作。| +|`permalinks`|_未设置_|有关固定链接配置，请参阅[Hugo文档](https://gohugo.io/content-management/urls/#permalinks)。| +|`taxonomies`|_未设置_|有关分类法配置，请参阅[组织内容]({{< ref "getting-started#organising-content" >}})部分。| + + +## 语言和国际化 + +Congo 针对完整的多语言网站进行了优化，并且主题assets中已经默认翻译成多种语言。语言配置允许您生成多个版本的内容，以为访问者提供在其母语中的定制体验。 + +该主题目前支持以下语言： + +| 语言 | 代码 | +| --------------------------------------- | ------- | +| :gb: **英语（默认）** | `en` | +| :egypt: 阿拉伯语 | `ar` | +| :bangladesh: 孟加拉语 | `bn` | +| :bulgaria: 保加利亚语 | `bg` | +| :cn: 中文 - 简体（中国） | `zh-cn` | +| :taiwan: 中文 - 繁体（台湾） | `zh-tw` | +| :flag-cz: 捷克语 | `cs` | +| :netherlands: 荷兰语 | `nl` | +| :finland: 芬兰语 | `fi` | +| :fr: 法语 | `fr` | +| :de: 德语 | `de` | +| :israel: 希伯来语 | `he` | +| :hungary: 匈牙利语 | `hu` | +| :indonesia: 印尼语 | `id` | +| :it: 意大利语 | `it` | +| :jp: 日语 | `ja` | +| :poland: 波兰语 | `pl` | +| :brazil: 葡萄牙语（巴西） | `pt-br` | +| :portugal: 葡萄牙语（葡萄牙） | `pt-pt` | +| :romania: 罗马尼亚语 | `ro` | +| :ru: 俄语 | `ru` | +| :slovakia: 斯洛伐克语 | `sk` | +| :es: 西班牙语（西班牙） | `es` | +| :tr: 土耳其语 | `tr` | +| :ukraine: 乌克兰语 | `uk` | + +默认翻译可以通过在 `i18n/[code].yaml` 中创建自定义文件来覆盖，其中包含翻译字符串。您还可以使用此方法添加新语言。如果您希望与社区分享新的翻译，请[Pull Request](https://github.com/jpanther/congo/pulls)。 + +### 配置 + +为了尽可能灵活，需要为网站上的每种语言创建一个语言配置文件。默认情况下，Congo 在 `config/_default/languages.en.toml` 中包含英语语言配置。 + +默认文件可以用作创建其他语言的模板，或者如果希望使用英语以外的语言编写网站，则可以重命名。只需使用格式 `languages.[language-code].toml` 命名文件。 + +{{< alert >}} +**注意：** 确保[网站配置](#site-configuration)中的 `defaultContentLanguage` 参数与语言配置文件名中的语言代码匹配。 +{{< /alert >}} + + +|名称|默认值|描述| +|---|---|---| +|`languageCode`|`"en"`|此文件的 Hugo 语言代码。它可以是顶级语言（即 `en`）或子变体（即 `en-AU`），并应与文件名中的语言代码匹配。| +|`languageName`|`"English"`|语言的名称。| +|`languageDirection`|`"ltr"`|这是否是 RTL 语言。设置为 `"rtl"` 以从右到左重新排列内容。Congo 完全支持同时使用 RTL 和 LTR 语言，并会动态调整到两者。| +|`weight`|`1`|构建多语言站点时语言的顺序的权重。| +|`title`|`"Congo"`|网站的标题。这将显示在站点标题和页脚中。| +|`copyright`|_未设置_|包含要显示在站点页脚中的版权消息的 Markdown 字符串。如果未提供，则 Congo 将使用站点 `title` 自动生成版权字符串。| +|`params.dateFormat`|`"2 January 2006"`|此语言中日期的格式。有关可接受格式，请参阅[Hugo文档](https://gohugo.io/functions/format/#gos-layout-string)。| +|`params.mainSections`|_未设置_|显示在最新文章列表中的部分。如果未提供，则使用文章数最多的部分。| +|`params.description`|_未设置_|网站描述。这将用于站点元数据。| +|`author.name`|_未设置_|作者的姓名。这将显示在文章页脚和使用配置文件布局时在主页上。| +|`author.image`|_未设置_|作者的图像文件路径。图像应为1:1的宽高比，并放置在站点的 `assets/` 文件夹中。| +|`author.headline`|_未设置_|包含作者头衔的 Markdown 字符串。它将显示在主页上作者姓名下方。| +|`author.bio`|_未设置_|包含作者简介的 Markdown 字符串。它将显示在文章页脚中。| +|`author.links`|_未设置_|要显示在作者详细信息旁边的链接。配置文件包含可以取消注释以启用的示例链接。显示链接的顺序由它们在数组中出现的顺序确定。可以通过在 `assets/icons/` 中提供相应的 SVG 图标资产来添加自定义链接。| + + +### 菜单 + +Congo 还支持语言特定的菜单配置。菜单配置文件遵循与语言文件相同的命名格式。只需在文件名中提供语言代码，以告诉 Hugo 该文件与哪种语言相关。 + +菜单配置文件的命名格式为 `menus.[language-code].toml`。始终确保菜单配置中使用的语言代码与语言配置相匹配。 + +[快速开始]({{< ref "getting-started#menus" >}})部分更详细地解释了此文件的结构。您还可以参考[Hugo 菜单文档](https://gohugo.io/content-management/menus/)以获取更多配置示例。 + +## 主题参数 + +Congo 提供了大量的配置参数，用于控制主题的功能。下表概述了 `config/_default/params.toml` 文件中的每个可用参数。 + +这里的许多文章默认值可以通过在 front matter 中指定来覆盖每篇文章的默认值。有关详细信息，请参阅[Front Matter]({{< ref "front-matter" >}})部分。 + + +|名称|默认值|描述| +|---|---|---| +|`colorScheme`|`"congo"`|要使用的主题颜色方案。有效值为 `congo`（默认）、`avocado`、`cherry`、`fire`、`ocean`、`sapphire` 和 `slate`。有关详细信息，请参阅[颜色方案]({{< ref "getting-started#颜色方案" >}})部分。| +|`defaultAppearance`|`"light"`|默认的主题外观，可以是 `light` 或 `dark`。| +|`autoSwitchAppearance`|`true`|主题外观是否根据访问者的操作系统首选项自动切换。设置为 `false` 以始终使用 `defaultAppearance`。| +|`enableSearch`|`false`|是否启用站内搜索。设置为 `true` 以启用搜索功能。请注意，搜索功能取决于 [站点配置](#site-configuration) 中的 `outputs.home` 设置正确。| +|`enableCodeCopy`|`false`|是否启用 `` 块的复制到剪贴板按钮。`highlight.noClasses` 参数必须设置为 `false`，以使代码复制正常工作。有关[其他配置文件](#other-configuration-files)的详细信息，请阅读下文。| +|`enableImageLazyLoading`|`true`|是否将图像标记为浏览器的延迟加载。| +|`robots`|_未设置_|指示机器人如何处理您的站点的字符串。如果设置，将在页面头部输出。有关有效值，请参阅[Google 文档](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives)。| +|`fingerprintAlgorithm`|`"sha256"`|指示在对assets进行指纹识别时使用的哈希算法。有效选项包括 `md5`、`sha256`、`sha384` 和 `sha512`。| +|`header.layout`|`"basic"`|页面头部和菜单的布局。有效值为 `basic`、`hamburger`、`hybrid` 或 `custom`。当设置为 `custom` 时，您必须通过创建 `/layouts/partials/header/custom.html` 文件提供自己的布局。| +|`header.logo`|_未设置_|站点徽标文件在 `assets/` 文件夹内的相对路径。徽标文件应以 2x 分辨率提供，并支持任何图像尺寸。| +|`header.logoDark`|_未设置_|与 `header.logo` 参数相同，但此图像在启用深色模式时使用。| +|`header.showTitle`|`true`|是否在页眉中显示站点标题。| +|`footer.showCopyright`|`true`|是否在站点页脚显示版权字符串。请注意，可以使用[语言配置](#language-and-i18n)中的 `copyright` 参数自定义字符串。| +|`footer.showThemeAttribution`|`true`|是否在站点页脚显示 "由...强力驱动" 的主题归属。如果选择禁用此消息，请考虑在站点的其他地方（例如关于页面）写上主题归属。| +|`footer.showAppearanceSwitcher`|`false`|是否在站点页脚显示外观切换器。使用浏览器的本地存储来保留访问者的首选项。| +|`footer.showScrollToTop`|`true`|设置为 `true` 时，将显示返回顶部箭头。| +|`homepage.layout`|`"page"`|主页的布局。有效值为 `page`、`profile` 或 `custom`。当设置为 `custom` 时，您必须通过创建 `/layouts/partials/home/custom.html` 文件提供自己的布局。有关详细信息，请参阅[主页布局]({{< ref "homepage-layout" >}})部分。| +|`homepage.showRecent`|`false`|是否在主页上显示最近的文章列表。| +|`homepage.recentLimit`|`5`|当 `homepage.showRecent` 为 `true` 时，显示的最大最近文章数。| +|`article.showDate`|`true`|是否显示文章日期。| +|`article.showDateUpdated`|`false`|是否显示文章更新日期。| +|`article.showAuthor`|`true`|是否在文章页脚显示作者框。| +|`article.showBreadcrumbs`|`false`|是否在文章头部显示面包屑。| +|`article.showDraftLabel`|`true`|在使用 `--buildDrafts` 构建站点时，是否显示文章旁边的草稿标签。| +|`article.showEdit`|`false`|是否显示编辑文章内容的链接。| +|`article.editURL`|_未设置_|当 `article.showEdit` 激活时，编辑链接的 URL。| +|`article.editAppendPath`|`true`|当 `article.showEdit` 激活时，是否将当前文章的路径附加到设置为 `article.editURL` 的 URL。| +|`article.showHeadingAnchors`|`true`|是否在文章内的标题旁边显示锚链接。| +|`article.showPagination`|`true`|是否在文章页脚显示下一篇/上一篇文章的链接。| +|`article.invertPagination`|`false`|是否翻转下一篇/上一篇文章链接的方向。| +|`article.showReadingTime`|`true`|是否显示文章阅读时间。| +|`article.showTableOfContents`|`false`|是否在文章上显示目录。| +|`article.showTaxonomies`|`false`|是否在与文章相关的分类法上显示。| +|`article.showWordCount`|`false`|是否显示文章字数。| +|`article.showComments`|`false`|是否在文章页脚之后包含[comments partial]({{< ref "partials#comments" >}})。| +|`article.sharingLinks`|_未设置_|要在每篇文章末尾显示的分享链接。如果未提供或设置为 `false`，则不会显示任何链接。| +|`list.showBreadcrumbs`|`false`|是否在列表页面的页眉中显示面包屑。| +|`list.showTableOfContents`|`false`|是否在列表页面上显示目录。| +|`list.showTaxonomies`|`false`|是否在列表页面上显示与此文章相关的分类法。| +|`list.showSummary`|`false`|是否在列表页面上显示文章摘要。如果在[Front Matter]({{< ref "front-matter" >}})中未提供摘要，则将使用[站点配置](#site-configuration)中的 `summaryLength` 参数自动生成一个摘要。| +|`list.groupByYear`|`true`|是否在列表页面上按年份对文章进行分组。| +|`list.paginationWidth`|`1`|在需要截断页面列表时，输出当前页面两侧的分页链接数。宽度为 `1` 将在需要截断列表时输出当前页面两侧的一个链接。当前、第一个和最后一个页面的链接始终会显示，并且是在此值之外的链接。| +|`sitemap.excludedKinds`|`["taxonomy", "term"]`|应从生成的 `/sitemap.xml` 文件中排除的内容类型。有关可接受的值，请参阅[Hugo 文档](https://gohugo.io/templates/section-templates/#page-kinds)。| +|`taxonomy.showTermCount`|`true`|是否在分类法列表上显示分类术语内文章的数量。| +|`fathomAnalytics.site`|_未设置_|由 Fathom Analytics 为网站生成的站点代码。有关详细信息，请参阅[分析文档]({{< ref "partials#analytics" >}})。| +|`fathomAnalytics.domain`|_未设置_|如果在 Fathom Analytics 中使用自定义域，请在此提供以从自定义域提供 `script.js`。| +|`plausibleAnalytics.domain`|_未设置_|输入要跟踪的网站的域。有关详细信息，请参阅[分析文档]({{< ref "partials#analytics" >}})。| +|`plausibleAnalytics.event`|_未设置_|可寻址 Plausible api 事件的 URL。有关详细信息，请参阅[分析文档]({{< ref "partials#analytics" >}})。| +|`plausibleAnalytics.script`|_未设置_|可寻址 Plausible 分析脚本的 URL。有关详细信息，请参阅[分析文档]({{< ref "partials#analytics" >}})。| +|`verification.google`|_未设置_|由 Google 提供的要包含在站点元数据中的站点验证字符串。| +|`verification.bing`|_未设置_|由 Bing 提供的要包含在站点元数据中的站点验证字符串。| +|`verification.pinterest`|_未设置_|由 Pinterest 提供的要包含在站点元数据中的站点验证字符串。| +|`verification.yandex`|_未设置_|由 Yandex 提供的要包含在站点元数据中的站点验证字符串。| + +## 其他配置文件 + +主题还包括一个 `markup.toml` 配置文件。该文件包含一些重要的参数，确保 Hugo 正确配置以生成使用 Congo 构建的站点。 + +始终确保此文件存在于配置目录中，并设置所需的值。否则，可能导致某些功能不正确地运行，并可能导致意外的行为。 diff --git a/exampleSite/content/docs/content-examples/index.zh-cn.md b/exampleSite/content/docs/content-examples/index.zh-cn.md new file mode 100644 index 00000000..312686c4 --- /dev/null +++ b/exampleSite/content/docs/content-examples/index.zh-cn.md @@ -0,0 +1,316 @@ +--- +title: "内容示例" +date: 2020-08-09 +draft: false +description: "一些演示如何创建和组织内容的示例。" +summary: "是时候通过一些演示示例将所有内容整合起来，展示如何创建和组织内容了。" +slug: "content-examples" +tags: ["content", "example"] +--- + +如果你按顺序阅读文档，现在应该对 Congo 中提供的所有功能和配置有所了解。本页面旨在将所有内容整合在一起，并提供一些你可能想在 Hugo 项目中使用的实际示例。 + +{{< alert >}} +**提示：** 如果你是 Hugo 新手，请务必查阅[官方文档](https://gohugo.io/content-management/page-bundles/)，了解有关page bundles和资源概念的更多信息。 +{{< /alert >}} + +本页面的示例可以根据不同的情境进行调整，但希望能为你提供一些关于如何处理特定内容项格式的思路，以适应你个人项目的需要。 + +## 分支页面 + +在 Hugo 中，分支页面包括主页、部分列表和分类页面等。需要记住的一点是，此类内容的文件名是 **`_index.md`**。 + +Congo 将遵循分支页面中指定的 front matter 参数，这些参数将覆盖该特定页面的默认设置。例如，在分支页面中设置 `title` 参数将允许覆盖页面标题。 + +### 主页 + +| | | +| ------------ | -------------------- | +| **布局：** | `layouts/index.html` | +| **内容：** | `content/_index.md` | + +在 Congo 中，主页是特殊的，因为其总体设计由主页布局配置参数控制。你可以在 [主页布局]({{< ref "homepage-layout" >}}) 部分了解更多信息。 + +如果你想在这个页面上添加自定义内容，只需创建一个 `content/_index.md` 文件。然后，此文件中的任何内容都将包含在你的主页中。 + +**示例:** + +```yaml +--- +title: "欢迎来到 Congo！" +description: "这是向主页添加内容的演示。" +--- +欢迎来到我的网站！我真的很高兴你停留在这里。 +``` + +_此示例设置了自定义标题，并在页面正文中添加了一些额外的文本。任何 Markdown 格式的文本都是可以接受的，包括短代码、图片和链接。_ + +### 列表页面 + +| | | +| ------------ | ---------------------------- | +| **布局：** | `layouts/_default/list.html` | +| **内容：** | `content/../_index.md` | + +列表页面将其内部的所有页面分组到一个部分，并提供一种让访问者访问每个页面的方式。博客或投影集是列表页面的示例，因为它们将帖子或项目分组在一起。 + +创建列表页面就像在 content 文件夹中创建一个子目录一样简单。例如，要创建一个 "Projects" 部分，你将创建 `content/projects/`。然后为你的每个项目创建一个 Markdown 文件。 + +列表页面将默认生成，但为了自定义内容，你还应该在这个新目录中创建一个 `_index.md` 页面。 + +```shell +. +└── content + └── projects + ├── _index.md # /projects + ├── first-project.md # /projects/first-project + └── another-project + ├── index.md # /projects/another-project + └── project.jpg +``` + +Hugo 将相应地为项目文件夹中的页面生成 URL。 + +就像主页一样，`_index.md` 文件中的内容将输出到生成的列表索引中。Congo 然后会在内容下方列出此部分中的任何页面。 + +**示例:** + +```yaml +--- +title: "项目" +description: "了解我的一些项目。" +cascade: + showReadingTime: false +--- +这个部分包含所有我的当前项目。 +``` + +_在此示例中，使用了特殊的 `cascade` 参数来隐藏此部分中任何子页面上的阅读时间。通过这样做，任何项目页面将不显示其阅读时间。这是在整个部分中覆盖默认主题参数的好方法，而无需在每个单独页面中包含它们。_ + +此站点的 [样本部分]({{< ref "samples" >}}) 是列表页面的示例。 + +### 分类页面 + +| | | +| ---------------- | -------------------------------- | +| **列表布局:** | `layouts/_default/taxonomy.html` | +| **术语布局:** | `layouts/_default/term.html` | +| **内容:** | `content/../_index.md` | + +分类页面有两种形式 - 分类列表和分类术语。列表显示给定分类中每个术语的列表，而术语显示与给定术语相关的页面列表。 + +术语可能会有点混淆，所以让我们通过一个使用名为 `animals` 的分类的示例来探讨一下。 + +首先，在 Hugo 中使用分类，必须进行配置。这是通过在 `config/_default/taxonomies.toml` 创建配置文件并定义分类名称来完成的。 + +```toml +# config/_default/taxonomies.toml + +animal = "animals" +``` + +Hugo 期望以它们的单数和复数形式列出分类，因此我们添加了单数 `animal` 等于复数 `animals` 来创建我们的示例分类。 + +现在我们的 `animals` 分类存在了，它需要被添加到各个内容项中。只需将其插入到前置元数据中： + +```yaml +--- +title: "Into the Lion's Den" +description: "This week we're learning about lions." +animals: ["lion", "cat"] +--- +``` + +这样就在我们的 `animals` 分类中创建了两个 _术语_ - `lion` 和 `cat`。 + +虽然此时并不明显，但 Hugo 现在将为这个新的分类生成列表和术语页面。默认情况下，可以通过 `/animals/` 访问列表，而术语页面可以在 `/animals/lion/` 和 `/animals/cat/` 找到。 + +列表页面将列出分类中包含的所有术语。在这个例子中，导航到 `/animals/` 将显示一个页面，其中包含指向各个术语页面的链接，如 "lion" 和 "cat"。 + +术语页面将列出该术语中包含的所有页面。这些术语列表本质上与普通的 [列表页面](#list-pages) 相同，并以相似的方式运作。 + +要向分类页面添加自定义内容，只需在使用分类名称作为子目录名的内容文件夹中创建 `_index.md` 文件。 + +```shell +. +└── content + └── animals + ├── _index.md # /animals + └── lion + └── _index.md # /animals/lion +``` + +这些内容文件中的任何内容都将放置到生成的分类页面上。与其他内容一样，前置元数据变量可用于覆盖默认设置。通过这种方式，您可以拥有一个名为 `lion` 的标签，但可以覆盖 `title` 为 "Lion"。 + +要了解实际效果，请查看此站点上的 [标签分类列表]({{< ref "tags" >}})。 + +## 单页 + +| | | +| ------------------------- | ------------------------------- | +| **布局：** | `layouts/_default/single.html` | +| **内容（独立）：** | `content/../page-name.md` | +| **内容（打包）：** | `content/../page-name/index.md` | + +Hugo 中的单页基本上是标准内容页面。它们被定义为不包含任何子页面的页面。这可能是关于页面，或者是博客部分中的单个博客文章。 + +关于单页的最重要的事情是，与分支页面不同，单页应该命名为 `index.md`，**没有**下划线。单页还很特殊，因为它们可以在部分的顶层进行分组，并以独特的名称命名。 + +```shell +. +└── content + └── blog + ├── first-post.md # /blog/first-post + ├── second-post.md # /blog/second-post + └── third-post + ├── index.md # /blog/third-post + └── image.jpg +``` + +在页面中包含资产，比如图片，应该使用页面包。页面包使用带有 `index.md` 文件的子目录创建。将资产与内容一起分组到自己的目录中是重要的，因为许多 shortcodes 和其他主题逻辑假定资源与页面一起打包。 + +**示例:** + +```yaml +--- +title: "我的第一篇博客文章" +date: 2022-01-25 +description: "欢迎来到我的博客！" +summary: "了解更多关于我以及我为什么开始写这个博客的信息。" +tags: ["欢迎", "新", "关于", "第一篇"] +--- +_这_ 是我的博客文章的内容。 +``` + +单页有各种可以用于自定义显示方式的 [前置元数据]({{< ref "front-matter" >}}) 参数。 + +### 外部链接 + +Congo 具有一个特殊功能，允许外部页面的链接出现在文章列表中。如果您在第三方网站（如 Medium）上有内容，或者有研究论文希望链接，而不想在 Hugo 站点中复制内容，这将非常有用。 + +要创建外部链接文章，需要设置一些特殊的前置元数据： + +```yaml +--- +title: "我的 Medium 文章" +date: 2022-01-25 +externalUrl: "https://medium.com/" +summary: "我在 Medium 上写了一篇文章。" +showReadingTime: false +_build: + render: "false" + list: "local" +--- +``` + +除了正常的前置元数据参数如 `title` 和 `summary` 外，`externalUrl` 参数用于告诉 Congo 这不是一篇普通文章。此处提供的 URL 将是访问者选择该文章时的目标链接。 + +此外，我们使用了一个特殊的 Hugo 前置元数据参数 `_build` 来阻止生成此内容的正常页面 - 因为我们正在链接到外部 URL，生成正常页面没有意义！ + +主题包含一个原型，使生成这些外部链接文章变得简单。只需在创建新内容时指定 `-k external`。 + +```shell +hugo new -k external posts/my-post.md +``` + +### 简单页面 + +| | | +| ----------------- | ------------------------------ | +| **Layout:** | `layouts/_default/simple.html` | +| **Front Matter:** | `layout: "simple"` | + +Congo 还包括一个专门用于简单页面的特殊布局。简单布局是一个全宽度的模板，只需将 Markdown 内容放入页面，而不包含任何特殊的主题功能。 + +简单布局中唯一可用的功能是面包屑和分享链接。但是，这些的行为仍然可以通过使用正常页面 [前置元数据]({{< ref "front-matter" >}}) 变量进行控制。 + +要在特定页面上启用简单布局，请添加 `layout` 前置元数据变量，其值为 `"simple"`： + +```yaml +--- +title: "我的落地页" +date: 2022-03-08 +layout: "simple" +--- +此页面内容现在是全宽度的。 + +## 自定义布局 + +Hugo 的一个好处是它使得为整个站点、单独的部分或页面创建自定义布局变得很容易。 + +布局遵循所有常规的 Hugo 模板规则，更多信息请参阅[官方 Hugo 文档](https://gohugo.io/templates/introduction/)。 + +### 覆盖默认布局 + +上面讨论的每种内容类型都列出了用于生成每种页面类型的布局文件。如果在本地项目中创建了此文件，它将覆盖主题模板，因此可用于自定义网站的默认样式。 + +例如，创建一个 `layouts/_default/single.html` 文件将允许完全自定义叶页面的布局。 + +### 自定义部分布局 + +为个别内容部分创建自定义布局也很简单。当您想要使用特定样式列出某种类型内容的部分时，这将非常有用。 + +让我们通过一个示例来创建一个自定义的“项目”页面，该页面使用特殊布局列出项目。 + +为了做到这一点，使用常规的 Hugo 内容规则构建您的内容，并为您的项目创建一个新部分。此外，通过使用与内容相同的目录名称并添加一个 `list.html` 文件来为项目部分创建一个新布局。 + +```shell +. +└── content +│ └── projects +│ ├── _index.md +│ ├── first-project.md +│ └── second-project.md +└── layouts + └── projects + └── list.html +``` + +这个 `list.html` 文件现在将覆盖默认的列表模板，但仅适用于 `projects` 部分。在我们查看这个文件之前，让我们首先查看个别项目文件。 + +```yaml +--- +title: "Congo" +date: 2021-08-11 +icon: "github" +description: "A theme for Hugo built with Tailwind CSS." +topics: ["Hugo", "Web", "Tailwind"] +externalUrl: "https://github.com/jpanther/congo/" +--- +``` + +_在这个示例中，我们为每个项目分配了一些元数据，然后我们可以在我们的列表模板中使用这些元数据。这里没有页面内容，但没有阻止您包含它。毕竟这是您自己的自定义模板！_ + +有了定义的项目，现在我们可以创建一个列表模板，输出每个项目的详细信息。 + +```go +{{ define "main" }} +
+ {{ range .Pages }} + + {{ end }} +
+{{ end }} +``` + +虽然这是一个相当简单的示例，但您可以看到它逐步处理此部分中的每个页面（即每个项目），然后输出到每个项目旁边的 HTML 链接和图标。每个项目的前置元数据用于确定显示哪些信息。 + +请记住，您需要确保相关的样式和类可用，这可能需要重新编译 Tailwind CSS。这在 [高级自定义]({{< ref "advanced-customisation" >}}) 部分中有更详细的讨论。 + +在创建此类自定义模板时，最简单的方法始终是查看默认 Congo 模板的工作方式，然后将其用作指南。记住，[Hugo 文档](https://gohugo.io/templates/introduction/)也是学习有关创建模板的更多信息的绝佳资源。 diff --git a/exampleSite/content/docs/front-matter/index.zh-cn.md b/exampleSite/content/docs/front-matter/index.zh-cn.md new file mode 100644 index 00000000..8a90cb32 --- /dev/null +++ b/exampleSite/content/docs/front-matter/index.zh-cn.md @@ -0,0 +1,51 @@ +--- +title: "Front Matter" +date: 2020-08-12 +draft: false +description: "Congo中可用的所有Front Matter 变量。" +summary: "虽然支持大多数 Hugo 默认值，但 Congo 添加了许多前置参数，以定制单个文章的呈现方式。" +slug: "front-matter" +tags: ["front matter", "config", "docs"] +--- + +除了[默认 Hugo 的Front Matter变量](https://gohugo.io/content-management/front-matter/#front-matter-variables)之外，Congo 添加了许多额外的选项，以定制单个文章的呈现方式。以下是所有可用的主题前置变量参数。 + +Front Matter参数的默认值是从主题的[基础配置]({{< ref "configuration" >}})中继承的，因此只有在要覆盖默认值时才需要在Front Matter变量中指定这些参数。 + + +|Name|Default|Description| +|---|---|---| +|`title`|_未设置_|文章的标题。| +|`description`|_未设置_|文章的文本描述。用于 HTML 元数据。| +|`feature`|`"*feature*"`|用于匹配此文章的feature图片文件名的文本模式。| +|`featureAlt`|`""`|feature图片的替代文本描述。| +|`cover`|`"*cover*"`|用于匹配此文章的封面图片文件名的文本模式。| +|`coverAlt`|`featureAlt`|封面图片的替代文本描述。| +|`coverCaption`|_未设置_|在封面图片下方显示的图注文本。| +|`thumbnail`|`"*thumb*"`_|用于匹配此文章的缩略图图片文件名的文本模式。| +|`thumbnailAlt`|`featureAlt`|缩略图图片的替代文本描述。| +|`externalUrl`|_未设置_|如果此文章发表在第三方网站上，则为此文章的 URL。提供 URL 将阻止生成内容页面，并且对此文章的任何引用将直接链接到第三方网站。| +|`editURL`|`article.editURL`|当 `showEdit` 激活时，编辑链接的 URL。| +|`editAppendPath`|`article.editAppendPath`|当 `showEdit` 激活时，是否将当前文章的路径附加到 `editURL` 设置的 URL。| +|`groupByYear`|`list.groupByYear`|文章在列表页面上是否按年份分组。| +|`keywords`|_未设置_|应包含在文章元数据中的任何关键字。| +|`menu`|_未设置_|提供数值时，此文章的链接将出现在指定的菜单中。有效值为 `main` 或 `footer`。| +|`robots`|_未设置_|指示爬虫机器人如何处理此文章的字符串。如果设置，它将输出到页面头部。参考[Google文档](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives)获取有效值。| +|`sharingLinks`|`article.sharingLinks`|在文章末尾显示哪些分享链接。如果未提供或设置为 `false`，则不显示任何链接。| +|`showAuthor`|`article.showAuthor`|是否在文章页脚显示作者框。| +|`showBreadcrumbs`|`article.showBreadcrumbs` 或 `list.showBreadcrumbs`|是否在文章或列表页眉中显示面包屑。| +|`showDate`|`article.showDate`|是否显示文章日期。日期使用 `date` 参数设置。| +|`showDateUpdated`|`article.showDateUpdated`|是否显示文章的更新日期。日期使用 `lastmod` 参数设置。| +|`showEdit`|`article.showEdit`|是否显示编辑文章内容的链接。| +|`showHeadingAnchors`|`article.showHeadingAnchors`|是否在文章中的标题旁边显示标题锚链接。| +|`showPagination`|`article.showPagination`|是否在文章页脚显示下一篇/上一篇文章的链接。| +|`invertPagination`|`article.invertPagination`|是否翻转下一篇/上一篇文章链接的方向。| +|`showReadingTime`|`article.showReadingTime`|是否显示文章的阅读时间。| +|`showTaxonomies`|`article.showTaxonomies`|是否显示与此文章相关的分类法。| +|`showTableOfContents`|`article.showTableOfContents`|是否在文章中显示目录。| +|`showWordCount`|`article.showWordCount`|是否显示文章的字数统计。| +|`showComments`|`article.showComments`|是否在文章页脚后包含[评论部分]({{< ref "partials#comments" >}})。| +|`showSummary`|`list.showSummary`|是否在列表页上显示文章摘要。| +|`summary`|使用 `summaryLength` 自动生成（参见[站点配置]({{< ref "configuration#site-configuration" >}})）|当启用 `showSummary` 时，用作此文章摘要的 Markdown 字符串。| +|`xml`|`true`，除非被 `sitemap.excludedKinds` 排除|此文章是否包含在生成的 `/sitemap.xml` 文件中。| + \ No newline at end of file diff --git a/exampleSite/content/docs/getting-started/index.zh-cn.md b/exampleSite/content/docs/getting-started/index.zh-cn.md new file mode 100644 index 00000000..81861e2a --- /dev/null +++ b/exampleSite/content/docs/getting-started/index.zh-cn.md @@ -0,0 +1,244 @@ +--- +title: "快速开始" +date: 2020-08-15 +draft: false +description: "Congo的启动方法" +summary: "这一部分假设你已经安装了Congo主题，并准备开始进行基本配置任务，如选择颜色方案、菜单和内容结构。" +slug: "getting-started" +tags: ["installation", "docs"] +--- + +{{< alert >}} +本节假定您已经[安装了Congo主题]({{< ref "docs/installation" >}})。 +{{< /alert >}} + +Congo提供的配置文件包含主题定制的所有可能设置。默认情况下，其中许多设置项都被注释掉，但您可以简单地取消注释以激活或更改特定功能。 + +## 基本配置 + +在创建任何内容之前，有一些新安装需要设置的事项。首先在`config.toml`文件中，设置`baseURL`和`languageCode`参数。`languageCode`应设置为您将用于撰写内容的主要语言。 + +```toml +# config/_default/config.toml + +baseURL = "https://your_domain.com/" +languageCode = "en" +``` + +下一步是配置语言设置。虽然Congo支持多语言设置，但目前，只需配置主要语言即可。 + +找到config文件夹中的`languages.en.toml`文件。如果您的主要语言是英语，可以直接使用此文件。否则，将其重命名，以便文件名中包含正确的语言代码。例如，对于法语，将文件重命名为`languages.fr.toml`。 + +{{< alert >}} +语言配置文件名中的语言代码应与`config.toml`中的`languageCode`设置相匹配。 +{{< /alert >}} + +```toml +# config/_default/languages.en.toml + +title = "My awesome website" + +[author] +name = "My name" +image = "img/author.jpg" +headline = "A generally awesome human" +bio = "A little bit about me" +links = [ + { twitter = "https://twitter.com/username" } +] +``` + +`[author]`配置确定在网站上显示作者信息的方式。图像应放置在站点的`assets/`文件夹中。链接将按照它们列出的顺序显示。 + +如果需要更多细节，每个配置选项的详细信息都在[配置]({{< ref "configuration" >}})部分中有介绍。 + +## 颜色方案 + +Congo默认情况下提供了一些颜色方案。要更改方案，只需设置`colorScheme`主题参数。有效选项为`congo`（默认）、`avocado`、`cherry`、`fire`、`ocean`、`sapphire`和`slate`。 + +{{< alert >}} +`colorScheme`值应以小写形式提供。 +{{< /alert >}} + +```toml +# config/_default/params.toml + +colorScheme = "congo" +``` + +Congo定义了一个在整个主题中使用的三色调色板。每个主色包含十种基于包含在[Tailwind](https://tailwindcss.com/docs/customizing-colors#color-palette-reference)中的颜色的阴影。 + +#### Congo（默认） + +{{< swatches "#71717a" "#8b5cf6" "#d946ef" >}} + +#### Avocado + +{{< swatches "#78716c" "#84cc16" "#10b981" >}} + +#### Cherry + +{{< swatches "#737373" "#f43f5e" "#22c55e" >}} + +#### Fire + +{{< swatches "#78716c" "#f97316" "#f43f5e" >}} + +#### Ocean + +{{< swatches "#64748b" "#3b82f6" "#06b6d4" >}} + +#### Sapphire + +{{< swatches "#64748b" "#6366f1" "#ec4899" >}} + +#### Slate + +{{< swatches "#6B7280" "#64748b" "#6B7280" >}} + +尽管这些是默认的方案，但您还可以创建自己的方案。有关详细信息，请参阅[高级自定义]({{< ref "advanced-customisation#colour-schemes" >}})部分。 + +### 组织内容 + +Congo不会强制您使用特定的内容类型，默认情况下，您可以自由定义您的内容。您可以选择使用 _pages_ 来创建静态站点，使用 _posts_ 来撰写博客，或使用 _projects_ 来展示项目。这种自由度使您能够根据您的需求和偏好来组织和呈现内容。 + +### 目录结构 + +以下是基本Congo项目的快速概览。所有内容都放置在`content`文件夹中： + +```shell +. +├── assets +│ └── img +│ └── author.jpg +├── config +│ └── _default +├── content +│ ├── _index.md +│ ├── about.md +│ └── posts +│ ├── _index.md +│ ├── first-post.md +│ └── another-post +│ ├── aardvark.jpg +│ └── index.md +└── themes + └── congo +``` + +{{< alert >}} +这里需要注意的关键一点是，在content目录中，普通文章页面的命名为`index.md`，而列表页面的命名为`_index.md`。任何与文章相关的静态文件都应放置在与索引文件相邻的子目录中。 +{{< /alert >}} + +对于Congo主题的设计，充分利用了Hugo页面束的优势，了解Hugo希望内容如何被组织是很重要的。务必阅读[Hugo官方文档](https://gohugo.io/content-management/organization/)以获取更多信息。 + +### 特色、封面和缩略图图片 + +Congo主题支持在文章列表和单独的文章页面顶部显示图像。有三种类型的图像，每种都有其特定的用途：`feature`（特色，这个不知道怎么翻译，可能是“主图” ？）、`cover`（封面）和`thumb`（缩略图）。 + +在下面的示例中，为`first-post`文章提供了封面和缩略图图像： + +```shell +. +└── content + └── posts + ├── _index.md + └── first-post + ├── cover.jpg + ├── index.md + └── thumb.jpg +``` + +`thumb`图像用作文章缩略图，将显示在文章列表中，而`cover`图像将显示在单个文章页面的内容顶部。 + +![带有缩略图图像的文章截图](article-screenshot.jpg "此示例显示了带有缩略图图像的文章。") + +{{< alert >}} +为了提供最大性能，缩略图图像将自动裁剪并调整大小为4:3的比例。封面图像将自动调整大小以适应其内容，但允许任何比例。 +{{< /alert >}} + +`feature`图像是一种特殊类型，当存在时，它将用于替代`thumb`和`cover`图像。特色图像也出现在文章元数据中，在将内容共享到Facebook和Twitter等第三方网络时包含在其中。 + +主题将智能检测文章图像并自动将其添加到您的站点。您不必在正文中引用它们，只需将以适当命名的文件放在页面资源中即可。如果图像文件名中的任何地方都包含术语`feature`、`cover`或`thumb`，那么它将用于该用途。 + +[示例部分]({{< ref "samples" >}})提供了这些图像的许多示例（您可以查看[源代码](https://github.com/jpanther/congo/tree/dev/exampleSite/content/samples)以查看文件结构）。 + +### 分类法 + +Congo 在分类方面也非常灵活。有些人喜欢使用标签（tags）和分类（categories）来对内容进行分组，而其他人可能更倾向于使用主题（topics）。 + +Hugo默认使用文章、标签和分类，如果这符合您的需求，那么这将运行良好。但是，如果您希望自定义此设置，可以通过创建`taxonomies.toml`配置文件来实现： + +```toml +# config/_default/taxonomies.toml + +topic = "topics" +``` + +这将使用主题替换默认的标签和分类。有关在命名分类法时的更多信息，请参阅[Hugo分类法文档](https://gohugo.io/content-management/taxonomies/)。 + +创建新分类法时，您将需要调整网站上的导航链接，以指向正确的部分，下面有相关说明。 + +## 菜单 + +Congo有两个菜单，可以根据您站点的内容和布局进行自定义。`main`菜单显示在站点页眉中，而`footer`菜单显示在页面底部，正好在版权声明上方。 + +这两个菜单都在`menus.en.toml`文件中配置。与语言配置文件类似，如果您希望使用其他语言，请将此文件重命名并用所需的语言代码替换`en`。菜单链接将按`weight`从低到高排序，然后按`name`字母顺序排序。 + +```toml +# config/_default/menus.en.toml + +[[main]] + name = "博客" + pageRef = "posts" + weight = 10 + +[[main]] + name = "主题" + pageRef = "topics" + weight = 20 + +[[main]] + name = "GitHub" + url = "https://github.com/jpanther/congo" + weight = 30 + [main.params] + icon = "github" + showName = false + target = "_blank" + +[[main]] + identifier = "search" + weight = 99 + [main.params] + action = "search" + icon = "search" + +[[footer]] + name = "隐私" + pageRef = "privacy" +``` + +### 基本链接 + +`name` 参数指定了菜单链接中使用的文本。您还可以选择提供 `title`，用于填充链接的 HTML title 属性。 + +`pageRef` 参数允许您轻松引用 Hugo 内容页面和分类法。这是配置菜单的最快方法，因为您只需引用任何 Hugo 内容项，它将自动构建正确的链接。要链接到外部 URL，可以使用 `url` 参数。 + +通过使用特殊的主题参数，可以进一步自定义。在链接中提供 `params` 允许添加 `icon`，通过 `showName` 切换链接文本的能力，并可选择设置 URL 的 `target`。在上面的示例中，GitHub 链接将只显示为图标，并在新窗口中打开链接。 + +### 操作链接 + +有一个特殊情况，用于创建执行主题操作的菜单项。这些链接项通过 `action` 参数进行标识，该参数指定链接应执行的操作。操作链接允许使用与其他链接（基本链接）相同的自定义参数，并且可以用图标或文本名称进行样式设置。 + +Congo内置有三个有效的主题操作： + +- `appearance` 将创建一个指向外观切换器（深色主题还是浅色主题）的链接 +- `locale` 将创建一个下拉选择器，以切换语言访问已翻译的内容 +- `search` 将创建指向站内搜索的链接 + +这两个菜单都是完全可选的，如果不需要，可以注释掉。使用默认文件中提供的模板作为配置指南。 + +## 更详细配置 + +上述步骤是最基本的配置。如果现在运行 `hugo server`，您将看到一个空白的 Congo 网站。更详细配置在 [基本配置]({{< ref "configuration" >}}) 部分进行介绍。 diff --git a/exampleSite/content/docs/homepage-layout/index.zh-cn.md b/exampleSite/content/docs/homepage-layout/index.zh-cn.md new file mode 100644 index 00000000..b1171e99 --- /dev/null +++ b/exampleSite/content/docs/homepage-layout/index.zh-cn.md @@ -0,0 +1,53 @@ +--- +title: "主页布局" +date: 2020-08-13 +draft: false +description: "在 Congo 主题中配置首页布局。" +summary: "Congo 提供了一个完全灵活的首页布局，内置了模板并支持自定义。" +slug: "homepage-layout" +tags: ["homepage", "layouts", "docs"] +--- + +Congo 提供了完全灵活的首页布局。有两个主要的模板可供选择，并提供额外的设置以调整设计。此外，您还可以提供自己的模板，完全掌控首页内容。 + +首页的布局由`params.toml`配置文件中的 `homepage.layout` 设置控制。另外，所有布局都可以选择包含[最近的文章](#recent-articles)列表。 + +## Page布局 + +默认布局是page布局。它只是一个显示您的 Markdown 内容的普通内容页面。非常适用于静态网站，并提供了很大的灵活性。 + +![首页布局截图](home-page.jpg) + +要启用页面布局，请在 `params.toml` 配置文件中设置 `homepage.layout = "page"`。 + +## Profile布局 + +profile布局非常适用于个人网站和博客。它通过提供图像和社交媒体链接，将作者的详细信息置于中心位置。 + +![个人资料布局截图](home-profile.jpg) + +作者信息存储在语言配置文件中。有关参数详细信息，请参阅 [入门指南]({{< ref "getting-started" >}}) 和 [语言配置]({{< ref "configuration##language-and-i18n" >}}) 部分。 + +此外，提供在主页内容中的任何 Markdown 内容将显示在作者资料下方。这允许额外的灵活性，以使用 Shortcodes 显示生物或其他自定义内容。 + +要启用profile布局，请在 `params.toml` 配置文件中设置 `homepage.layout = "profile"`。 + +## custom布局 + +如果内置的首页布局不满足您的需求，您可以选择提供自己的自定义布局。这允许您完全掌控页面内容，基本上为您提供了一个空白的画布。 + +要启用自定义布局，请在 `params.toml` 配置文件中设置 `homepage.layout = "custom"`。 + +配置值设置后，创建一个新的 `custom.html` 文件并将其放置在 `layouts/partials/home/custom.html`。现在，`custom.html` 文件中的任何内容都将放置在站点首页的内容区域。您可以使用任何 HTML、Tailwind 或 Hugo 模板函数来定义布局。 + +要在自定义布局中包含[最近的文章](#recent-articles)，请使用 `recent-articles.html` 部分。 + +例如，这个站点的[首页]({{< ref "/" >}})使用自定义布局，允许在profile和page布局之间切换。访问 [GitHub 仓库](https://github.com/jpanther/congo/blob/dev/exampleSite/layouts/partials/home/custom.html) 查看它是如何工作的。 + +## 最近的文章 + +所有首页布局都可以选择在主页面内容下方显示最近的文章。要启用此功能，只需在 `params.toml` 配置文件中将 `homepage.showRecent` 设置为 `true`。 + +![具有最近文章的个人资料布局](home-profile-list.jpg) + +此部分中列出的文章来自 `mainSections` 设置，该设置允许使用您网站上使用的所有内容类型。例如，如果您有用于 _posts_ 和 _projects_ 的内容部分，可以将此设置设置为 `["posts", "projects"]`，所有这两个部分中的文章都将用于填充最近的列表。主题期望此设置为数组，因此如果您只使用一个部分来存储所有内容，您应相应地设置为 `["blog"]`。 \ No newline at end of file diff --git a/exampleSite/content/docs/hosting-deployment/index.zh-cn.md b/exampleSite/content/docs/hosting-deployment/index.zh-cn.md new file mode 100644 index 00000000..0e07adce --- /dev/null +++ b/exampleSite/content/docs/hosting-deployment/index.zh-cn.md @@ -0,0 +1,148 @@ +--- +title: "部署" +date: 2020-08-07 +draft: false +description: "学习如何部署 Congo 网站。" +summary: "Congo 被设计为在几乎任何部署场景中都具有灵活性。了解如何将项目部署到一些常见的主机平台。" +slug: "hosting-deployment" +tags: ["hosting", "deployment", "docs", "github", "netlify", "render"] +--- + +有许多方法可以部署使用 Congo 构建的 Hugo 网站。该主题被设计为在几乎任何部署场景中都具有灵活性。 + +Congo 在整个主题中使用相对 URL。这使得站点可以轻松部署到子文件夹和像 GitHub Pages 这样的主机。通常情况下，只要在 config.toml 文件中配置了 baseURL 参数，就不需要特殊的配置。 + +要学习如何部署您的站点，Hugo 官方的主机与部署文档是最佳选择。下面的部分包含一些特定的主题配置细节，可以帮助您在某些提供商那里顺利部署。 + +**选择您的提供商：** + +- [GitHub Pages](#github-pages) +- [Netlify](#netlify) +- [Render](#render) +- [Cloudflare Pages](#cloudflare-pages) +- [共享主机、VPS 或私有 Web 服务器](#shared-hosting-vps-or-private-web-server) + +--- + +## GitHub Pages + +GitHub 允许使用 [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) 在 Actions 中托管网站。要启用此功能，请在您的存储库上启用 Pages，并创建一个新的 Actions 工作流来构建和部署您的站点。 + +该文件需要采用 YAML 格式，放置在您的 GitHub 存储库的 `.github/workflows/` 目录中，并以 `.yml` 扩展名命名。 + +{{< alert >}} +**重要提示：**确保在 `branches` 下设置正确的分支名称，并在部署步骤的 `if` 参数中设置用于项目的源分支。 +{{< /alert >}} + +```yaml +# .github/workflows/gh-pages.yml + +name: GitHub Pages + +on: + push: + branches: + - main + +jobs: + build-deploy: + runs-on: ubuntu-latest + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + submodules: true + fetch-depth: 0 + + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: "latest" + + - name: Build + run: hugo --minify + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.ref == 'refs/heads/main' }} + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: gh-pages + publish_dir: ./public +``` + +将配置文件推送到 GitHub，操作应会自动运行。第一次可能会失败，您需要访问 GitHub 存储库的 **Settings > Pages** 部分以检查源是否正确。它应该设置为使用 `gh-pages` 分支。 + +{{< screenshot src="github-pages-source.jpg" alt="GitHub Pages source settings 屏幕截图" >}} + +您还应该访问 **Settings > Actions > General** 部分，检查工作流权限是否允许操作对您的存储库进行更改。 + +{{< screenshot src="github-workflow-permissions.jpg" alt="GitHub Workflow Permissions 设置屏幕截图" >}} + +配置设置后，重新运行操作，站点应该能够正确构建和部署。您可以查看操作日志以确保一切都成功部署。 + +## Netlify + +要部署到 [Netlify](https://www.netlify.com)，创建一个新的持续部署站点并将其链接到您的源代码。在 Netlify UI 中，可以将构建设置留空。您只需要配置将要使用的域。 + +{{< screenshot src="netlify-build-settings.jpg" alt="Netlify 构建设置屏幕截图" >}} + +然后在您站点存储库的根目录中，创建一个 `netlify.toml` 文件： + +```toml +# netlify.toml + +[build] + command = "hugo mod get -u && hugo --gc --minify -b $URL" + publish = "public" + +[build.environment] + HUGO_VERSION = "0.118.2" + NODE_ENV = "production" + GO_VERSION = "1.20" + TZ = "UTC" # Set to preferred timezone + +[context.production.environment] + HUGO_ENV = "production" +``` + +此配置假设您正在将 Congo 部署为 Hugo 模块。如果您使用其他方法安装了主题，请将构建命令更改为简单的 `hugo --gc --minify -b $URL`。 + +当您将配置文件推送到存储库时，Netlify 应会自动部署您的站点。您可以在 Netlify UI 中检查部署日志以查看是否有任何错误。 + +## Render + +部署到 [Render](https://render.com) 非常简单，所有配置都通过 Render UI 进行。 + +创建一个新的 **Static Site** 并将其链接到项目的代码存储库。然后简单地配置构建命令为 `hugo --gc --minify`，发布目录为 `public`。 + +{{< screenshot src="render-settings.jpg" alt="Render 设置屏幕截图" >}} + +只要您对存储库进行更改，站点将自动构建和部署。 + +## Cloudflare Pages + +Cloudflare 提供 [Pages](https://pages.cloudflare.com/) 服务，可以托管 Hugo 博客。它从 git 存储库构建站点，然后在 Cloudflare 的 CDN 上托管。请按照他们的 [Hugo 部署指南](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site) 开始使用。 + +Cloudflare 提供的 Rocket Loader™ 功能试图加速带有 JavaScript 的网页渲染，但它会破坏主题中的外观切换器。它还可能导致浏览站点时因脚本加载顺序错误而出现令人讨厌的浅色/深色屏幕闪烁。 + +可以通过禁用此功能来解决这个问题： + +- 转到 [Cloudflare 仪表板](https://dash.cloudflare.com) +- 在列表中点击您的域名 +- 在 _Speed_ 部分中点击 _Optimization_ +- 滚动到 _Rocket Loader™_ 并禁用它 + +使用 Congo 构建的 Hugo 站点即使禁用此功能仍然加载非常快。 + +## 共享托管、VPS 或私有 Web 服务器 + +使用传统的 Web 托管，或部署到自己的 Web 服务器，只需构建 Hugo 站点并将文件传输到主机即可。 + +确保 `config.toml` 中的 `baseURL` 参数设置为您网站根目录的完整 URL（包括任何子域或子文件夹）。 + +然后使用 `hugo` 构建您的站点，将输出目录的内容复制到 Web 服务器的根目录，您就准备好了。默认情况下，输出目录的名称为 `public`。 + +_如果您需要托管提供商，请查看 [Vultr](https://www.vultr.com/?ref=8957394-8H) 或 [DigitalOcean](https://m.do.co/c/36841235e565)。使用这些推广链接注册将为您提供最多 100 美元的免费信用，以便您可以尝试该服务。_ diff --git a/exampleSite/content/docs/installation/index.zh-cn.md b/exampleSite/content/docs/installation/index.zh-cn.md new file mode 100644 index 00000000..36b7af60 --- /dev/null +++ b/exampleSite/content/docs/installation/index.zh-cn.md @@ -0,0 +1,173 @@ +--- +title: "安装" +date: 2020-08-16 +draft: false +description: "如何安装Congo主题" +summary: "学习如何从0开始使用Hugo和Congo。如果您是新用户，这是开始的最佳位置。" +slug: "installation" +tags: ["installation", "docs"] +--- + +只需按照标准的Hugo [快速入门](https://gohugo.io/getting-started/quick-start/)流程，即可快速启动和运行。 + +下面提供了详细的安装说明。还有关于[更新主题](#installing-updates)的说明。 + +## 安装 + +以下说明将帮助您从0使用Hugo和Congo启动和运行。此指南中提到的大多数依赖项可以使用您平台上选择的包管理器进行安装。 + +### 安装Hugo + +如果您以前没有使用过Hugo，您需要[将其安装到本地计算机上](https://gohugo.io/getting-started/installing)。您可以通过运行命令 `hugo version` 来检查是否已经安装。 + +{{< alert >}} +确保您使用的是 **Hugo版本0.87.0** 或更高版本，因为该主题利用了一些最新的Hugo功能。 +{{< /alert >}} + +您可以在[Hugo文档](https://gohugo.io/getting-started/installing)中找到有关您平台的详细安装说明。 + +### 创建新站点 + +运行命令 `hugo new site mywebsite` 在名为 `mywebsite` 的目录中创建一个新的Hugo站点。 + +请注意，您可以将项目目录命名为任何您选择的名称，但下面的说明将假定其名称为 `mywebsite`。如果使用其他名称，请确保相应地进行替换。 + +### 下载Congo主题 + +有几种不同的方法可以将Congo主题安装到您的Hugo网站中。从最简单到最难安装和维护的方式，它们分别是： + +- [Hugo模块](#使用hugo安装)（推荐） +- [Git子模块](#使用git安装) +- [手动文件复制](#手动安装) + +如果不确定，请选择Hugo模块方法。 + +#### 使用Hugo安装 + +这种方法是保持主题最新的最快最简单的方法。Hugo使用 **Go** 来初始化和管理模块，因此在继续之前，您需要确保已安装 `go`。 + +1. [下载](https://golang.org/dl/)并安装Go。您可以通过使用命令 `go version` 来检查是否已安装。 + + {{< alert >}} + 确保您使用的是 **Go版本1.12** 或更高版本，因为Hugo需要这个版本以使模块正常工作。 + {{< /alert >}} + +2. 从Hugo项目目录（您上面创建的目录）中，为您的网站初始化模块： + + ```shell + # 如果您在GitHub上管理项目 + hugo mod init github.com// + + # 如果您在本地管理项目 + hugo mod init my-project + ``` + +3. 通过创建一个新文件 `config/_default/module.toml` 并添加以下内容，将主题添加到配置中： + + ```toml + [[imports]] + path = "github.com/jpanther/congo/v2" + ``` + +4. 使用 `hugo server` 启动您的服务器，主题将自动下载。 +5. 继续 [设置主题配置文件](#设置主题配置文件)。 + +#### 使用Git安装 + +对于这种方法，您需要确保在本地计算机上安装了 **Git**。 + +切换到您的Hugo网站目录（上面创建的目录），初始化一个新的 `git` 存储库并将刚果添加为子模块。 + +```bash +cd mywebsite +git init +git submodule add -b stable https://github.com/jpanther/congo.git themes/congo +``` + +然后继续 [设置主题配置文件](#设置主题配置文件)。 + +### 设置主题配置文件 + +在您的网站根目录中，删除由Hugo生成的 `config.toml` 文件。将主题中的 `*.toml` 配置文件复制到您的 `config/_default/` 文件夹中。这将确保您具有所有正确的主题设置，并使您能够轻松地根据需要自定义主题。 + +{{< alert >}} +**注意：** 如果您的项目中已存在 `module.toml` 文件，则不应覆盖它！ +{{< /alert >}} + +根据您安装主题的方式，您将在不同的位置找到主题配置文件： + +- **Hugo模块：** 在Hugo缓存目录中，或者从GitHub[下载一份副本](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/jpanther/congo/tree/stable/config/_default) +- **Git子模块或手动安装：** `themes/congo/config/_default` + +复制文件后，您的配置文件夹应如下所示： + +```shell +config/_default/ +├─ config.toml +├─ markup.toml +├─ menus.toml +├─ module.toml # 如果使用Hugo模块安装 +└─ params.toml +``` + +{{< alert >}} +**重要：** 如果您不是使用Hugo模块的方法安装Congo，则必须在您的 `config.toml` 文件顶部添加 `theme = "congo"` 这一行。 +{{< /alert >}} + +### 下一步 + +基本的刚果安装现在已经完成。继续查看 [入门](#入门) 部分，了解有关配置主题的更多信息。 + +--- + +## 安装更新 + +我们不时会发布[新的版本](https://github.com/jpanther/congo/releases)，其中包含对主题的修复和新功能。为了利用这些更改，您需要更新网站上的主题文件。 + +您执行此操作的方式将取决于主题最初安装时选择的安装方法。下面是每种方法的说明。 + +- [Hugo模块](#使用Hugo更新) +- [Git子模块](#使用Git更新) +- [手动文件复制](#手动更新) + +### 使用Hugo更新 + +Hugo使更新模块变得非常容易。只需切换到项目目录并执行以下命令： + +```shell +hugo mod get -u +``` + +Hugo将自动更新项目所需的任何模块。它通过检查您的 `module.toml` 和 `go.mod` 文件来完成。如果更新时出现任何问题，请检查这些文件是否仍然正确配置。 + +然后只需重新构建您的站点，并检查一切是否按预期工作。 + +{{< alert >}} +在更新模块时，有时Hugo会缓存主题的较旧版本。如果发生这种情况，请使用 `hugo mod clean` 命令清除本地缓存，然后重新构建您的站点。 +{{< /alert >}} + +### 使用Git更新 + +可以使用 `git` 命令更新Git子模块。只需执行以下命令，最新版本的主题将被下载到本地存储库中： + +```shell +git submodule update --remote --merge +``` + +一旦子模块已更新，重新构建您的站点并检查一切是否按预期工作。 + +### 手动更新 + +手动更新刚果需要您下载主题的最新副本，并替换项目中的旧版本。 + +{{< alert >}} +请注意，在此过程中，您对主题文件的任何本地自定义将丢失。 +{{< /alert >}} + +1. 下载主题源代码的最新发布版本。 + + {{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}从Github下载{{< /button >}} + +2. 解压缩存档，将文件夹重命名为 `congo`，并将其移动到Hugo项目根文件夹内的 `themes/` 目录。您需要覆盖现有目录以替换所有主题文件。 + +3. 重新构建您的站点 \ No newline at end of file diff --git a/exampleSite/content/docs/partials/index.zh-cn.md b/exampleSite/content/docs/partials/index.zh-cn.md new file mode 100644 index 00000000..8337854c --- /dev/null +++ b/exampleSite/content/docs/partials/index.zh-cn.md @@ -0,0 +1,114 @@ +--- +title: "Partials" +date: 2020-08-10 +draft: false +description: "Congo 主题中的所有partial。" +summary: "partials用于向主题添加特殊功能，包括分析、评论、网站图标、自定义脚本等等。" +slug: "partials" +tags: ["partials", "analytics", "privacy", "comments", "favicons", "icon", "docs"] +--- + +## Analytics + +Congo内置支持Fathom Analytics和Google Analytics。Fathom是Google Analytics的付费替代方案，尊重用户隐私。如果您感兴趣，可以使用此[推广链接](https://usefathom.com/ref/RLAJSV)获得$10的信用并尝试该服务。 + +### Fathom Analytics + +要启用Fathom Analytics支持，只需在 `config/_default/params.toml` 文件中提供您的Fathom站点代码。如果您还使用Fathom的自定义域功能，并希望从您的域提供其脚本，还可以提供`domain`配置值。如果不提供`domain`值，则脚本将直接从Fathom DNS加载。 + +```toml +# config/_default/params.toml + +[fathomAnalytics] + site = "ABC12345" + domain = "llama.yoursite.com" +``` + +### Plausible Analytics + +要启用 Plausible 分析支持，只需在 `config/_default/params.toml` 文件中提供您要跟踪的网站域。如果您使用的是自托管的 Plausible，或者希望使用 [代理分析](https://plausible.io/docs/proxy/introduction) 脚本和事件 API 路由，您还可以提供额外的 `event` 和 `script` 配置值。如果不提供这两个值，脚本将直接加载 Plausible 的默认托管服务。有关更多详细信息，请参阅 [使用代理进行分析](https://plausible.io/docs/proxy/introduction)。 + +```toml +# config/_default/params.toml + +[plausibleAnalytics] + domain = "blog.yoursite.com" + event = "https://plausible.yoursite.com/api/event" + script = "https://plausible.yoursite.com/js/script.js" +``` + +### Google Analytics + +要启用 Google Analytics 支持，只需在 `config/_default/config.toml` 文件中提供 `googleAnalytics` 键，脚本将自动添加。 + +根据提供的配置值，支持版本 3 (analytics.js) 和版本 4 (gtag.js)： + +```toml +# config/_default/config.toml + +# version 3 +googleAnalytics = "UA-PROPERTY_ID" +# version 4 +googleAnalytics = "G-MEASUREMENT_ID" +``` + +### 自定义分析提供商 + +如果您希望在您的网站上使用不同的分析提供商，您还可以覆盖分析 partial 并提供自己的脚本。只需在项目中创建文件 `layouts/partials/analytics.html`，它将自动包含在网站的 `` 中。 + +## 评论 + +要在文章中添加评论，Congo 包括对评论 partial 的支持，该 partial 包含在每篇文章页面的底部。只需提供一个包含显示您选择的评论所需代码的 `layouts/partials/comments.html`。 + +您可以使用内置的 Hugo Disqus 模板，也可以提供自己的自定义代码。有关详细信息，请参阅 [Hugo 文档](https://gohugo.io/content-management/comments/)。 + +一旦提供了 partial，就可以使用 `showComments` 参数来更精细地控制评论的显示位置。该值可以在 `params.toml` [配置文件]({{< ref "configuration#theme-parameters" >}})中在主题级别设置，也可以通过在 [front matter]({{< ref "front-matter" >}}) 中将其包含在每篇文章中。该参数默认为 `false`，因此必须在这些位置之一将其设置为 `true`，以便显示评论。 + +## 网站图标 + +Congo 提供了一组默认的空白网站图标，以便开始使用，但您可以提供自己的资产来覆盖它们。获取新网站图标资产的最简单方法是使用第三方提供商（例如 [favicon.io](https://favicon.io)）生成它们。 + +图标资产应直接放置在您网站的 `static/` 文件夹中，并按下面的清单命名。如果您使用 [favicon.io](https://favicon.io)，这些将是为您自动生成的文件名，但如果愿意，您也可以提供自己的资产。 + +```shell +static/ +├─ android-chrome-192x192.png +├─ android-chrome-512x512.png +├─ apple-touch-icon.png +├─ favicon-16x16.png +├─ favicon-32x32.png +├─ favicon.ico +└─ site.webmanifest +``` + +或者，您还可以完全覆盖默认的网站图标行为，并提供自己的网站图标 HTML 标签和资产。只需在您的项目中提供一个 `layouts/partials/favicons.html` 文件，它将被注入到站点的 `` 中，取代默认的资产。 + +## 图标 + +与 [图标 shortcode]({{< ref "shortcodes#icon" >}}) 类似，您可以通过使用 Congo 的 `icon.html` 部分在自己的模板和部分中包含图标。该部分接受一个参数，即要包含的图标的名称。 + +**例:** + +```go + {{ partial "icon.html" "github" }} +``` + +图标是使用 Hugo 管道生成的，这使它们非常灵活。Congo 包含了许多内置的图标，用于社交、链接和其他用途。查看 [图标示例]({{< ref "samples/icons" >}}) 页面，以获取支持的所有图标的完整列表。 + +您可以通过在项目的 `assets/icons/` 目录中提供自己的图标资产来添加自定义图标。然后，可以通过在没有 `.svg` 扩展名的情况下使用 SVG 文件名在部分中引用该图标。 + +图标还可以通过调用 [图标 shortcode]({{< ref "shortcodes#icon" >}}) 在文章内容中使用。 + +## 扩展 + +Congo 还提供了许多扩展部分，允许扩展基本功能。 + +### 文章链接 + +如果希望在文章链接后插入其他代码，请创建一个 `layouts/partials/extend-article-link.html` 文件。当与 [`badge`]({{< ref "shortcodes#badge" >}}) shortcode 结合使用时，这特别强大，可以用于突出显示某些文章的元数据。 + +### 头部和页脚 + +该主题允许直接将额外的代码插入到模板的 `` 和 `