From 6c1853ef0b1a886685f0a9b48ff71ba37554cfe8 Mon Sep 17 00:00:00 2001 From: Cell <1024@lruihao.cn> Date: Wed, 25 Sep 2024 18:01:57 +0800 Subject: [PATCH] =?UTF-8?q?Docs:=20=E6=9B=B4=E6=96=B0=E8=87=AA=E5=AE=9A?= =?UTF-8?q?=E4=B9=89=E6=A8=A1=E6=9D=BF=E7=9B=B8=E5=85=B3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- config/_default/params.toml | 8 +-- content/en/documentation/advanced/index.md | 7 ++- .../getting-started/configuration/index.md | 8 +++ content/en/references/blocks/index.md | 60 +++++++++++++------ content/zh-cn/documentation/advanced/index.md | 7 ++- .../getting-started/configuration/index.md | 8 +++ content/zh-cn/references/blocks/index.md | 60 +++++++++++++------ go.mod | 2 +- go.sum | 4 +- 9 files changed, 115 insertions(+), 49 deletions(-) diff --git a/config/_default/params.toml b/config/_default/params.toml index 9346877..06a1f9b 100644 --- a/config/_default/params.toml +++ b/config/_default/params.toml @@ -663,11 +663,11 @@ disableThemeInject = false # 是否在 feed 中显示全文内容。 fullText = true -# FixIt 0.3.12 | NEW Custom partials options -# Defined custom partials to be included in the /layouts/partials/ directory. +# FixIt 0.3.12 | NEW Custom partials config +# Custom partials must be stored in the /layouts/partials/ directory. # Depends on open custom blocks https://fixit.lruihao.cn/references/blocks/ -# FixIt 0.3.12 | 新增 自定义部分选项 -# 定义的自定义部分要包含在 /layouts/partials/ 目录中。 +# FixIt 0.3.12 | 新增 自定义部分配置 +# 自定义模板必须存放在 /layouts/partials/ 目录中。 # 依赖于开放的自定义块 https://fixit.lruihao.cn/references/blocks/ [customPartials] head = [ diff --git a/content/en/documentation/advanced/index.md b/content/en/documentation/advanced/index.md index b7f0799..349ba35 100644 --- a/content/en/documentation/advanced/index.md +++ b/content/en/documentation/advanced/index.md @@ -19,7 +19,7 @@ tags: toc: auto: false --- - + Discover advanced usage of the Hugo - **FixIt** theme. @@ -125,12 +125,15 @@ Hugo allows you to modify the theme by overriding the theme templates, for examp However, for most of the templates, FixIt theme generally doesn't recommend you do this, as it may make theme upgrades difficult in the future. -{{< version 0.3.7 >}} In order to avoid upgrade conflicts, based on this feature, the FixIt theme opens a unified custom template entry file, you can implement [Open Custom Blocks][block] through `define`. +{{< version 0.3.7 >}} + +In order to avoid upgrade conflicts, based on this feature, the FixIt theme opens a unified custom template entry file and configuration, see [Open Custom Blocks][block]. ## PWA Support This part is shown in the [pwa support page][pwa-support]. + [pwa-support]: {{< relref path="/guides/pwa-support" >}} [block]: {{< relref path="/references/blocks" >}} diff --git a/content/en/documentation/getting-started/configuration/index.md b/content/en/documentation/getting-started/configuration/index.md index 1af6dad..c530984 100644 --- a/content/en/documentation/getting-started/configuration/index.md +++ b/content/en/documentation/getting-started/configuration/index.md @@ -1256,6 +1256,12 @@ color theme : `string` The theme of pace. All available themes: `barber-shop`, `big-counter`, `bounce`, `center-atom`, `center-circle`, `center-radar`, `center-simple`, `corner-indicator`, `fill-left`, `flash`, `flat-top`, `loading-bar`, `mac-osx`, `material`, `minimal`. Default is `minimal`. +### customPartials + +{{< version 0.3.12 >}} + +`map` Custom partials Configuration. See [Open Custom Blocks][block]. + ### dev {{< version 0.2.15 >}} @@ -1644,6 +1650,7 @@ They're easily created via . ![Complete configuration preview](full-configuration-preview.png "Complete configuration preview") + [config]: https://github.com/hugo-fixit/FixIt/blob/master/hugo.toml [menu-system]: https://gohugo.io/content-management/menus/ [hugo-config]: https://gohugo.io/getting-started/configuration/ @@ -1656,6 +1663,7 @@ They're easily created via . [vercount]: https://vercount.one/ [busuanzi]: https://busuanzi.ibruce.info/ [pacejs]: https://github.com/CodeByZach/pace +[block]: {{< relref path="/references/blocks" >}} [configuration-markup]: https://gohugo.io/getting-started/configuration-markup/ [necessary-configuration-for-theme]: https://github.com/hugo-fixit/FixIt/issues/43 [hugo-output-formats]: https://gohugo.io/templates/output-formats/ diff --git a/content/en/references/blocks/index.md b/content/en/references/blocks/index.md index 42ab24f..8c3c278 100644 --- a/content/en/references/blocks/index.md +++ b/content/en/references/blocks/index.md @@ -14,13 +14,21 @@ To enhance the extensibility of the FixIt theme, we provide some custom blocks t +## What's the Meaning + +By opening custom blocks, the extensibility of the FixIt theme is further enhanced. + +After that, we can make full use of the basic features of the theme and build more upper-level components, so that the blog is full of unlimited imagination and creativity! + +![Theme, Components, Blog Venn Diagram](./featured-image.webp "Build multiple upper-level components based on the FixIt theme, and finally use them in the top-level blog.") + ## Entry File {{< version 0.3.7 >}} -The FixIt theme opens a unified custom template entry file [`layouts/partials/custom.html`][custom-html], through which you can implement custom blocks or more ideas. +The FixIt theme opens a unified custom template entry file [`layouts/partials/custom.html`][custom-html]. -To avoid upgrade conflicts and facilitate the reference of theme components, it's strongly recommended to copy this file from the theme to your project and override it. +In this file, the FixIt theme has defined all open custom blocks. If you want to further customize, you can copy it from the theme to your project and override it. ```bash cp themes/FixIt/layouts/partials/custom.html layouts/partials/custom.html @@ -42,35 +50,49 @@ You can implement these blocks through `define`. | `custom-post__footer:before` | Custom block before post footer | `layouts/posts/single.html` | | `custom-post__footer:after` | Custom block after post footer | `layouts/posts/single.html` | -## What's the Meaning +## Theme Configuration -By opening custom blocks, the extensibility of the FixIt theme is further enhanced. +{{< version 0.3.12 >}} -After that, we can make full use of the basic features of the theme and build more upper-level components, so that the blog is full of unlimited imagination and creativity! +To facilitate the management of introducing custom templates, you can specify the path of custom templates through the `params.customPartials` parameter. -![Theme, Components, Blog Venn Diagram](./featured-image.webp "Build multiple upper-level components based on the FixIt theme, and finally use them in the top-level blog.") +Custom partials must be stored in the `/layouts/partials/` directory. -## How to Use +```toml +[params] + [params.customPartials] + head = [] + profile = [] + aside = [] + comment = [] + footer = [] + widgets = [] + assets = [] + postFooterBefore = [] + postFooterAfter = [] +``` -For example, the FixIt theme documentation site customizes the `custom-profile` block on the homepage. +## How to Use -First, create a custom template entry file: +Now let's take the custom home page `custom-profile` block as an example to demonstrate how to use custom blocks. -```bash -cp themes/FixIt/layouts/partials/custom.html layouts/partials/custom.html -``` +At first, create a custom file in the `layouts/partials/` directory, such as `layouts/partials/custom/profile.html`. -Then, define the `custom-profile` block in the custom template: +Write any content: -```go-html-template {title="layouts/partials/custom.html"} - +```go-html-template +The quick brown fox jumps over the lazy dog. +``` -{{- define "custom-profile" -}} - {{- partial "custom/profile.html" . -}} -{{- end -}} +Then specify the path of the custom template in the configuration file. - +```toml +[params] + [params.customPartials] + profile = ["custom/profile.html"] ``` +Visit the homepage, and you will see the custom content in the `profile` area. + [custom-html]: https://github.com/hugo-fixit/FixIt/blob/master/layouts/partials/custom.html diff --git a/content/zh-cn/documentation/advanced/index.md b/content/zh-cn/documentation/advanced/index.md index d6ab761..036e5f9 100644 --- a/content/zh-cn/documentation/advanced/index.md +++ b/content/zh-cn/documentation/advanced/index.md @@ -19,7 +19,7 @@ tags: toc: auto: false --- - + 探索 Hugo - **FixIt** 主题的的进阶使用。 @@ -125,12 +125,15 @@ Hugo 允许你通过覆盖主题模板来改造主题，例如：你可以创建 但是，对于主题的大多数模板，我们通常不建议你这样做，因为这样可能会导致未来升级主题困难。 -{{< version 0.3.7 >}} 为了避免升级冲突问题，基于这一特性，FixIt 主题开放了统一的自定义模板入口文件，你可以通过 `define` 实现 [开放的自定义块][block]。 +{{< version 0.3.7 >}} + +为了避免升级冲突问题，基于这一特性，FixIt 主题开放了统一的自定义模板入口文件及配置，详见 [开放的自定义块][block]。 ## PWA 支持 这部分内容在 [PWA 支持页面][pwa-support] 中介绍。 + [pwa-support]: {{< relref path="/guides/pwa-support" >}} [block]: {{< relref path="/references/blocks" >}} diff --git a/content/zh-cn/documentation/getting-started/configuration/index.md b/content/zh-cn/documentation/getting-started/configuration/index.md index ee64cf4..89a7bdd 100644 --- a/content/zh-cn/documentation/getting-started/configuration/index.md +++ b/content/zh-cn/documentation/getting-started/configuration/index.md @@ -1247,6 +1247,12 @@ color theme : `string` 进度条主题，可选值：`barber-shop`、`big-counter`、`bounce`、`center-atom`、`center-circle`、`center-radar`、`center-simple`、`corner-indicator`、`fill-left`、`flash`、`flat-top`、`loading-bar`、`mac-osx`、`material`、`minimal`，默认：`minimal`。 +### customPartials + +{{< version 0.3.12 >}} + +`map` 自定义部分配置。详见 [开放的自定义块][block]。 + ### dev {{< version 0.2.15 >}} @@ -1635,6 +1641,7 @@ c4u ![完整配置下的预览](full-configuration-preview.zh-cn.png "完整配置下的预览") + [config]: https://github.com/hugo-fixit/FixIt/blob/master/hugo.toml [menu-system]: https://gohugo.io/content-management/menus/ [hugo-config]: https://gohugo.io/getting-started/configuration/ @@ -1647,6 +1654,7 @@ c4u [vercount]: https://vercount.one/ [busuanzi]: https://busuanzi.ibruce.info/ [pacejs]: https://github.com/CodeByZach/pace +[block]: {{< relref path="/references/blocks" >}} [configuration-markup]: https://gohugo.io/getting-started/configuration-markup/ [necessary-configuration-for-theme]: https://github.com/hugo-fixit/FixIt/issues/43 [hugo-output-formats]: https://gohugo.io/templates/output-formats/ diff --git a/content/zh-cn/references/blocks/index.md b/content/zh-cn/references/blocks/index.md index 1fd85dd..a0cbf6e 100644 --- a/content/zh-cn/references/blocks/index.md +++ b/content/zh-cn/references/blocks/index.md @@ -14,13 +14,21 @@ lightgallery: true +## 有何意义 + +通过开放自定义块，FixIt 主题的可扩展性进一步提升。 + +之后，我们可以充分利用主题的基础特性，构建更多上层组件，从而使博客充满无限的想象空间和创意！ + +![主题、组件、博客 Venn 图](/references/blocks/featured-image.webp "以 FixIt 主题为核心构建多个上层组件，最后在最上层的博客中使用。") + ## 入口文件 {{< version 0.3.7 >}} -FixIt 主题开放了统一的自定义模板入口文件 [`layouts/partials/custom.html`][custom-html]，你可以通过这个文件来实现自定义块或者更多的想法。 +FixIt 主题开放了统一的自定义模板入口文件 [`layouts/partials/custom.html`][custom-html]。 -为了避免升级冲突并方便引用主题组件，我们强烈建议你将此文件从主题复制到你的项目中并重写。 +在这个文件中，FixIt 主题已经定义了所有开放自定义块。如果你想进一步自定义，你可以将它从主题复制到你的项目中并重写。 ```bash cp themes/FixIt/layouts/partials/custom.html layouts/partials/custom.html @@ -42,35 +50,49 @@ cp themes/FixIt/layouts/partials/custom.html layouts/partials/custom.html | `custom-post__footer:before` | 文章页脚前自定义块 | `layouts/posts/single.html` | | `custom-post__footer:after` | 文章页脚后自定义块 | `layouts/posts/single.html` | -## 有何意义 +## 主题配置 -通过开放自定义块，FixIt 主题的可扩展性进一步提升。 +{{< version 0.3.12 >}} -之后，我们可以充分利用主题的基础特性，构建更多上层组件，从而使博客充满无限的想象空间和创意！ +为了便于管理引入自定义模板，可以通过 `params.customPartials` 参数来指定自定义模板的路径。 -![主题、组件、博客 Venn 图](/references/blocks/featured-image.webp "以 FixIt 主题为核心构建多个上层组件，最后在最上层的博客中使用。") +自定义模板必须存放在 `/layouts/partials/` 目录中。 -## 如何使用 +```toml +[params] + [params.customPartials] + head = [] + profile = [] + aside = [] + comment = [] + footer = [] + widgets = [] + assets = [] + postFooterBefore = [] + postFooterAfter = [] +``` -例如，FixIt 主题文档站点自定义了首页的 `custom-profile` 块。 +## 如何使用 -首先，创建自定义模板入口文件： +现在我们以自定义首页的 `custom-profile` 块为例，来演示如何使用自定义块。 -```bash -cp themes/FixIt/layouts/partials/custom.html layouts/partials/custom.html -``` +首先，在 `layouts/partials/` 目录下创建自定义文件，例如 `layouts/partials/custom/profile.html`。 -然后，在自定义模板中定义 `custom-profile` 块： +写入任意内容： -```go-html-template {title="layouts/partials/custom.html"} - +```go-html-template +The quick brown fox jumps over the lazy dog. +``` -{{- define "custom-profile" -}} - {{- partial "custom/profile.html" . -}} -{{- end -}} +然后，在配置文件中指定自定义模板的路径即可。 - +```toml +[params] + [params.customPartials] + profile = ["custom/profile.html"] ``` +访问首页，你会看到在 `profile` 区域显示了模板中自定义的内容。 + [custom-html]: https://github.com/hugo-fixit/FixIt/blob/master/layouts/partials/custom.html diff --git a/go.mod b/go.mod index af6db63..df21778 100644 --- a/go.mod +++ b/go.mod @@ -3,7 +3,7 @@ module github.com/hugo-fixit/docs go 1.20 require ( - github.com/hugo-fixit/FixIt v0.3.12-0.20240925083026-0eab22d0362a // indirect + github.com/hugo-fixit/FixIt v0.3.12-0.20240925102835-954d86432f3e // indirect github.com/hugo-fixit/component-projects v1.1.3 // indirect github.com/hugo-fixit/shortcode-caniuse v1.1.3 // indirect github.com/hugo-fixit/shortcode-rewards v1.0.4 // indirect diff --git a/go.sum b/go.sum index e8a483c..dc81d6b 100644 --- a/go.sum +++ b/go.sum @@ -1,5 +1,5 @@ -github.com/hugo-fixit/FixIt v0.3.12-0.20240925083026-0eab22d0362a h1:oO4rKG2xHkeZprFX5iSO2vLGGMcZOMupvpZdFFEMtgA= -github.com/hugo-fixit/FixIt v0.3.12-0.20240925083026-0eab22d0362a/go.mod h1:3XIRedrqakO7/a4ZnhE46haMRF8HgsT0N0B5j5D2iRU= +github.com/hugo-fixit/FixIt v0.3.12-0.20240925102835-954d86432f3e h1:7a6PDPQVPr/Ch3MB6M6J4Bqa4RDB8YhcLuCIp9hUsn4= +github.com/hugo-fixit/FixIt v0.3.12-0.20240925102835-954d86432f3e/go.mod h1:3XIRedrqakO7/a4ZnhE46haMRF8HgsT0N0B5j5D2iRU= github.com/hugo-fixit/component-projects v1.1.3 h1:iK6q07CpFsnnJGh8q2stVjv6Lr77dTM9o+P7LGDEYmE= github.com/hugo-fixit/component-projects v1.1.3/go.mod h1:nXW0R37REwpfwUD1I4RtB5QW71vw66nRyB9uEpYxr+c= github.com/hugo-fixit/shortcode-caniuse v1.1.3 h1:U1YBJz5SI/d1BBQhHcD0eVgJdCcpzK2usSizPiu+a4w=