feat(glossary): provide basic term glossary (#869)

* feat(glossary): provide basic term glossary

Enabled a site-wide terminology glossary.

* Added the `term` shortcode displaying term definition.
* Added the /glossary page showing all term definitions.
* Enabled a simplistic search of term definitions.

* refactor(glossary): update glossary page links and add callout for Hugo support

- Removed the glossary entry from the menu and adjusted weights for subsequent items.
- Added informational callouts in the glossary documentation for multiple languages, directing users to the Hugo Glossary Quick Reference.
- Updated links in the glossary documentation to point to the correct pages.

* fix(glossary): update links to glossary page format across multiple languages

- Changed links in the glossary documentation to use Hugo's relref format for consistency.
- Updated links in Persian, Japanese, English, and Simplified Chinese glossary pages.

---------

Co-authored-by: Xin <5097752+imfing@users.noreply.github.com>
Co-authored-by: Xin <xin@imfing.com>
This commit is contained in:
yuri
2026-01-19 23:33:09 +01:00
committed by GitHub
parent 66a9d98630
commit 5028140432
28 changed files with 461 additions and 3 deletions

File diff suppressed because one or more lines are too long

View File

@@ -43,6 +43,12 @@ body {
@apply hx:outline-none hx:ring-2 hx:ring-primary-200 hx:ring-offset-1 hx:ring-offset-primary-300 hx:dark:ring-primary-800 hx:dark:ring-offset-primary-700;
}
@layer base {
abbr:where([title]) {
cursor: help;
}
}
@import "./typography.css";
@import "./highlight.css";
@import "./components/cards.css";

View File

@@ -18,4 +18,20 @@
{{- $output = $output | merge (dict $pageLink (dict "title" $pageTitle "data" $data)) -}}
{{- end -}}
{{/* Extract glossary data entries */}}
{{- $glossaryEntries := dict -}}
{{- with (index .Site.Data .Site.Language.Lang "termbase") -}}
{{- range . -}}
{{- $entry := cond (.abbr) (printf "%s %s %s" .abbr .term .definition) (printf "%s %s" .term .definition) -}}
{{- $glossaryEntries = $glossaryEntries | merge (dict .term $entry) -}}
{{- end -}}
{{- end -}}
{{- $glossary := dict
"title" "Glossary"
"data" $glossaryEntries
-}}
{{- $output = $output | merge (dict (relLangURL "glossary") $glossary )}}
{{- $output | jsonify -}}

View File

@@ -0,0 +1,4 @@
---
title: Glossary
layout: glossary
---

View File

@@ -0,0 +1,4 @@
---
title: واژه‌نامه
layout: glossary
---

View File

@@ -0,0 +1,4 @@
---
title: 用語集
layout: glossary
---

View File

@@ -0,0 +1,4 @@
---
title: 术语表
layout: glossary
---

View File

@@ -13,4 +13,5 @@ This section covers some advanced topics of the theme.
{{< card link="multi-language" title="Multi-language" icon="translate" >}}
{{< card link="customization" title="Customization" icon="pencil" >}}
{{< card link="comments" title="Comments System" icon="chat-alt" >}}
{{< card link="glossary" title="Glossary" icon="library" >}}
{{< /cards >}}

View File

@@ -0,0 +1,49 @@
---
title: "واژه‌نامه"
weight: 1
prev: /docs/advanced
---
Hextra از ایجاد واژه‌نامهٔ اصطلاحات در سطح کل سایت پشتیبانی می‌کند.
<!--more-->
{{< callout type="info" >}}
برای اطلاعات بیشتر دربارهٔ پشتیبانی واژه‌نامهٔ داخلی Hugo، به [مرجع سریع واژه‌نامهٔ Hugo](https://gohugo.io/quick-reference/glossary/) مراجعه کنید.
{{< /callout >}}
## فایل دادهٔ منبع
تعاریف اصطلاحات به‌صورت متمرکز در فایل دادهٔ `termbase.yaml` برای هر [زبان پشتیبانی‌شده](../multi-language/) ذخیره می‌شوند.
{{< filetree/container >}}
{{< filetree/folder name="data" state="open" >}}
{{< filetree/folder name="en" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="fr" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="ja" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< /filetree/container >}}
هر فایل YAML شامل فهرستی از اصطلاحات واژه‌نامه است. هر ورودی شامل موارد زیر است:
* `term`: نام کامل مفهوم یا عبارت.
* `definition`: توضیح یا شرح مختصر اصطلاح.
* `abbr` (اختیاری): مخفف یا سرواژهٔ رایج اصطلاح.
```yaml {filename="data/fa/termbase.yaml"}
- term: seo
abbr: SEO
definition: "بهینه‌سازی موتور جستجو افزایش دیده‌شدن یک صفحهٔ وب در نتایج موتورهای جستجو"
- term: "سازندهٔ سایت ایستا"
definition: "موتورهایی که ورودی متنی را پردازش کرده و صفحات وب ایستا تولید می‌کنند"
```
## صفحهٔ واژه‌نامه
نمونهٔ صفحهٔ واژه‌نامه در [واژه‌نامه]({{% relref "/glossary" %}}) در دسترس است و شامل تمام اصطلاحات تعریف‌شده همراه با توضیحات و مخفف‌هاست.

View File

@@ -0,0 +1,49 @@
---
title: "用語集"
weight: 1
prev: /docs/advanced
---
Hextra は、サイト全体で使用する用語集の構築をサポートしています。
<!--more-->
{{< callout type="info" >}}
Hugo の用語集サポートの詳細については、[Hugo 用語集クイックリファレンス](https://gohugo.io/quick-reference/glossary/)をご覧ください。
{{< /callout >}}
## データソースファイル
用語の定義は、各[対応言語](../multi-language/)ごとに `termbase.yaml` データファイルに一元管理されています。
{{< filetree/container >}}
{{< filetree/folder name="data" state="open" >}}
{{< filetree/folder name="en" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="fr" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="ja" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< /filetree/container >}}
各 YAML データファイルには、用語の一覧が含まれています。各エントリには以下が含まれます:
* `term`:概念やフレーズの正式名称。
* `definition`:用語の簡潔な説明。
* `abbr`(任意):一般的に使用される略語や頭字語。
```yaml {filename="data/ja/termbase.yaml"}
- term: seo
abbr: SEO
definition: "検索エンジン最適化 — ウェブページの検索エンジンでの可視性を向上させる手法"
- term: "静的サイトジェネレーター"
definition: "テキスト入力を処理して静的なウェブページを生成するソフトウェアエンジン"
```
## 用語ページ
用語集のサンプルページは [用語集]({{% relref "/glossary" %}}) で確認できます。すべての定義済み用語とその説明・略語が表示されます。

View File

@@ -0,0 +1,50 @@
---
title: "Glossary"
weight: 1
prev: /docs/advanced
---
Hextra supports building a site-wide terminology glossary.
<!--more-->
{{< callout type="info" >}}
For more information about Hugo's built-in glossary support, see the [Hugo Glossary Quick Reference](https://gohugo.io/quick-reference/glossary/).
{{< /callout >}}
## Source Data File
Term definitions are centrally stored in a `termbase.yaml` data file for each [supported language](../multi-language/).
{{< filetree/container >}}
{{< filetree/folder name="data" state="open" >}}
{{< filetree/folder name="en" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="fr" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="ja" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< /filetree/container >}}
Each YAML data file contains a list of glossary entries. Every entry includes:
* `term`: The full name of the concept or phrase.
* `definition`: A brief explanation or description of the term.
* `abbr` (optional): A commonly used abbreviation or acronym for the term.
```yaml {filename="data/en/termbase.yaml"}
- term: seo
abbr: SEO
definition: "Search engine optimization improving the visibility of a web page in search engines"
- term: static site generator
definition: "Software engines processing text input to generate static web pages"
```
## Glossary Page
An example glossary page is available at [Glossary]({{% relref "/glossary" %}}), displaying all
defined terms with their descriptions and abbreviations.

View File

@@ -0,0 +1,49 @@
---
title: "术语表"
weight: 1
prev: /docs/advanced
---
Hextra 支持构建全站范围的术语词汇表。
<!--more-->
{{< callout type="info" >}}
有关 Hugo 内置术语表支持的更多信息,请参阅 [Hugo 术语表快速参考](https://gohugo.io/quick-reference/glossary/)。
{{< /callout >}}
## 数据源文件
术语定义集中存储在每种[支持语言](../multi-language/)的 `termbase.yaml` 数据文件中。
{{< filetree/container >}}
{{< filetree/folder name="data" state="open" >}}
{{< filetree/folder name="en" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="fr" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="ja" state="open" >}}
{{< filetree/file name="termbase.yaml" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< /filetree/container >}}
每个 YAML 数据文件包含一组术语条目。每个条目包括:
* `term`:术语或短语的完整名称。
* `definition`:对术语的简要解释或描述。
* `abbr`(可选):术语常用的缩写或首字母缩写。
```yaml {filename="data/zh-cn/termbase.yaml"}
- term: seo
abbr: SEO
definition: "搜索引擎优化——提高网页在搜索引擎中的可见度"
- term: "静态网站生成器"
definition: "将文本输入处理为静态网页的生成引擎"
```
## 术语页面
术语表示例页面可在 [术语表]({{% relref "/glossary" %}}) 查看,显示所有定义的术语及其描述和缩写。

View File

@@ -1,7 +1,7 @@
---
title: "Multi-language"
weight: 1
prev: /docs/advanced
prev: /docs/advanced/glossary
---
Hextra supports creating site with multiple languages using Hugo's [multilingual mode](https://gohugo.io/content-management/multilingual/).

View File

@@ -14,6 +14,7 @@ Hextra provides a collection of beautiful shortcodes to enhance your content.
{{< card link="cards" title="Cards" icon="card" >}}
{{< card link="details" title="Details" icon="chevron-right" >}}
{{< card link="filetree" title="FileTree" icon="folder-tree" >}}
{{< card link="term" title="Term" icon="question-mark-circle" >}}
{{< card link="icon" title="Icon" icon="badge-check" >}}
{{< card link="steps" title="Steps" icon="one" >}}
{{< card link="tabs" title="Tabs" icon="collection" >}}

View File

@@ -1,6 +1,6 @@
---
title: Tabs
next: /docs/guide/deploy-site
next: /docs/guide/term
---
## Example

View File

@@ -0,0 +1,28 @@
---
title: اصطلاح
next: /docs/guide/deploy-site
---
یک مؤلفهٔ داخلی برای نمایش تعریف اصطلاحات.
تعاریف اصطلاحات در یک [فایل دادهٔ YAML](/docs/advanced/glossary#source-data-file) ساختاریافته نگهداری می‌شوند،
و برای هر زبان پشتیبانی‌شده یک فایل جداگانه تعریف می‌گردد.
## مثال
* {{< term "سازندهٔ سایت ایستا" >}}
* {{< term "SEO" >}}
## نحوهٔ استفاده
```
{{</* term "SEO" */>}}
```
اگر اصطلاحی در واژه‌نامه یافت نشود، همان‌طور که وارد شده نمایش داده می‌شود.
## گزینه‌ها
| نام | توضیح |
|---------------|----------------------------|
| `entry` | اصطلاح واژه‌نامه |

View File

@@ -0,0 +1,28 @@
---
title: 用語
next: /docs/guide/deploy-site
---
用語の定義を表示するための組み込みコンポーネントです。
用語の定義は、構造化された YAML [データファイル](/docs/advanced/glossary#source-data-file)で管理されており、
対応する言語ごとに1つのファイルが定義されています。
## 例
* {{< term "静的サイトジェネレーター" >}}
* {{< term "SEO" >}}
## 使用方法
```
{{</* term "SEO" */>}}
```
用語が用語集に存在しない場合は、そのまま表示されます。
## オプション
| 名前 | 説明 |
|--------------|--------------------------|
| `entry` | 用語名 |

View File

@@ -0,0 +1,29 @@
---
title: Term
next: /docs/guide/deploy-site
---
A built-in component to display a terminology definition.
Glossary definition is maintained in a structured YAML [data file](/docs/advanced/glossary#source-data-file),
with one file defined per supported language.
## Example
* {{< term "static site generator" >}}
* {{< term "SEO" >}}
## Usage
```
{{</* term "SEO" */>}}
```
If a term is not found in the glossary, it is returned as-is.
## Options
| Name | Description |
|--------------|-----------------------------|
| `entry` | Glossary term |

View File

@@ -0,0 +1,28 @@
---
title: 术语
next: /docs/guide/deploy-site
---
一个用于显示术语定义的内置组件。
术语定义保存在结构化的 YAML [数据文件](/docs/advanced/glossary#source-data-file)中,
每种支持的语言对应一个文件。
## 示例
* {{< term "静态网站生成器" >}}
* {{< term "SEO" >}}
## 用法
```
{{</* term "SEO" */>}}
```
如果术语在词汇表中未找到,则会原样返回该术语。
## 选项
| 名称 | 描述 |
|--------------|------------------|
| `entry` | 术语名称 |

View File

@@ -0,0 +1,12 @@
---
# Terminology glossary
#
# Example usage of term.html shortcode:
#
# {{< term "SEO" >}}
- term: seo
abbr: SEO
definition: "Search engine optimization improving the visibility of a web page in search engines"
- term: static site generator
definition: "Software engines processing text input to generate static web pages"

View File

@@ -0,0 +1,12 @@
---
# واژه‌نامه اصطلاحات
#
# نمونه‌ای از استفاده از term.html:
#
# {{< term "SEO" >}}
- term: seo
abbr: SEO
definition: "بهینه‌سازی موتور جستجو افزایش دیده‌شدن یک صفحهٔ وب در نتایج موتورهای جستجو"
- term: "سازندهٔ سایت ایستا"
definition: "موتورهایی که ورودی متنی را پردازش کرده و صفحات وب ایستا تولید می‌کنند"

View File

@@ -0,0 +1,12 @@
---
# 用語集
#
# term.html ショートコードの使用例:
#
# {{< term "SEO" >}}
- term: seo
abbr: SEO
definition: "検索エンジン最適化 — ウェブページの検索エンジンでの可視性を向上させる手法"
- term: "静的サイトジェネレーター"
definition: "テキスト入力を処理して静的なウェブページを生成するソフトウェアエンジン"

View File

@@ -0,0 +1,12 @@
---
# 术语词汇表
#
# term.html shortcode 的使用示例:
#
# {{< term "SEO" >}}
- term: seo
abbr: SEO
definition: "搜索引擎优化——提高网页在搜索引擎中的可见度"
- term: "静态网站生成器"
definition: "将文本输入处理为静态网页的生成引擎"

View File

@@ -1,6 +1,7 @@
documentation: "مستندات"
showcase: "ویترین"
blog: "وبلاگ"
glossary: "واژه‌نامه"
about: "درباره ما"
more: "بیشتر"
hugoDocs: "مستندات هیوگو ↖"

View File

@@ -1,6 +1,7 @@
documentation: "ドキュメント"
showcase: "展示"
blog: "ブログ"
glossary: "用語集"
about: "概要"
more: "もっと見る"
hugoDocs: "Hugo ドキュメント ↗"

View File

@@ -1,6 +1,7 @@
documentation: "文档"
showcase: "项目展示"
blog: "博客"
glossary: "术语表"
about: "关于"
more: "更多"
hugoDocs: "Hugo 文档 ↗"

View File

@@ -0,0 +1,32 @@
{{- /*
Highlight a glossary term
@param {string} entry Either the glossary abbreviation or the term.
or
@param {string} 0 Either the glossary abbreviation or the term.
@example {{< term entry="MAC" >}}
@example {{< term "MAC" >}}
*/ -}}
{{- $entry := .Get "entry" | default (.Get 0) -}}
{{- $entryLower := lower $entry -}}
{{- $match := dict -}}
<!-- Go over the term data file - data/<lang>/termbase.yaml -->
{{- range (index .Site.Data .Site.Language.Lang "termbase") -}}
{{- if or (eq (lower .abbr) $entryLower) (eq (lower .term) $entryLower) -}}
{{- $match = . -}}
{{- break -}}
{{- end -}}
{{- end -}}
{{- with $match }}
<abbr title="{{ .definition | plainify }}">
{{- $entry -}}
</abbr>
{{- else }}
{{- $entry -}}
{{- end }}

25
layouts/glossary.html Normal file
View File

@@ -0,0 +1,25 @@
{{ define "main" }}
<div class='hx:mx-auto hx:flex hextra-max-page-width'>
{{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" true) }}
{{ partial "toc.html" (dict "Params" (dict "toc" false)) }}
<article class="hx:w-full hx:break-words hx:flex hx:min-h-[calc(100vh-var(--navbar-height))] hx:min-w-0 hx:justify-center hx:pb-8 hx:pr-[calc(env(safe-area-inset-right)-1.5rem)]">
<main class="hx:w-full hx:min-w-0 hx:max-w-6xl hx:px-6 hx:pt-4 hx:md:px-12">
{{ if .Title }}<h1 class="hx:text-center hx:mt-2 hx:text-4xl hx:font-bold hx:tracking-tight hx:text-slate-900 hx:dark:text-slate-100">{{ .Title }}</h1>{{ end }}
<div class="content">
{{- with (index .Site.Data .Site.Language.Lang "termbase") -}}
<dl>
{{- range sort . "term" -}}
<dt>
{{- .term }}{{ with .abbr }} ({{ . -}}){{ end -}}
</dt>
<dd>
{{- .definition -}}
</dd>
{{- end -}}
</dl>
{{- end -}}
</div>
</main>
</article>
</div>
{{ end }}