Merge branch 'dev'

* dev: Docs: 增加菜单自定义块 Docs: 更新 CSE 教程 Docs: 增加 Google CSE 支持，并增加文档和教程 (hugo-fixit/FixIt#244)
hugo-fixit · Dec 2, 2024 · 4931221 · 4931221
2 parents cd989e4 + ac09083
commit 4931221
Show file tree

Hide file tree

Showing 15 changed files with 316 additions and 10 deletions.
diff --git a/config/_default/params.en.toml b/config/_default/params.en.toml
@@ -10,6 +10,10 @@
   [search.algolia]
     index = "index.en"
 
+[cse]
+  [cse.google]
+    cx = "27010f0a2633d4da4"
+
 [header]
   [header.subtitle]
     name = "Theme for Hugo"

diff --git a/config/_default/params.toml b/config/_default/params.toml
@@ -105,8 +105,8 @@ disableThemeInject = false
 # 搜索配置
 [search]
   enable = true
-  # type of search engine ["algolia", "fuse"]
-  # 搜索引擎的类型 ["algolia", "fuse"]
+  # type of search engine ["algolia", "fuse", "cse"]
+  # 搜索引擎的类型 ["algolia", "fuse", "cse"]
   type = "algolia"
   # max index length of the chunked content
   # 文章内容最长索引长度
@@ -142,6 +142,23 @@ disableThemeInject = false
     useExtendedSearch = false
     ignoreFieldNorm = false
 
+# FixIt 0.3.16 | NEW Custom Search Engine (CSE)
+# FixIt 0.3.16 | 新增 自定义搜索引擎 (CSE)
+[cse]
+  # Search Engine: ["google", "bing"]
+  # 搜索引擎：["google", "bing"]
+  engine = "google"
+  # Search results page URL (layout: search)
+  # 搜索结果页面 URL (layout: search)
+  resultsPage = "/search/"
+  # Google: https://programmablesearchengine.google.com/
+  # Google Custom Search Engine Context
+  # Google 自定义搜索引擎 ID
+  [cse.google]
+    cx = ""
+  # Bing (Unsupported): https://www.customsearch.ai/
+  [cse.bing]
+
 # Header config
 # 页面头部导航栏配置
 [header]

diff --git a/config/_default/params.zh-cn.toml b/config/_default/params.zh-cn.toml
@@ -12,6 +12,11 @@ description = "一个简洁、优雅且高效的 Hugo 主题 FixIt"
   [search.algolia]
     index = "index.zh-cn"
 
+[cse]
+  resultsPage = "/zh-cn/search/"
+  [cse.google]
+    cx = "83ffebf0680ff4971"
+
 [header]
   [header.subtitle]
     name = "Hugo 主题"

diff --git a/content/en/documentation/content-management/introduction/index.md b/content/en/documentation/content-management/introduction/index.md
@@ -101,6 +101,12 @@ Set `layout: friends` in the front matter and create data file named `friends.ym
 > hugo new friends/index.md
 > ```
 
+### Search
+
+{{< version 0.3.16 >}}
+
+See [CSE Support][cse-support].
+
 ### Projects
 
 This is an additional theme component, please refer to [hugo-fixit/component-projects].
@@ -508,6 +514,7 @@ By the way, as these translations could be used by other people, please take the
 [page-resources]: https://gohugo.io/content-management/page-resources/
 [page-bundles]: https://gohugo.io/content-management/page-bundles/
 [front-matter]: https://gohugo.io/content-management/front-matter/
+[cse-support]: {{< relref path="/guides/cse-support" >}}
 [hugo-fixit/component-projects]: /ecosystem/hugo-fixit/component-projects/
 [theme-config]: {{< relref path="/documentation/getting-started/configuration#theme-configuration" >}}
 [content-to-menu]: {{< relref path="/documentation/getting-started/configuration#content-to-menu" >}}

diff --git a/content/en/documentation/getting-started/configuration/index.md b/content/en/documentation/getting-started/configuration/index.md
@@ -488,7 +488,7 @@ enable
 : `bool` Whether to enable search. Default is `false`.
 
 type
-: `string` The type of search engine. The configuration value for `type` can be one of `algolia`, `fuse`. Default is `fuse`.
+: `string` The type of search engine. The configuration value for `type` can be one of `algolia`, `fuse` or `cse`. Default is `fuse`.
 
 contentLength
 : `int` The max index length of the chunked content. Default is `4000`.
@@ -531,7 +531,7 @@ fuse
 
 ---
 
-Based on [algolia][algolia] or [Fuse.js][fusejs], searching is supported in **FixIt** theme.
+Based on [algolia][algolia], [Fuse.js][fusejs] or [Custom Search Engine](#cse), searching is supported in **FixIt** theme.
 
 In order to generate `search.json` for searching, add `search` output file type to the `home` of the `outputs` part in your site configuration.
 
@@ -542,6 +542,36 @@ In order to generate `search.json` for searching, add `search` output file type
 
 {{< link href="/guides/algolia-atomic" content="Tips about algolia" card=true >}}
 
+### cse
+
+{{< version 0.3.16 >}}
+
+`map` The Custom Search Engine (CSE) Configuration. See [CSE Support][cse-support].
+
+```toml
+[params]
+  [params.cse]
+    engine = ""
+    resultsPage = "/search/"
+    [params.cse.google]
+      cx = ""
+    [params.cse.bing]
+```
+
+engine
+: `string` The search engine. The configuration value for `engine` can be one of `google`, `bing`.
+
+resultsPage
+: `string` The search results page URL (`layout: search`). Default is `/search/`.
+
+google
+: `map` The [Google Custom Search Engine][google-cse] Configuration.
+
+- cx: `string` The Google Custom Search Engine Context ID.
+
+bing
+: `map` The [Bing Custom Search Engine][bing-cse] Configuration. (Unsupported)
+
 ### header
 
 `map` The Header Configuration.
@@ -1812,6 +1842,9 @@ They're easily created via <https://realfavicongenerator.net/>.
 [algolia]: https://www.algolia.com/
 [fusejs]: https://fusejs.io/
 [fusejs-options]: https://fusejs.io/api/options.html
+[cse-support]: {{< relref path="/guides/cse-support" >}}
+[google-cse]: https://programmablesearchengine.google.com/
+[bing-cse]: https://www.customsearch.ai/
 [custom-admonitions]: {{< relref "/documentation/advanced#custom-admonitions" >}}
 [custom-task-lists]: {{< relref "/documentation/advanced#custom-task-lists" >}}
 [mermaid-themes]: https://mermaid.js.org/config/theming.html#available-themes

diff --git a/content/en/guides/cse-support/index.md b/content/en/guides/cse-support/index.md
@@ -0,0 +1,93 @@
+--- 
+title: CSE Support
+date: 2024-11-28T15:01:29+08:00
+categories:
+  - Guides
+  - Documentation
+tags: 
+  - CSE
+  - Advanced
+resources:
+  - name: featured-image
+    src: cover.webp
+description: Guide to setup CSE in FixIt.
+---
+
+Find out how to setup Custom Search Engine in FixIt.
+
+<!--more-->
+
+## What is CSE?
+
+**Custom Search Engine** (CSE) lets you create a search engine for your website, your blog, or a collection of websites. You can configure your search engine to search both web pages and images. You can fine-tune the ranking, customize the look and feel of the search results etc.
+
+Common search engines have their own CSE services, such as:
+
+- [Google Programmable Search Engine][google-cse]
+- [Bing Custom Search][bing-cse]
+
+## Configure CSE in FixIt
+
+{{< version 0.3.16 >}}
+
+First, manually create a search result display page:
+
+```bash
+hugo new content search/index.md
+```
+
+To configure Google or Bing CSE in the FixIt theme:
+
+```toml
+[params]
+  [params.search]
+    enable = true
+    type = "cse"
+  [params.cse]
+    # Search engine: ["google", "bing"]
+    engine = "google"
+    resultsPage = "/search/"
+    [params.cse.google]
+      cx = ""
+    [params.cse.bing]
+      # Unsupported yet
+```
+
+## Google CSE
+
+Google CSE, also known as Google Programmable Search Engine, this section mainly introduces how to use Google CSE in FixIt. You can go to [Programmable Search Engine Tutorial][google-cse-tutorial] page to view the complete tutorial.
+
+Follow the steps below to create a Google search engine:
+
+```timeline {animation=true}
+events:
+  - content: "Create a new search engine in [Google Programmable Search Engine](https://programmablesearchengine.google.com/)."
+  - content: "Enter your search engine name, for example: `FixIt`."
+  - content: "Select to search specific sites or pages, and enter your site URL. e.g. `fixit.lruihao.cn`."
+  - content: "Click the `Create` button."
+  - content: 'After a moment, the page will prompt you: "A new search engine has been created", then click the `Customize` button to enter the search engine customization page.'
+  - content: "**Click Appearance and Style => Layout => Select `Two-column`**. (==This step is crucial, do not ignore it!==)"
+    type: warning
+  - content: "Finally, click Overview and copy your search engine ID."
+    type: info
+  - content: "Paste the search engine ID into the `cx` field in the configuration file."
+    type: primary
+  - content: "🎉 Congratulations! Restart the Hugo server and try the search feature."
+    type: success
+```
+
+## Bing CSE
+
+> [!WARNING]
+> Bing CSE is not supported in FixIt yet.
+
+<!--
+Bing Custom Search is similar to Google CSE, but the configuration is different. You can go to the [Bing Custom Search][bing-cse] page to view the complete tutorial.
+
+Follow these steps to create a new custom search instance:
+-->
+
+<!-- link reference definition -->
+[google-cse]: https://programmablesearchengine.google.com/
+[bing-cse]: https://www.customsearch.ai/
+[google-cse-tutorial]: https://programmablesearchengine.google.com/about/
diff --git a/content/en/references/blocks/index.md b/content/en/references/blocks/index.md
@@ -40,6 +40,8 @@ You can implement these blocks through `define`.
 | Block Name                   | Description                     | Location                               |
 | :--------------------------- | :------------------------------ | :------------------------------------- |
 | `custom-head`                | Head custom block               | `layouts/_default/baseof.html`         |
+| `custom-menu:desktop`        | Desktop menu custom block       | `layouts/partials/header.html`         |
+| `custom-menu:mobile`         | Mobile menu custom block        | `layouts/partials/header.html`         |
 | `custom-profile`             | Profile custom block            | `layouts/partials/home/profile.html`   |
 | `custom-comment`             | Comment system custom block     | `layouts/partials/single/comment.html` |
 | `custom-aside`               | Sidebar custom block            | `layouts/posts/single.html`            |

diff --git a/content/en/search/index.md b/content/en/search/index.md
@@ -0,0 +1,5 @@
+---
+title: Search
+layout: search
+date: 2024-11-28T15:58:33+08:00
+---
diff --git a/content/zh-cn/documentation/content-management/introduction/index.md b/content/zh-cn/documentation/content-management/introduction/index.md
@@ -99,9 +99,15 @@ type: posts
 > 你可以使用以下命令快速创建友情链接页面：
 >
 > ```bash
-> hugo new friends/index.md
+> hugo new content friends/index.md
 > ```
 
+### 搜索结果
+
+{{< version 0.3.16 >}}
+
+详见 [CSE 支持][cse-support]。
+
 ### 项目页面
 
 这是一个额外的主题组件，具体请查看 [hugo-fixit/component-projects]。
@@ -508,6 +514,7 @@ defaultContentLanguage = "zh-cn"
 [page-resources]: https://gohugo.io/content-management/page-resources/
 [page-bundles]: https://gohugo.io/content-management/page-bundles/
 [front-matter]: https://gohugo.io/content-management/front-matter/
+[cse-support]: {{< relref path="/guides/cse-support" >}}
 [hugo-fixit/component-projects]: /ecosystem/hugo-fixit/component-projects/
 [theme-config]: {{< relref path="/documentation/getting-started/configuration#theme-configuration" >}}
 [content-to-menu]: {{< relref path="/documentation/getting-started/configuration#content-to-menu" >}}

diff --git a/content/zh-cn/documentation/getting-started/configuration/index.md b/content/zh-cn/documentation/getting-started/configuration/index.md
@@ -490,7 +490,7 @@ enable
 : `bool` 是否启用搜索。
 
 type
-: `string` 搜索引擎的类型，可选值：`algolia`、`fuse`，默认：`fuse`。
+: `string` 搜索引擎的类型，可选值：`algolia`、`fuse` 或 `cse`，默认：`fuse`。
 
 contentLength
 : `int` 文章内容最长索引长度。
@@ -533,7 +533,7 @@ fuse
 
 ---
 
-基于 [algolia][algolia] 或 [Fuse.js][fusejs]，**FixIt** 主题支持搜索功能。
+基于 [algolia][algolia]、[Fuse.js][fusejs] 或者 [自定义搜索引擎](#cse)，**FixIt** 主题支持搜索功能。
 
 为了生成搜索功能所需要的 `search.json`, 请在你的站点配置中添加 `search` 输出文件类型到 `outputs` 部分的 `home` 字段中。
 
@@ -544,6 +544,36 @@ fuse
 
 {{< link href="/zh-cn/guides/algolia-atomic/" content="关于 algolia 的使用技巧" card=true >}}
 
+### cse
+
+{{< version 0.3.16 >}}
+
+`map` 自定义搜索引擎（CSE）配置，详见 [CSE 支持][cse-support]。
+
+```toml
+[params]
+  [params.cse]
+    engine = ""
+    resultsPage = "/search/"
+    [params.cse.google]
+      cx = ""
+    [params.cse.bing]
+```
+
+engine
+: `string` 搜索引擎。`engine` 的配置值可以是 `google` 或 `bing`。
+
+resultsPage
+: `string` 搜索结果页面 URL（`layout: search`）。默认为 `/search/`。
+
+google
+: `map` [Google 自定义搜索引擎][google-cse] 配置。
+
+- cx: `string` Google 自定义搜索引擎上下文 ID。
+
+bing
+: `map` [Bing 自定义搜索引擎][bing-cse] 配置。 (暂不支持)
+
 ### header
 
 `map` 页面头部导航栏配置。
@@ -1811,6 +1841,9 @@ c4u
 [algolia]: https://www.algolia.com/
 [fusejs]: https://fusejs.io/
 [fusejs-options]: https://fusejs.io/api/options.html
+[cse-support]: {{< relref path="/guides/cse-support" >}}
+[google-cse]: https://programmablesearchengine.google.com/
+[bing-cse]: https://www.customsearch.ai/
 [custom-admonitions]: {{< relref "/documentation/advanced#custom-admonitions" >}}
 [custom-task-lists]: {{< relref "/documentation/advanced#custom-task-lists" >}}
 [mermaid-themes]: https://mermaid.js.org/config/theming.html#available-themes