From 2e48ec392b1df321f7854edc509eb18b78142f27 Mon Sep 17 00:00:00 2001 From: Nishant Srivastava Date: Fri, 14 Aug 2026 11:56:19 +0200 Subject: [PATCH 1/3] feat: add talks and series page types via archives layout Generalize the archives layout into a grouped index that powers archives, talks, and series pages. Add a series taxonomy dropdown to the navbar and series links to the breadcrumb. --- docs/content/archives/_index.fa.md | 2 + docs/content/archives/_index.ja.md | 2 + docs/content/archives/_index.md | 2 + docs/content/archives/_index.zh-cn.md | 2 + docs/content/blog/demo-series-part-1.md | 16 ++++++++ docs/content/blog/demo-series-part-2.md | 16 ++++++++ docs/content/blog/hextra-tips-dark-mode.md | 16 ++++++++ docs/content/blog/hextra-tips-shortcodes.md | 16 ++++++++ docs/content/series/demo-series/_index.fa.md | 5 +++ docs/content/series/demo-series/_index.ja.md | 5 +++ docs/content/series/demo-series/_index.md | 5 +++ .../series/demo-series/_index.zh-cn.md | 5 +++ docs/content/series/hextra-tips/_index.fa.md | 5 +++ docs/content/series/hextra-tips/_index.ja.md | 5 +++ docs/content/series/hextra-tips/_index.md | 5 +++ .../series/hextra-tips/_index.zh-cn.md | 5 +++ .../talks/2024-open-source-communities.md | 18 ++++++++ docs/content/talks/2025-css-architecture.md | 18 ++++++++ docs/content/talks/2025-hugo-theming.md | 18 ++++++++ docs/content/talks/_index.fa.md | 5 +++ docs/content/talks/_index.ja.md | 5 +++ docs/content/talks/_index.md | 5 +++ docs/content/talks/_index.zh-cn.md | 5 +++ docs/hugo.yaml | 17 +++++++- layouts/_partials/breadcrumb.html | 6 +++ .../_partials/components/archive-item.html | 13 ++++++ .../_partials/components/grouped-list.html | 29 +++++++++++++ layouts/_partials/navbar-series.html | 41 +++++++++++++++++++ layouts/_partials/navbar.html | 2 + layouts/archives.html | 38 +++++------------ layouts/single.html | 2 +- 31 files changed, 304 insertions(+), 30 deletions(-) create mode 100644 docs/content/blog/demo-series-part-1.md create mode 100644 docs/content/blog/demo-series-part-2.md create mode 100644 docs/content/blog/hextra-tips-dark-mode.md create mode 100644 docs/content/blog/hextra-tips-shortcodes.md create mode 100644 docs/content/series/demo-series/_index.fa.md create mode 100644 docs/content/series/demo-series/_index.ja.md create mode 100644 docs/content/series/demo-series/_index.md create mode 100644 docs/content/series/demo-series/_index.zh-cn.md create mode 100644 docs/content/series/hextra-tips/_index.fa.md create mode 100644 docs/content/series/hextra-tips/_index.ja.md create mode 100644 docs/content/series/hextra-tips/_index.md create mode 100644 docs/content/series/hextra-tips/_index.zh-cn.md create mode 100644 docs/content/talks/2024-open-source-communities.md create mode 100644 docs/content/talks/2025-css-architecture.md create mode 100644 docs/content/talks/2025-hugo-theming.md create mode 100644 docs/content/talks/_index.fa.md create mode 100644 docs/content/talks/_index.ja.md create mode 100644 docs/content/talks/_index.md create mode 100644 docs/content/talks/_index.zh-cn.md create mode 100644 layouts/_partials/components/archive-item.html create mode 100644 layouts/_partials/components/grouped-list.html create mode 100644 layouts/_partials/navbar-series.html diff --git a/docs/content/archives/_index.fa.md b/docs/content/archives/_index.fa.md index d7783ddb..d16a7ed9 100644 --- a/docs/content/archives/_index.fa.md +++ b/docs/content/archives/_index.fa.md @@ -2,4 +2,6 @@ title: آرشیو layout: archives toc: false +group: + section: blog --- diff --git a/docs/content/archives/_index.ja.md b/docs/content/archives/_index.ja.md index 79cf02fd..7ead6977 100644 --- a/docs/content/archives/_index.ja.md +++ b/docs/content/archives/_index.ja.md @@ -2,4 +2,6 @@ title: アーカイブ layout: archives toc: false +group: + section: blog --- diff --git a/docs/content/archives/_index.md b/docs/content/archives/_index.md index 8326a222..83a55056 100644 --- a/docs/content/archives/_index.md +++ b/docs/content/archives/_index.md @@ -2,4 +2,6 @@ title: Archives layout: archives toc: false +group: + section: blog --- diff --git a/docs/content/archives/_index.zh-cn.md b/docs/content/archives/_index.zh-cn.md index ae444c24..3fee15c4 100644 --- a/docs/content/archives/_index.zh-cn.md +++ b/docs/content/archives/_index.zh-cn.md @@ -2,4 +2,6 @@ title: 归档 layout: archives toc: false +group: + section: blog --- diff --git a/docs/content/blog/demo-series-part-1.md b/docs/content/blog/demo-series-part-1.md new file mode 100644 index 00000000..dceb6087 --- /dev/null +++ b/docs/content/blog/demo-series-part-1.md @@ -0,0 +1,16 @@ +--- +title: Demo Series Part 1 - Getting Started +date: 2024-09-12 +series: + - demo-series +excludeSearch: true +--- + +This is the first post of the demo series. Tagging a post with a +`series` taxonomy term groups it with the other posts in the series. + + + +## Content + +Learn the fundamentals before moving on to Part 2. diff --git a/docs/content/blog/demo-series-part-2.md b/docs/content/blog/demo-series-part-2.md new file mode 100644 index 00000000..d5b58e2b --- /dev/null +++ b/docs/content/blog/demo-series-part-2.md @@ -0,0 +1,16 @@ +--- +title: Demo Series Part 2 - Advanced Topics +date: 2025-04-22 +series: + - demo-series +excludeSearch: true +--- + +This is the second post of the demo series. All posts sharing the same +`series` taxonomy term appear on the series page. + + + +## Content + +Now that you understand the fundamentals, explore the advanced topics. diff --git a/docs/content/blog/hextra-tips-dark-mode.md b/docs/content/blog/hextra-tips-dark-mode.md new file mode 100644 index 00000000..4da67246 --- /dev/null +++ b/docs/content/blog/hextra-tips-dark-mode.md @@ -0,0 +1,16 @@ +--- +title: "Hextra Tips: Dark Mode Setup" +date: 2023-05-10 +series: + - hextra-tips +excludeSearch: true +--- + +This is a sample post in the second demo series. It shows that more than +one series can exist, each listed in the Series dropdown. + + + +## Content + +Learn how to configure dark mode in Hextra. diff --git a/docs/content/blog/hextra-tips-shortcodes.md b/docs/content/blog/hextra-tips-shortcodes.md new file mode 100644 index 00000000..d00cb1c4 --- /dev/null +++ b/docs/content/blog/hextra-tips-shortcodes.md @@ -0,0 +1,16 @@ +--- +title: "Hextra Tips: Using Shortcodes" +date: 2023-08-20 +series: + - hextra-tips +excludeSearch: true +--- + +This is a sample post in the second demo series. It shows that more than +one series can exist, each listed in the Series dropdown. + + + +## Content + +Explore the shortcodes that ship with Hextra. diff --git a/docs/content/series/demo-series/_index.fa.md b/docs/content/series/demo-series/_index.fa.md new file mode 100644 index 00000000..106ae7c1 --- /dev/null +++ b/docs/content/series/demo-series/_index.fa.md @@ -0,0 +1,5 @@ +--- +title: مجموعهٔ نمایشی +layout: archives +toc: false +--- diff --git a/docs/content/series/demo-series/_index.ja.md b/docs/content/series/demo-series/_index.ja.md new file mode 100644 index 00000000..64118717 --- /dev/null +++ b/docs/content/series/demo-series/_index.ja.md @@ -0,0 +1,5 @@ +--- +title: デモシリーズ +layout: archives +toc: false +--- diff --git a/docs/content/series/demo-series/_index.md b/docs/content/series/demo-series/_index.md new file mode 100644 index 00000000..97c37119 --- /dev/null +++ b/docs/content/series/demo-series/_index.md @@ -0,0 +1,5 @@ +--- +title: Demo Series +layout: archives +toc: false +--- diff --git a/docs/content/series/demo-series/_index.zh-cn.md b/docs/content/series/demo-series/_index.zh-cn.md new file mode 100644 index 00000000..b0e6e974 --- /dev/null +++ b/docs/content/series/demo-series/_index.zh-cn.md @@ -0,0 +1,5 @@ +--- +title: 示例系列 +layout: archives +toc: false +--- diff --git a/docs/content/series/hextra-tips/_index.fa.md b/docs/content/series/hextra-tips/_index.fa.md new file mode 100644 index 00000000..33f82424 --- /dev/null +++ b/docs/content/series/hextra-tips/_index.fa.md @@ -0,0 +1,5 @@ +--- +title: نکته‌های هگزترا +layout: archives +toc: false +--- diff --git a/docs/content/series/hextra-tips/_index.ja.md b/docs/content/series/hextra-tips/_index.ja.md new file mode 100644 index 00000000..7591f27e --- /dev/null +++ b/docs/content/series/hextra-tips/_index.ja.md @@ -0,0 +1,5 @@ +--- +title: Hextra ヒント +layout: archives +toc: false +--- diff --git a/docs/content/series/hextra-tips/_index.md b/docs/content/series/hextra-tips/_index.md new file mode 100644 index 00000000..53109859 --- /dev/null +++ b/docs/content/series/hextra-tips/_index.md @@ -0,0 +1,5 @@ +--- +title: Hextra Tips +layout: archives +toc: false +--- diff --git a/docs/content/series/hextra-tips/_index.zh-cn.md b/docs/content/series/hextra-tips/_index.zh-cn.md new file mode 100644 index 00000000..d30538c5 --- /dev/null +++ b/docs/content/series/hextra-tips/_index.zh-cn.md @@ -0,0 +1,5 @@ +--- +title: Hextra 提示 +layout: archives +toc: false +--- diff --git a/docs/content/talks/2024-open-source-communities.md b/docs/content/talks/2024-open-source-communities.md new file mode 100644 index 00000000..d33af44d --- /dev/null +++ b/docs/content/talks/2024-open-source-communities.md @@ -0,0 +1,18 @@ +--- +title: Building Sustainable Open Source Communities +date: 2024-06-15 +tags: + - Open Source + - Community +excludeSearch: true +--- + +This is a sample talk post. It demonstrates how a section can be +rendered as a year-grouped archive timeline. + + + +## Abstract + +What makes an open source community thrive? This talk covers the +practices that help maintainers grow a healthy contributor base. diff --git a/docs/content/talks/2025-css-architecture.md b/docs/content/talks/2025-css-architecture.md new file mode 100644 index 00000000..5efa1e24 --- /dev/null +++ b/docs/content/talks/2025-css-architecture.md @@ -0,0 +1,18 @@ +--- +title: CSS Architecture for Large Design Systems +date: 2025-02-10 +tags: + - CSS + - Design Systems +excludeSearch: true +--- + +This is a sample talk post. It demonstrates how a section can be +rendered as a year-grouped archive timeline. + + + +## Abstract + +A deep dive into scalable CSS architectures and how utility-first +approaches keep large design systems maintainable. diff --git a/docs/content/talks/2025-hugo-theming.md b/docs/content/talks/2025-hugo-theming.md new file mode 100644 index 00000000..c3e2a5b2 --- /dev/null +++ b/docs/content/talks/2025-hugo-theming.md @@ -0,0 +1,18 @@ +--- +title: Theming Hugo Sites with Tailwind CSS +date: 2025-11-03 +tags: + - Hugo + - Tailwind CSS +excludeSearch: true +--- + +This is a sample talk post. It demonstrates how a section can be +rendered as a year-grouped archive timeline. + + + +## Abstract + +How to build a modern Hugo theme with Tailwind CSS, including asset +pipeline setup and customization points. diff --git a/docs/content/talks/_index.fa.md b/docs/content/talks/_index.fa.md new file mode 100644 index 00000000..bc9fb6a0 --- /dev/null +++ b/docs/content/talks/_index.fa.md @@ -0,0 +1,5 @@ +--- +title: گفتگوها +layout: archives +toc: false +--- diff --git a/docs/content/talks/_index.ja.md b/docs/content/talks/_index.ja.md new file mode 100644 index 00000000..d2d8681e --- /dev/null +++ b/docs/content/talks/_index.ja.md @@ -0,0 +1,5 @@ +--- +title: トーク +layout: archives +toc: false +--- diff --git a/docs/content/talks/_index.md b/docs/content/talks/_index.md new file mode 100644 index 00000000..72bb4c21 --- /dev/null +++ b/docs/content/talks/_index.md @@ -0,0 +1,5 @@ +--- +title: Talks +layout: archives +toc: false +--- diff --git a/docs/content/talks/_index.zh-cn.md b/docs/content/talks/_index.zh-cn.md new file mode 100644 index 00000000..e58ccbda --- /dev/null +++ b/docs/content/talks/_index.zh-cn.md @@ -0,0 +1,5 @@ +--- +title: 演讲 +layout: archives +toc: false +--- diff --git a/docs/hugo.yaml b/docs/hugo.yaml index 841337e2..d868f2a2 100644 --- a/docs/hugo.yaml +++ b/docs/hugo.yaml @@ -17,6 +17,11 @@ outputs: page: [html, markdown] section: [html, rss, markdown] +taxonomies: + tag: tags + category: categories + series: series + defaultContentLanguage: en languages: en: @@ -110,6 +115,11 @@ menu: - identifier: more name: More weight: 4 + - identifier: series + name: Series + weight: 4.5 + params: + type: series - identifier: showcase name: Showcase pageRef: /showcase @@ -156,6 +166,11 @@ menu: pageRef: /glossary parent: more weight: 3 + - identifier: talks + name: Talks + pageRef: /talks + parent: more + weight: 4 sidebar: - identifier: more @@ -241,8 +256,6 @@ params: displayPagination: true archives: - # Source section used for the archives page. - section: blog # Date format for archive list items. dateFormat: "Jan 02" diff --git a/layouts/_partials/breadcrumb.html b/layouts/_partials/breadcrumb.html index 1f4612e8..40ea27ec 100644 --- a/layouts/_partials/breadcrumb.html +++ b/layouts/_partials/breadcrumb.html @@ -10,6 +10,12 @@ {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx:w-3.5 hx:shrink-0 hx:rtl:-rotate-180\"") -}} {{ end -}} {{ end -}} + {{- range $page.GetTerms "series" }} +
+ {{- partial "utils/title" . -}} +
+ {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx:w-3.5 hx:shrink-0 hx:rtl:-rotate-180\"") -}} + {{ end -}}
{{- partial "utils/title" $page -}}
diff --git a/layouts/_partials/components/archive-item.html b/layouts/_partials/components/archive-item.html new file mode 100644 index 00000000..85c2378f --- /dev/null +++ b/layouts/_partials/components/archive-item.html @@ -0,0 +1,13 @@ +{{- $page := .page -}} +{{- $dateFormat := .dateFormat | default "Jan 02" -}} +
+ +
+ + {{ $page.Title }} + + {{- with $page.Params.tags }} + {{ partial "tags.html" (dict "context" $page) }} + {{- end }} +
+
diff --git a/layouts/_partials/components/grouped-list.html b/layouts/_partials/components/grouped-list.html new file mode 100644 index 00000000..c3fcd5a6 --- /dev/null +++ b/layouts/_partials/components/grouped-list.html @@ -0,0 +1,29 @@ +{{- $pages := .pages | default slice -}} +{{- $groupBy := .groupBy | default "year" -}} +{{- $dateFormat := .dateFormat | default "Jan 02" -}} + +{{- if eq $groupBy "year" }} + {{- range $pages.GroupByDate "2006" "desc" }} +

{{ .Key }}

+
+ {{- range .Pages }} + {{ partial "components/archive-item.html" (dict "page" . "dateFormat" $dateFormat) }} + {{- end }} +
+ {{- end }} +{{- else if eq $groupBy "month" }} + {{- range $pages.GroupByDate "2006-01" "desc" }} +

{{ .Key }}

+
+ {{- range .Pages }} + {{ partial "components/archive-item.html" (dict "page" . "dateFormat" $dateFormat) }} + {{- end }} +
+ {{- end }} +{{- else }} +
+ {{- range $pages }} + {{ partial "components/archive-item.html" (dict "page" . "dateFormat" $dateFormat) }} + {{- end }} +
+{{- end -}} diff --git a/layouts/_partials/navbar-series.html b/layouts/_partials/navbar-series.html new file mode 100644 index 00000000..6c79a2c6 --- /dev/null +++ b/layouts/_partials/navbar-series.html @@ -0,0 +1,41 @@ +{{- $item := .item -}} +{{- $currentPage := .currentPage -}} +{{- $active := and (eq $currentPage.Kind "term") (eq $currentPage.Data.Singular "series") -}} +{{- $activeClass := cond $active "hx:font-medium" "hx:text-gray-600 hx:hover:text-gray-800 hx:dark:text-gray-400 hx:dark:hover:text-gray-200" -}} +{{- if site.Taxonomies.series }} +
+ + +
+{{- end -}} diff --git a/layouts/_partials/navbar.html b/layouts/_partials/navbar.html index d64e430b..cf4ee61e 100644 --- a/layouts/_partials/navbar.html +++ b/layouts/_partials/navbar.html @@ -37,6 +37,8 @@ {{- partial "theme-toggle.html" (dict "iconHeight" $iconHeight "hideLabel" (not .Params.label) "iconHeight" $iconHeight "location" "top" "class" "hx:p-1 hx:md:p-2") -}} {{- else if eq .Params.type "language-switch" -}} {{- partial "language-switch" (dict "context" $page "grow" false "hideLabel" (not .Params.label) "iconName" (.Params.icon | default "translate") "iconHeight" $iconHeight "location" "top" "class" "hx:p-1 hx:md:p-2") -}} + {{- else if eq .Params.type "series" -}} + {{- partial "navbar-series.html" (dict "item" . "currentPage" $currentPage) -}} {{- else if .Params.icon -}} {{- /* Display icon menu item */ -}} {{- if not $link -}}{{ warnf "Icon menu item '%s' has no URL" .Name }}{{- end -}} diff --git a/layouts/archives.html b/layouts/archives.html index f4740671..366ed9b7 100644 --- a/layouts/archives.html +++ b/layouts/archives.html @@ -1,8 +1,13 @@ {{ define "main" }} - {{- $section := site.Params.archives.section | default "blog" -}} - {{- $dateFormat := site.Params.archives.dateFormat | default "Jan 02" -}} - {{- $pages := where site.RegularPages "Section" $section -}} - {{- $groups := $pages.GroupByDate "2006" "desc" -}} + {{- $groupBy := .Params.group.groupBy | default (cond (eq .Kind "term") "none" "year") -}} + {{- $dateFormat := .Params.group.dateFormat | default site.Params.archives.dateFormat | default "Jan 02" -}} + {{- $pages := slice -}} + {{- if eq .Kind "term" }} + {{- $pages = .Pages -}} + {{- else }} + {{- $section := .Params.group.section | default (.Params.archives.section | default (site.Params.archives.section | default (.Section | default "blog"))) -}} + {{- $pages = where site.RegularPages "Section" $section -}} + {{- end -}}
{{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" true) }} {{ partial "toc.html" (dict "Params" (dict "toc" false)) }} @@ -13,29 +18,8 @@ {{ if .Title }}

{{ .Title }}

{{ end }}
{{ partial "custom/content-begin.html" . }} - {{- if $groups }} - {{- range $groups }} -

{{ .Key }}

-
- {{- range .Pages }} - {{- $page := . -}} -
- -
- - {{ .Title }} - - {{- with .Params.tags }} - {{ partial "tags.html" (dict "context" $page) }} - {{- end }} -
-
- {{- end }} -
- {{- end }} + {{- if $pages }} + {{ partial "components/grouped-list.html" (dict "pages" $pages "groupBy" $groupBy "dateFormat" $dateFormat) }} {{- else }}

{{ (T "noResultsFound") | default "No posts found." }}

{{- end }} diff --git a/layouts/single.html b/layouts/single.html index eac3472b..e27afad1 100644 --- a/layouts/single.html +++ b/layouts/single.html @@ -5,7 +5,7 @@
{{ partial "custom/page-begin.html" . }} - {{ partial "breadcrumb.html" (dict "page" . "enable" false) }} + {{ partial "breadcrumb.html" (dict "page" . "enable" (ne .CurrentSection .Site.Home)) }}
{{ if .Title }}

{{ .Title }}

{{ end }}
From 28f8cfbe2a86da146f6613dab474bec9cc004c57 Mon Sep 17 00:00:00 2001 From: Nishant Srivastava Date: Fri, 14 Aug 2026 11:56:22 +0200 Subject: [PATCH 2/3] docs: document talks and series pages Explain the generalized archives layout, group options, and how to set up talks archives and series taxonomies. --- .../docs/advanced/additional-pages.fa.md | 161 +++++++++++++++--- .../docs/advanced/additional-pages.ja.md | 161 +++++++++++++++--- .../content/docs/advanced/additional-pages.md | 161 +++++++++++++++--- .../docs/advanced/additional-pages.zh-cn.md | 161 +++++++++++++++--- 4 files changed, 556 insertions(+), 88 deletions(-) diff --git a/docs/content/docs/advanced/additional-pages.fa.md b/docs/content/docs/advanced/additional-pages.fa.md index ce40e4f0..3df92b33 100644 --- a/docs/content/docs/advanced/additional-pages.fa.md +++ b/docs/content/docs/advanced/additional-pages.fa.md @@ -6,7 +6,7 @@ aliases: - /docs/advanced/glossary/ --- -Hextra چند صفحهٔ اضافی دارد که باید به‌صورت جداگانه فعال شوند: واژه‌نامه و آرشیو. +Hextra چند صفحهٔ اضافی دارد که باید به‌صورت جداگانه فعال شوند: واژه‌نامه، آرشیو، گفتگوها و مجموعه. @@ -65,41 +65,158 @@ layout: glossary ## آرشیو -می‌توانید برای نوشته‌های یک بخش، یک صفحه آرشیو زمانی (گروه‌بندی‌شده بر اساس سال) بسازید. +چیدمان `archives` یک فهرست گروه‌بندی‌شدهٔ عمومی است: هر مجموعه‌ای از صفحه‌ها را به‌صورت یک خط زمانی گروه‌بندی‌شده بر اساس سال (یا فهرست ساده) نمایش می‌دهد و به‌صورت پیش‌فرض، بخشی که صفحه به آن تعلق دارد را آرشیو می‌کند. این چیدمان علاوه بر صفحه آرشیو داخلی، انواع صفحهٔ [گفتگوها](#گفتگوها) و [مجموعه](#مجموعه) را که در ادامه توضیح داده شده‌اند، امکان‌پذیر می‌کند. -1. صفحه آرشیو را ایجاد کنید: - ```yaml {filename="content/archives/_index.md"} +برای ساخت یک صفحه آرشیو مستقل که به بخش دیگری اشاره می‌کند (مثلاً صفحه `/archives` برای فهرست نوشته‌های وبلاگ)، `group.section` را در front matter صفحه تنظیم کنید: + +```yaml {filename="content/archives/_index.md"} +--- +title: Archives +layout: archives +toc: false +group: + section: blog +--- +``` + +ساختار نمونهٔ داخلی همین است: صفحه در `content/archives/` قرار دارد اما بخش `blog` را آرشیو می‌کند. یک صفحهٔ نمونه از آرشیو در [آرشیو]({{% relref "/archives" %}}) در دسترس است. + +### گزینه‌ها + +- `group.section`: بخش مورد نظر برای آرشیو. مقدار پیش‌فرض، بخش خود صفحه است و به `params.archives.section` (پیش‌فرض `blog`) برمی‌گردد. +- `group.dateFormat`: قالب نمایش تاریخ آیتم‌های فهرست. مقدار پیش‌فرض `Jan 02` است و به `params.archives.dateFormat` برمی‌گردد. +- `group.groupBy`: `year` (پیش‌فرض)، `month`، یا `none` برای فهرست ساده. صفحه‌های ترم (مانند مجموعه) از آنجا که با ترم گروه‌بندی شده‌اند، به‌صورت پیش‌فرض `none` هستند. + +پیام حالت خالی از کلید ترجمه `noResultsFound` استفاده می‌کند. + +## گفتگوها + +یک بخش محتوایی مانند `talks` را می‌توان مانند صفحه آرشیو به‌صورت فهرست جدا بر اساس سال نمایش داد. + +1. صفحهٔ فهرست بخش را با چیدمان `archives` ایجاد کنید: + ```yaml {filename="content/talks/_index.md"} --- - title: Archives + title: Talks layout: archives toc: false --- ``` + این صفحه به‌صورت پیش‌فرض بخش خودش را آرشیو می‌کند، بنابراین `/talks/` همهٔ گفتگوها را گروه‌بندی‌شده بر اساس سال نمایش می‌دهد. هیچ پیکربندی دیگری لازم نیست. 2. (اختیاری) آن را به منوی بالا اضافه کنید: ```yaml {filename="hugo.yaml"} menu: main: - - identifier: archives - name: Archives - pageRef: /archives + - identifier: talks + name: Talks + pageRef: /talks ``` -3. (اختیاری، چندزبانه) فایل‌های آرشیو ترجمه‌شده با همان layout اضافه کنید، برای مثال: - - `content/archives/_index.fa.md` - - `content/archives/_index.ja.md` - - `content/archives/_index.zh-cn.md` -4. (اختیاری) بخش مورد استفاده برای آرشیو را تغییر دهید. مقدار پیش‌فرض `blog` است. +3. (اختیاری، چندزبانه) صفحه‌های فهرست ترجمه‌شده با همان layout اضافه کنید، برای مثال `content/talks/_index.ja.md`. + +ساختار فایل برای آرشیو گفتگوها به این شکل است: + +{{< filetree/container >}} + {{< filetree/folder name="content" state="open" >}} + {{< filetree/folder name="talks" state="open" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/folder name="open-source-communities" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="slides.pdf" >}} + {{< /filetree/folder >}} + {{< filetree/file name="css-architecture.md" >}} + {{< filetree/folder name="hugo-theming" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="cover.png" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +هر گفتگو می‌تواند یک فایل Markdown ساده (`css-architecture.md`) یا یک پوشهٔ page bundle باشد: یک `index.md` به‌همراه تصاویر و دارایی‌هایش (مانند اسلایدها یا تصویر کاور) در همان زیرپوشه (`open-source-communities/`، `hugo-theming/`) گروه‌بندی می‌شود. فقط `_index.md` دارای front matter چیدمان `archives` است: + +```yaml {filename="content/talks/hugo-theming/index.md"} +--- +title: Theming Hugo Sites with Tailwind CSS +date: 2025-11-03 +tags: + - Hugo + - Tailwind CSS +--- +``` + +یک صفحهٔ نمونه از آرشیو گفتگوها در [گفتگوها]({{% relref "/talks" %}}) در دسترس است. + +## مجموعه + +مجموعه (series) نوشته‌های مرتبط (معمولاً نوشته‌های وبلاگ) را زیر یک نام گروه‌بندی می‌کند. مجموعه یک برچسب تاکسونومی است: همهٔ نوشته‌های دارای برچسب `series` یکسان در صفحهٔ خودکار `/series/<نام>/` گروه‌بندی می‌شوند. نام مجموعه همان گروه است، بنابراین صفحه نوشته‌ها را بدون گروه‌بندی اضافه در کنار هم فهرست می‌کند. + +1. تاکسونومی `series` را پیکربندی کنید: ```yaml {filename="hugo.yaml"} - params: - archives: - section: blog + taxonomies: + series: series ``` -5. (اختیاری) قالب نمایش تاریخ آیتم‌های آرشیو را تغییر دهید. مقدار پیش‌فرض `Jan 02` است. + تنظیم `taxonomies` تاکسونومی‌های پیش‌فرض هوگو را جایگزین می‌کند. برای حفظ تاکسونومی‌های موجود، آن‌ها را نیز فهرست کنید: ```yaml {filename="hugo.yaml"} - params: - archives: - dateFormat: "Jan 02" + taxonomies: + tag: tags + category: categories + series: series + ``` +2. در front matter هر نوشته‌ای که به مجموعه تعلق دارد، برچسب را اضافه کنید: + ```yaml {filename="content/blog/part-1/index.md"} + --- + title: "Demo Series Part 1" + date: 2024-09-12 + series: + - demo-series + --- + ``` + با فهرست کردن چند برچسب، یک نوشته می‌تواند به بیش از یک مجموعه تعلق داشته باشد. front matter `series` همچنین پیوندهای Open Graph `og:see_also` را در صفحه نوشته تولید می‌کند. +3. (اختیاری) یک صفحه فهرست ترم بسازید تا عنوان مجموعه را تنظیم کنید و چیدمان `archives` را فعال کنید: + ```yaml {filename="content/series/demo-series/_index.md"} + --- + title: Demo Series + layout: archives + toc: false + --- ``` + بدون این صفحه، `/series/demo-series/` همچنان همهٔ نوشته‌های مجموعه را فهرست می‌کند. -پیام حالت خالی از کلید ترجمه `noResultsFound` استفاده می‌کند. +ساختار فایل برای یک مجموعه به این شکل است: + +{{< filetree/container >}} + {{< filetree/folder name="content" state="open" >}} + {{< filetree/folder name="blog" state="open" >}} + {{< filetree/folder name="part-1" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="diagram.png" >}} + {{< /filetree/folder >}} + {{< filetree/file name="part-2.md" >}} + {{< /filetree/folder >}} + {{< filetree/folder name="series" state="open" >}} + {{< filetree/folder name="demo-series" state="open" >}} + {{< filetree/file name="_index.md" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +نوشته‌های مجموعه در بخش عادی خود (در این مثال `blog`) باقی می‌مانند. دایرکتوری `content/series/` محل قرارگیری نوشته‌ها نیست — دایرکتوری محتوای تاکسونومی هوگو است و فقط برای سفارشی‌کردن صفحهٔ ترم خودکار `/series/<نام>/` استفاده می‌شود (عنوان، چیدمان `archives`). این دایرکتوری اختیاری است: بدون آن نیز `/series/<نام>/` تولید می‌شود و نوشته‌های مجموعه را زیر نام مجموعه فهرست می‌کند. + +مانند نوشته‌های گفتگو، یک نوشتهٔ مجموعه نیز می‌تواند یک فایل Markdown ساده یا یک پوشهٔ page bundle (مثلاً `part-1/`) باشد که نوشته را به‌همراه تصاویر و دارایی‌هایش گروه‌بندی می‌کند. + +### افزودن منوی کشویی مجموعه به منو + +برای افزودن یک منوی کشویی که همهٔ مجموعه‌ها را در ناوبری بالا فهرست می‌کند، یک آیتم منو با `type: series` اضافه کنید: + +```yaml {filename="hugo.yaml"} +menu: + main: + - identifier: series + name: Series + params: + type: series +``` + +منوی کشویی به‌صورت خودکار همهٔ برچسب‌های مجموعه را فهرست می‌کند. برای سفارشی‌کردن برچسب نمایشی یک مجموعه، عنوان را در صفحهٔ فهرست ترم (`content/series/<نام>/_index.md`) تنظیم کنید. -یک صفحهٔ نمونه از آرشیو در [آرشیو]({{% relref "/archives" %}}) در دسترس است. +یک صفحهٔ نمونه از آرشیو مجموعه در [مجموعهٔ نمایشی]({{% relref "/series/demo-series" %}}) در دسترس است. diff --git a/docs/content/docs/advanced/additional-pages.ja.md b/docs/content/docs/advanced/additional-pages.ja.md index d30c468c..fbb104db 100644 --- a/docs/content/docs/advanced/additional-pages.ja.md +++ b/docs/content/docs/advanced/additional-pages.ja.md @@ -6,7 +6,7 @@ aliases: - /docs/advanced/glossary/ --- -Hextra には明示的に有効化する追加ページがあります。用語集とアーカイブです。 +Hextra には明示的に有効化する追加ページがあります。用語集、アーカイブ、トーク、シリーズです。 @@ -65,41 +65,158 @@ layout: glossary ## アーカイブ -投稿を年ごとにまとめたアーカイブタイムラインページを作成できます。 +`archives` レイアウトは汎用のグループ化インデックスです。任意のページ集合を年ごとにグループ化したタイムライン（またはフラットリスト）として表示し、デフォルトではページが属するセクションをアーカイブします。組み込みのアーカイブページのほか、後述の[トーク](#トーク)や[シリーズ](#シリーズ)などのページ種別を実現します。 -1. アーカイブページを作成します： - ```yaml {filename="content/archives/_index.md"} +別のセクションを指す独立したアーカイブページを作成するには（たとえばブログ投稿を一覧する `/archives` ページ）、ページの front matter で `group.section` を設定します： + +```yaml {filename="content/archives/_index.md"} +--- +title: Archives +layout: archives +toc: false +group: + section: blog +--- +``` + +これが組み込みのサンプルの仕組みです。ページは `content/archives/` にありますが、`blog` セクションをアーカイブします。アーカイブのサンプルページは [アーカイブ]({{% relref "/archives" %}}) で確認できます。 + +### オプション + +- `group.section`: アーカイブ対象のセクション。デフォルトはページ自身のセクションで、`params.archives.section`（デフォルト `blog`）にフォールバックします。 +- `group.dateFormat`: リスト項目の日付表示形式。デフォルトは `Jan 02` で、`params.archives.dateFormat` にフォールバックします。 +- `group.groupBy`: `year`（デフォルト）、`month`、またはフラットリストの `none`。タームページ（シリーズなど）はすでにタームでグループ化されているため、デフォルトは `none` です。 + +空状態メッセージは i18n キー `noResultsFound` を使用します。 + +## トーク + +`talks` のようなコンテンツセクションを、アーカイブページと同じ年ごとのインデックスとして一覧できます。 + +1. セクションのインデックスページを `archives` レイアウトで作成します： + ```yaml {filename="content/talks/_index.md"} --- - title: Archives + title: Talks layout: archives toc: false --- ``` + このページはデフォルトで自分のセクションをアーカイブするため、`/talks/` にはすべてのトークが年ごとにグループ化されて表示されます。追加の設定は不要です。 2. （任意）トップメニューに追加します： ```yaml {filename="hugo.yaml"} menu: main: - - identifier: archives - name: Archives - pageRef: /archives + - identifier: talks + name: Talks + pageRef: /talks ``` -3. （任意・多言語）同じ layout を使った翻訳版アーカイブページを追加します。例： - - `content/archives/_index.fa.md` - - `content/archives/_index.ja.md` - - `content/archives/_index.zh-cn.md` -4. （任意）アーカイブ対象のセクションを変更します。デフォルトは `blog` です。 +3. （任意・多言語）同じ layout を使った翻訳版インデックスページを追加します。例：`content/talks/_index.ja.md`。 + +トークアーカイブのファイル構成は次のようになります： + +{{< filetree/container >}} + {{< filetree/folder name="content" state="open" >}} + {{< filetree/folder name="talks" state="open" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/folder name="open-source-communities" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="slides.pdf" >}} + {{< /filetree/folder >}} + {{< filetree/file name="css-architecture.md" >}} + {{< filetree/folder name="hugo-theming" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="cover.png" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +各トーク投稿は、単一の Markdown ファイル（`css-architecture.md`）またはページバンドルディレクトリにできます。ページバンドルでは、`index.md` をその画像やアセット（スライドやカバー画像など）と同じサブディレクトリ（`open-source-communities/`、`hugo-theming/`）にまとめます。`layout: archives` の front matter を持つのは `_index.md` だけです： + +```yaml {filename="content/talks/hugo-theming/index.md"} +--- +title: Theming Hugo Sites with Tailwind CSS +date: 2025-11-03 +tags: + - Hugo + - Tailwind CSS +--- +``` + +トークアーカイブのサンプルページは [トーク]({{% relref "/talks" %}}) で確認できます。 + +## シリーズ + +シリーズは、関連する投稿（通常はブログ投稿）を名前でグループ化するものです。シリーズはタクソノミー用語であり、同じ `series` 用語を持つすべての投稿は、自動生成される `/series/<名前>/` ページにグループ化されます。シリーズ名がグループなので、ページには投稿が追加のグループ化なしにまとめて一覧表示されます。 + +1. `series` タクソノミーを設定します： ```yaml {filename="hugo.yaml"} - params: - archives: - section: blog + taxonomies: + series: series ``` -5. （任意）アーカイブ項目の日付表示形式を変更します。デフォルトは `Jan 02` です。 + `taxonomies` を設定すると Hugo のデフォルトが置き換わります。既存のタクソノミーを維持するには、それらも列挙します： ```yaml {filename="hugo.yaml"} - params: - archives: - dateFormat: "Jan 02" + taxonomies: + tag: tags + category: categories + series: series + ``` +2. シリーズに属する各投稿の front matter に用語を付けます： + ```yaml {filename="content/blog/part-1/index.md"} + --- + title: "Demo Series Part 1" + date: 2024-09-12 + series: + - demo-series + --- + ``` + 複数の用語を並べることで、投稿を複数のシリーズに含めることができます。`series` front matter は投稿ページの Open Graph `og:see_also` リンクも生成します。 +3. （任意）シリーズのタイトルを設定し `archives` レイアウトを有効にするタームインデックスページを作成します： + ```yaml {filename="content/series/demo-series/_index.md"} + --- + title: Demo Series + layout: archives + toc: false + --- ``` + このページがなくても、`/series/demo-series/` にはシリーズのすべての投稿が一覧表示されます。 -空状態メッセージは i18n キー `noResultsFound` を使用します。 +シリーズのファイル構成は次のようになります： + +{{< filetree/container >}} + {{< filetree/folder name="content" state="open" >}} + {{< filetree/folder name="blog" state="open" >}} + {{< filetree/folder name="part-1" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="diagram.png" >}} + {{< /filetree/folder >}} + {{< filetree/file name="part-2.md" >}} + {{< /filetree/folder >}} + {{< filetree/folder name="series" state="open" >}} + {{< filetree/folder name="demo-series" state="open" >}} + {{< filetree/file name="_index.md" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +シリーズ投稿は通常のセクション（この例では `blog`）に置いたままにします。`content/series/` ディレクトリは投稿の置き場所ではありません。Hugo のタクソノミーコンテンツディレクトリであり、自動生成される `/series/<名前>/` タームページをカスタマイズするためだけに使います（タイトル、`archives` レイアウト）。このディレクトリは任意です。なくても `/series/<名前>/` は生成され、シリーズ投稿がシリーズ名の下に一覧表示されます。 + +トーク投稿と同様に、シリーズ投稿も単一の Markdown ファイルまたはページバンドルディレクトリ（例：`part-1/`）にできます。ページバンドルでは投稿を画像やアセットと一緒にまとめられます。 + +### メニューにシリーズのドロップダウンを追加する + +トップナビゲーションにすべてのシリーズを一覧するドロップダウンを追加するには、`type: series` のメニュー項目を追加します： + +```yaml {filename="hugo.yaml"} +menu: + main: + - identifier: series + name: Series + params: + type: series +``` + +ドロップダウンにはすべてのシリーズ用語が自動的に表示されます。シリーズに表示するラベルを変更するには、タームインデックスページ（`content/series/<名前>/_index.md`）でタイトルを設定します。 -アーカイブのサンプルページは [アーカイブ]({{% relref "/archives" %}}) で確認できます。 +シリーズアーカイブのサンプルページは [デモシリーズ]({{% relref "/series/demo-series" %}}) で確認できます。 diff --git a/docs/content/docs/advanced/additional-pages.md b/docs/content/docs/advanced/additional-pages.md index 55599750..bbe0ada4 100644 --- a/docs/content/docs/advanced/additional-pages.md +++ b/docs/content/docs/advanced/additional-pages.md @@ -6,7 +6,7 @@ aliases: - /docs/advanced/glossary/ --- -Hextra includes additional pages that you can enable explicitly: glossary and archives. +Hextra includes additional pages that you can enable explicitly: glossary, archives, talks, and series. @@ -65,41 +65,158 @@ An example glossary page is available at [Glossary]({{% relref "/glossary" %}}). ## Archives -You can create an archive timeline page (grouped by year) for posts in a section. +The `archives` layout is a general grouped index: it renders any set of pages as a year-grouped timeline (or as a flat list), and by default it archives the section the page belongs to. It powers the built-in archives page as well as the [Talks](#talks) and [Series](#series) page types described below. -1. Create the archive page: - ```yaml {filename="content/archives/_index.md"} +To create a standalone archive page that points at a different section (for example an `/archives` page listing blog posts), set `group.section` in the page front matter: + +```yaml {filename="content/archives/_index.md"} +--- +title: Archives +layout: archives +toc: false +group: + section: blog +--- +``` + +This is how the built-in example works: the page lives in `content/archives/` but archives the `blog` section. An example archive page is available at [Archives]({{% relref "/archives" %}}). + +### Options + +- `group.section`: the section to archive. The default is the page's own section, falling back to `params.archives.section` (default `blog`). +- `group.dateFormat`: date format for list items. The default is `Jan 02`, falling back to `params.archives.dateFormat`. +- `group.groupBy`: `year` (default), `month`, or `none` for a flat list. Term pages (such as a series) default to `none`, since they are already grouped by the term. + +The empty-state message uses the `noResultsFound` i18n key. + +## Talks + +A content section such as `talks` can be listed as a year-separated index, just like the archives page. + +1. Create the section's index page with the `archives` layout: + ```yaml {filename="content/talks/_index.md"} --- - title: Archives + title: Talks layout: archives toc: false --- ``` + The page archives its own section by default, so `/talks/` renders all talks grouped by year. No further configuration is needed. 2. (Optional) Add it to the top menu: ```yaml {filename="hugo.yaml"} menu: main: - - identifier: archives - name: Archives - pageRef: /archives + - identifier: talks + name: Talks + pageRef: /talks ``` -3. (Optional, multilingual) Add translated archive index pages with the same layout, for example: - - `content/archives/_index.fa.md` - - `content/archives/_index.ja.md` - - `content/archives/_index.zh-cn.md` -4. (Optional) Change the content section used for archives. The default is `blog`. +3. (Optional, multilingual) Add translated index pages with the same layout, for example `content/talks/_index.ja.md`. + +The file structure for a talks archive looks like this: + +{{< filetree/container >}} + {{< filetree/folder name="content" state="open" >}} + {{< filetree/folder name="talks" state="open" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/folder name="open-source-communities" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="slides.pdf" >}} + {{< /filetree/folder >}} + {{< filetree/file name="css-architecture.md" >}} + {{< filetree/folder name="hugo-theming" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="cover.png" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +Each talk post can be either a single Markdown file (`css-architecture.md`) or a page bundle directory: an `index.md` with its images and assets (such as slide decks or cover images) grouped in the same subdirectory (`open-source-communities/`, `hugo-theming/`). Only `_index.md` carries the `layout: archives` front matter: + +```yaml {filename="content/talks/hugo-theming/index.md"} +--- +title: Theming Hugo Sites with Tailwind CSS +date: 2025-11-03 +tags: + - Hugo + - Tailwind CSS +--- +``` + +An example talks archive is available at [Talks]({{% relref "/talks" %}}). + +## Series + +A series groups related posts (usually blog posts) under a name. It is a taxonomy term: all posts sharing the same `series` term are grouped on an automatically generated `/series//` page. The series name is the group, so the page lists its posts together without extra grouping. + +1. Configure the `series` taxonomy: ```yaml {filename="hugo.yaml"} - params: - archives: - section: blog + taxonomies: + series: series ``` -5. (Optional) Change the archive item date format. The default is `Jan 02`. + Setting `taxonomies` replaces Hugo's default ones. To keep existing taxonomies, list them as well: ```yaml {filename="hugo.yaml"} - params: - archives: - dateFormat: "Jan 02" + taxonomies: + tag: tags + category: categories + series: series + ``` +2. Tag each post that belongs to the series in its front matter: + ```yaml {filename="content/blog/part-1/index.md"} + --- + title: "Demo Series Part 1" + date: 2024-09-12 + series: + - demo-series + --- + ``` + A post can belong to more than one series by listing several terms. The `series` front matter also drives the Open Graph `og:see_also` links on the post page. +3. (Optional) Create a term index page to set the series title and enable the `archives` layout: + ```yaml {filename="content/series/demo-series/_index.md"} + --- + title: Demo Series + layout: archives + toc: false + --- ``` + Without this page, `/series/demo-series/` still lists all posts in the series. -The empty-state message uses the `noResultsFound` i18n key. +The file structure for a series looks like this: + +{{< filetree/container >}} + {{< filetree/folder name="content" state="open" >}} + {{< filetree/folder name="blog" state="open" >}} + {{< filetree/folder name="part-1" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="diagram.png" >}} + {{< /filetree/folder >}} + {{< filetree/file name="part-2.md" >}} + {{< /filetree/folder >}} + {{< filetree/folder name="series" state="open" >}} + {{< filetree/folder name="demo-series" state="open" >}} + {{< filetree/file name="_index.md" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +The series posts stay in their normal section (`blog` in this example). The `content/series/` directory is not a second home for posts — it is Hugo's taxonomy content directory, used only to customize the automatically generated `/series//` term page (title, `archives` layout). It is optional: without it, `/series//` is still generated and lists the series posts under the series name. + +Like talk posts, a series post can be a single Markdown file or a page bundle directory (for example `part-1/`) that groups the post with its images and assets. + +### Add a Series Dropdown to the Menu + +To add a dropdown that lists all series in the top navigation, add a menu item with `type: series`: + +```yaml {filename="hugo.yaml"} +menu: + main: + - identifier: series + name: Series + params: + type: series +``` + +The dropdown lists every series term automatically. To customize the label shown for a series, set its title on the term index page (`content/series//_index.md`). -An example archive page is available at [Archives]({{% relref "/archives" %}}). +An example series archive is available at [Demo Series]({{% relref "/series/demo-series" %}}). diff --git a/docs/content/docs/advanced/additional-pages.zh-cn.md b/docs/content/docs/advanced/additional-pages.zh-cn.md index e0f1c4b6..f7be33e8 100644 --- a/docs/content/docs/advanced/additional-pages.zh-cn.md +++ b/docs/content/docs/advanced/additional-pages.zh-cn.md @@ -6,7 +6,7 @@ aliases: - /docs/advanced/glossary/ --- -Hextra 提供一些需要单独启用的附加页面：术语表与归档页。 +Hextra 提供一些需要单独启用的附加页面：术语表、归档页、演讲与系列。 @@ -65,41 +65,158 @@ layout: glossary ## 归档页 -你可以为某个内容分区的文章创建按年份分组的归档时间线页面。 +`archives` 布局是一个通用的分组索引：它可以将任意页面集合渲染为按年份分组的时间线（或平面列表），并且默认归档页面自身所属的内容分区。它支撑内置的归档页面，也支撑下面介绍的[演讲](#演讲)和[系列](#系列)两种页面类型。 -1. 创建归档页面： - ```yaml {filename="content/archives/_index.md"} +要创建指向其他分区的独立归档页面（例如列出博客文章的 `/archives` 页面），请在页面 front matter 中设置 `group.section`： + +```yaml {filename="content/archives/_index.md"} +--- +title: Archives +layout: archives +toc: false +group: + section: blog +--- +``` + +内置示例就是如此：页面位于 `content/archives/`，但归档的是 `blog` 分区。示例归档页面可在 [归档]({{% relref "/archives" %}}) 查看。 + +### 选项 + +- `group.section`: 要归档的分区。默认值是页面自身所在的分区，回退到 `params.archives.section`（默认 `blog`）。 +- `group.dateFormat`: 列表项的日期显示格式。默认值是 `Jan 02`，回退到 `params.archives.dateFormat`。 +- `group.groupBy`: `year`（默认）、`month`，或 `none` 以显示平面列表。术语页面（如系列）由于已按术语分组，默认值为 `none`。 + +空状态文案使用 i18n 键 `noResultsFound`。 + +## 演讲 + +内容分区（如 `talks`）可以像归档页面一样，列表为按年份分隔的索引。 + +1. 使用 `archives` 布局创建内容分区的索引页： + ```yaml {filename="content/talks/_index.md"} --- - title: Archives + title: Talks layout: archives toc: false --- ``` + 该页面默认归档其自身所在的分区，因此 `/talks/` 会按年份分组显示所有演讲。无需其他配置。 2. （可选）将其添加到顶部菜单： ```yaml {filename="hugo.yaml"} menu: main: - - identifier: archives - name: Archives - pageRef: /archives + - identifier: talks + name: Talks + pageRef: /talks ``` -3. （可选，多语言）添加使用相同 layout 的多语言归档首页，例如： - - `content/archives/_index.fa.md` - - `content/archives/_index.ja.md` - - `content/archives/_index.zh-cn.md` -4. （可选）修改归档来源分区。默认值为 `blog`。 +3. （可选，多语言）添加使用相同 layout 的多语言索引页，例如 `content/talks/_index.ja.md`。 + +演讲归档的文件结构如下： + +{{< filetree/container >}} + {{< filetree/folder name="content" state="open" >}} + {{< filetree/folder name="talks" state="open" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/folder name="open-source-communities" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="slides.pdf" >}} + {{< /filetree/folder >}} + {{< filetree/file name="css-architecture.md" >}} + {{< filetree/folder name="hugo-theming" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="cover.png" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +每篇演讲可以是一个独立的 Markdown 文件（`css-architecture.md`），也可以是一个页面包目录：一个 `index.md` 与其图片和资源（如幻灯片或封面图）放在同一子目录（`open-source-communities/`、`hugo-theming/`）。只有 `_index.md` 带有 `layout: archives` front matter： + +```yaml {filename="content/talks/hugo-theming/index.md"} +--- +title: Theming Hugo Sites with Tailwind CSS +date: 2025-11-03 +tags: + - Hugo + - Tailwind CSS +--- +``` + +示例演讲归档可在 [演讲]({{% relref "/talks" %}}) 查看。 + +## 系列 + +系列将相关文章（通常是博客文章）按名称分组。系列是一个分类术语：所有带有相同 `series` 术语的文章会自动分组到 `/series/<名称>/` 页面。系列名称即为分组，因此该页面会将这些文章列在一起，不再做额外的分组。 + +1. 配置 `series` 分类： ```yaml {filename="hugo.yaml"} - params: - archives: - section: blog + taxonomies: + series: series ``` -5. （可选）修改归档条目的日期显示格式。默认值是 `Jan 02`。 + 设置 `taxonomies` 会替换 Hugo 的默认分类。要保留现有分类，请一并列出： ```yaml {filename="hugo.yaml"} - params: - archives: - dateFormat: "Jan 02" + taxonomies: + tag: tags + category: categories + series: series + ``` +2. 在每篇属于该系列的文章 front matter 中添加术语： + ```yaml {filename="content/blog/part-1/index.md"} + --- + title: "Demo Series Part 1" + date: 2024-09-12 + series: + - demo-series + --- + ``` + 通过列出多个术语，一篇文章可以属于多个系列。`series` front matter 还会在文章页面生成 Open Graph 的 `og:see_also` 链接。 +3. （可选）创建术语索引页以设置系列标题并启用 `archives` 布局： + ```yaml {filename="content/series/demo-series/_index.md"} + --- + title: Demo Series + layout: archives + toc: false + --- ``` + 即使没有此页面，`/series/demo-series/` 仍会列出该系列的所有文章。 -空状态文案使用 i18n 键 `noResultsFound`。 +系列的文件结构如下： + +{{< filetree/container >}} + {{< filetree/folder name="content" state="open" >}} + {{< filetree/folder name="blog" state="open" >}} + {{< filetree/folder name="part-1" state="open" >}} + {{< filetree/file name="index.md" >}} + {{< filetree/file name="diagram.png" >}} + {{< /filetree/folder >}} + {{< filetree/file name="part-2.md" >}} + {{< /filetree/folder >}} + {{< filetree/folder name="series" state="open" >}} + {{< filetree/folder name="demo-series" state="open" >}} + {{< filetree/file name="_index.md" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +系列文章仍保留在它们正常的分区（此例中为 `blog`）中。`content/series/` 目录并不是文章的存放位置 — 它是 Hugo 的分类内容目录，仅用于自定义自动生成的 `/series/<名称>/` 术语页面（标题、`archives` 布局）。该目录是可选的：即使没有它，`/series/<名称>/` 也会生成并将系列文章列在系列名称下。 + +与演讲文章类似，系列文章可以是独立的 Markdown 文件，也可以是页面包目录（例如 `part-1/`），将文章与其图片和资源放在一起。 + +### 在菜单中添加系列下拉菜单 + +要在顶部导航中添加列出所有系列的下拉菜单，请添加一个 `type: series` 的菜单项： + +```yaml {filename="hugo.yaml"} +menu: + main: + - identifier: series + name: Series + params: + type: series +``` + +下拉菜单会自动列出每个系列术语。要自定义某个系列显示的标签，请在其术语索引页（`content/series/<名称>/_index.md`）中设置标题。 -示例归档页面可在 [归档]({{% relref "/archives" %}}) 查看。 +示例系列归档可在 [示例系列]({{% relref "/series/demo-series" %}}) 查看。 From b81e3672978da154aa27a82e9ee306606f7d0fb1 Mon Sep 17 00:00:00 2001 From: Nishant Srivastava Date: Fri, 14 Aug 2026 11:56:24 +0200 Subject: [PATCH 3/3] chore(deps): bump nanoid from 3.3.16 to 3.3.18 --- package-lock.json | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 64f70a07..71eb420e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -4,6 +4,7 @@ "requires": true, "packages": { "": { + "name": "hextra", "devDependencies": { "@axe-core/playwright": "^4.11.3", "@playwright/test": "^1.60.0", @@ -1091,9 +1092,9 @@ } }, "node_modules/nanoid": { - "version": "3.3.16", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.16.tgz", - "integrity": "sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==", + "version": "3.3.18", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz", + "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==", "dev": true, "funding": [ {