Initial commit: Rapport Website (Hugo + Hextra)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
File diff suppressed because one or more lines are too long
Binary file not shown.
|
After Width: | Height: | Size: 168 KiB |
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: تم هگزترا
|
||||
layout: hextra-home
|
||||
---
|
||||
|
||||
{{< hextra/hero-badge >}}
|
||||
<div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
|
||||
<span>آزاد، متنباز</span>
|
||||
{{< icon name="arrow-circle-left" attributes="height=14" >}}
|
||||
{{< /hextra/hero-badge >}}
|
||||
|
||||
<div class="hx:mt-6 hx:mb-6">
|
||||
{{< hextra/hero-headline >}}
|
||||
ساخت وبسایتهای مدرن <br class="hx:sm:block hx:hidden" />با مارکداون و هیوگو
|
||||
{{< /hextra/hero-headline >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mb-12">
|
||||
{{< hextra/hero-subtitle >}}
|
||||
تم هیوگو سریع و دارای امکانات کامل <br class="hx:sm:block hx:hidden" />برای ایجاد وبسایتهای استاتیک زیبا
|
||||
{{< /hextra/hero-subtitle >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mb-6">
|
||||
{{< hextra/hero-button text="شروع کنید" link="docs" >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mt-6"></div>
|
||||
|
||||
{{< hextra/feature-grid >}}
|
||||
{{< hextra/feature-card
|
||||
title="سریع و با امکانات کامل"
|
||||
subtitle="ساده و آسان برای استفاده، در عین حال قدرتمند و غنی از ویژگیها متنوع."
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-md:min-h-[340px]"
|
||||
image="/images/hextra-doc.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[24px] hx:w-[180%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="مارکداون تنها چیزی است که شما نیاز دارید"
|
||||
subtitle="فقط با مارکداون بنویسید. تکمیل و کامل با کامپوننتهای کد کوتاه."
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-lg:min-h-[340px]"
|
||||
image="/images/hextra-markdown.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[36px] hx:w-[180%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(142,53,74,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="جستجوی کامل متن"
|
||||
subtitle="جستجوی متن کامل داخلی با FlexSearch، بدون نیاز به نصب موارد اضافی."
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-md:min-h-[340px]"
|
||||
image="/images/hextra-search.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[36px] hx:w-[110%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(221,210,59,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="سبک مانند یک پر"
|
||||
subtitle="برای استفاده از هگزترا به هیچ وابستگی یا Node.js نیاز نیست. با پشتیبانی از هیوگو، یکی از سریعترین تولیدکنندگان سایت استاتیک، سایت شما را تنها در چند ثانیه با یک باینری میسازد."
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title=" واکنشگرا با حالت تیره"
|
||||
subtitle="در اندازههای مختلف صفحه نمایش عالی به نظر میرسد. پشتیبانی از حالت تیره داخلی، با تغییر خودکار براساس اولویت سیستم کاربر."
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="ساخت و میزبانی رایگان"
|
||||
subtitle="با گیتهاب Actions بسازید و به صورت رایگان در گیتهاب Pages میزبانی کنید. یا میتوانید آن را در هر سرویس میزبانی استاتیک میزبانی کنید."
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="چند زبانه آسان"
|
||||
subtitle="فقط با افزودن پسوند محلی به پرونده مارکداون صفحات وبسایت چند زبانه ایجاد کنید. افزودن پشتیبانی i18n به سایت شما بصری است."
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="و خیلی بیشتر..."
|
||||
icon="sparkles"
|
||||
subtitle="برجستهکردن سینتکس / فهرست مطالب / سئو / RSS / LaTeX / Mermaid / سفارشیسازی / و موارد دیگر…"
|
||||
>}}
|
||||
{{< /hextra/feature-grid >}}
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Hextra テーマ
|
||||
layout: hextra-home
|
||||
---
|
||||
|
||||
{{< hextra/hero-badge >}}
|
||||
<div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
|
||||
<span>無料、オープンソース</span>
|
||||
{{< icon name="arrow-circle-right" attributes="height=14" >}}
|
||||
{{< /hextra/hero-badge >}}
|
||||
|
||||
<div class="hx:mt-6 hx:mb-6">
|
||||
{{< hextra/hero-headline >}}
|
||||
MarkdownとHugoで <br class="hx:sm:block hx:hidden" />モダンなウェブサイトを構築
|
||||
{{< /hextra/hero-headline >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mb-12">
|
||||
{{< hextra/hero-subtitle >}}
|
||||
美しい静的ウェブサイトを作るための <br class="hx:sm:block hx:hidden" />高速でバッテリー同梱型のHugoテーマ
|
||||
{{< /hextra/hero-subtitle >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mb-6">
|
||||
{{< hextra/hero-button text="始める" link="docs" >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mt-6"></div>
|
||||
|
||||
{{< hextra/feature-grid >}}
|
||||
{{< hextra/feature-card
|
||||
title="高速かつ多機能"
|
||||
subtitle="シンプルで使いやすく、それでいて強力で豊富な機能を備えています。"
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-md:min-h-[340px]"
|
||||
image="/images/hextra-doc.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[24px] hx:w-[180%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="MarkdownだけでOK"
|
||||
subtitle="Markdownだけで作成可能。ショートコードコンポーネントで充実させることもできます。"
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-lg:min-h-[340px]"
|
||||
image="/images/hextra-markdown.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[36px] hx:w-[180%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(142,53,74,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="全文検索"
|
||||
subtitle="FlexSearchによる全文検索が内蔵されており、追加の設定は不要です。"
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-md:min-h-[340px]"
|
||||
image="/images/hextra-search.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[36px] hx:w-[110%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(221,210,59,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="羽のように軽量"
|
||||
subtitle="Hextraを使用するために依存関係やNode.jsは必要ありません。Hugoによって動力を得ており、単一のバイナリで数秒でサイトを構築できます。"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="レスポンシブ対応とダークモード"
|
||||
subtitle="さまざまな画面サイズで美しく見えます。内蔵のダークモードサポートにより、ユーザーのシステム設定に基づいて自動切り替えが可能です。"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="無料で構築とホスティング"
|
||||
subtitle="GitHub Actionsを使って構築し、GitHub Pagesで無料でホスティングできます。また、他の静的ホスティングサービスでもホスティング可能です。"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="簡単な多言語対応"
|
||||
subtitle="Markdownファイルにロケールサフィックスを追加するだけで多言語ページを作成できます。i18nサポートの追加も直感的です。"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="さらに多くの機能"
|
||||
icon="sparkles"
|
||||
subtitle="構文ハイライト / 目次 / SEO / RSS / LaTeX / Mermaid / カスタマイズ可能 / など多数..."
|
||||
>}}
|
||||
{{< /hextra/feature-grid >}}
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Hextra Theme
|
||||
layout: hextra-home
|
||||
---
|
||||
|
||||
{{< hextra/hero-badge >}}
|
||||
<div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
|
||||
<span>Free, open source</span>
|
||||
{{< icon name="arrow-circle-right" attributes="height=14" >}}
|
||||
{{< /hextra/hero-badge >}}
|
||||
|
||||
<div class="hx:mt-6 hx:mb-6">
|
||||
{{< hextra/hero-headline >}}
|
||||
Build modern websites <br class="hx:sm:block hx:hidden" />with Markdown and Hugo
|
||||
{{< /hextra/hero-headline >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mb-12">
|
||||
{{< hextra/hero-subtitle >}}
|
||||
Fast, batteries-included Hugo theme <br class="hx:sm:block hx:hidden" />for creating beautiful static websites
|
||||
{{< /hextra/hero-subtitle >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mb-6">
|
||||
{{< hextra/hero-button text="Get Started" link="docs" >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mt-6"></div>
|
||||
|
||||
{{< hextra/feature-grid >}}
|
||||
{{< hextra/feature-card
|
||||
title="Fast and Full-featured"
|
||||
subtitle="Simple and easy to use, yet powerful and feature-rich."
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-md:min-h-[340px]"
|
||||
image="images/hextra-doc.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[24px] hx:w-[180%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="Markdown is All You Need"
|
||||
subtitle="Compose with just Markdown. Enrich with Shortcode components."
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-lg:min-h-[340px]"
|
||||
image="images/hextra-markdown.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[36px] hx:w-[180%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(142,53,74,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="Full Text Search"
|
||||
subtitle="Built-in full text search with FlexSearch, no extra setup required."
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-md:min-h-[340px]"
|
||||
image="images/hextra-search.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[36px] hx:w-[110%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(221,210,59,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="Lightweight as a Feather"
|
||||
subtitle="No dependency or Node.js is needed to use Hextra. Powered by Hugo, one of *the fastest* static site generators, building your site in just seconds with a single binary."
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="Responsive with Dark Mode Included"
|
||||
subtitle="Looks great on different screen sizes. Built-in dark mode support, with auto-switching based on user's system preference."
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="Build and Host for Free"
|
||||
subtitle="Build with GitHub Actions, and host for free on GitHub Pages. Alternatively it can be hosted on any static hosting service."
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="Multi-Language Made Easy"
|
||||
subtitle="Create multi-language pages by just adding locales suffix to the Markdown file. Adding i18n support to your site is intuitive."
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="And Much More..."
|
||||
icon="sparkles"
|
||||
subtitle="Syntax highlighting / Table of contents / SEO / RSS / LaTeX / Mermaid / Customizable / and more..."
|
||||
>}}
|
||||
{{< /hextra/feature-grid >}}
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Hextra 主题
|
||||
layout: hextra-home
|
||||
---
|
||||
|
||||
{{< hextra/hero-badge >}}
|
||||
<div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
|
||||
<span>免费 开源</span>
|
||||
{{< icon name="arrow-circle-right" attributes="height=14" >}}
|
||||
{{< /hextra/hero-badge >}}
|
||||
|
||||
<div class="hx:mt-6 hx:mb-6">
|
||||
{{< hextra/hero-headline >}}
|
||||
创建现代化网站 <br class="hx:sm:block hx:hidden" />由 Markdown 和 Hugo 驱动
|
||||
{{< /hextra/hero-headline >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mb-12">
|
||||
{{< hextra/hero-subtitle >}}
|
||||
极速且全能的 Hugo 主题框架 <br class="hx:sm:block hx:hidden" />为构建现代化的静态网站而生
|
||||
{{< /hextra/hero-subtitle >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mb-6">
|
||||
{{< hextra/hero-button text="现在开始" link="docs" >}}
|
||||
</div>
|
||||
|
||||
<div class="hx:mt-6"></div>
|
||||
|
||||
{{< hextra/feature-grid >}}
|
||||
{{< hextra/feature-card
|
||||
title="快速且功能全面"
|
||||
subtitle="简单易用，功能强大丰富。"
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-md:min-h-[340px]"
|
||||
image="/images/hextra-doc.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[24px] hx:w-[180%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="Markdown 写作"
|
||||
subtitle="只需使用 Markdown 进行编辑。多样的 Shortcode 组件开箱即用。"
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-lg:min-h-[340px]"
|
||||
image="/images/hextra-markdown.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[36px] hx:w-[180%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(142,53,74,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="全文搜索"
|
||||
subtitle="内置 FlexSearch 全文搜索，无需额外设置。"
|
||||
class="hx:aspect-auto hx:md:aspect-[1.1/1] hx:max-md:min-h-[340px]"
|
||||
image="/images/hextra-search.webp"
|
||||
imageClass="hx:top-[40%] hx:left-[36px] hx:w-[110%] hx:sm:w-[110%] hx:dark:opacity-80"
|
||||
style="background: radial-gradient(ellipse at 50% 80%,rgba(221,210,59,0.15),hsla(0,0%,100%,0));"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="轻如羽毛"
|
||||
subtitle="使用 Hextra 无需依赖 Node.js。由 Hugo 提供支持，Hugo 是最快的静态网站生成器之一，只需一个二进制文件即可在数秒内创建网站。"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="响应式布局，暗黑模式"
|
||||
subtitle="适应不同的屏幕尺寸。内置暗黑模式支持，并根据用户的系统偏好自动切换。"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="免费构建和托管"
|
||||
subtitle="使用 GitHub Actions 进行构建，并在 GitHub Pages 上免费托管。也可以托管在任何静态托管服务上。"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="多语言轻松实现"
|
||||
subtitle="仅需通过在 Markdown 文件后添加语言代码即可创建多语言页面。向您的站点添加 i18n 支持直观易行。"
|
||||
>}}
|
||||
{{< hextra/feature-card
|
||||
title="还有更多..."
|
||||
icon="sparkles"
|
||||
subtitle="代码高亮 / 目录 / SEO / RSS / LaTeX 公式 / Mermaid 图标 / 自定义 / 等等..."
|
||||
>}}
|
||||
{{< /hextra/feature-grid >}}
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: درباره ما
|
||||
toc: false
|
||||
---
|
||||
|
||||
هگزترا به گونهای طراحی شده است که یک موضوع ساده، سریع و انعطاف پذیر برای ساخت وبسایتهای استاتیک مدرن باشد. این به ویژه برای وبسایتهای مستندسازی مناسب است اما میتواند برای انواع مختلف سایتها مانند وبلاگها، نمونهکار و موارد دیگر نیز استفاده شود.
|
||||
|
||||
Hugo مانند Jekyll، یک ایجادکننده سایت استاتیک است. چیزی که Hugo را متمایز میکند این است که یک باینری واحد است و نصب و اجرای آن بر روی پلتفرمهای مختلف را آسان میکند. همچنین بسیار سریع و قابل اعتماد است و میتواند یک سایت را با هزاران صفحه در میلیثانیه ارائه دهد.
|
||||
|
||||
هگزترا با ذهنیتی ساخته شده است که بر داشتن حداقل ردپا متمرکز شده است. برای شروع، هیچ وابستگی اضافی مانند بستههای Node.js لازم نیست. تنها چیزی که نیاز دارید یک پرونده پیکربندی YAML به همراه محتوای مارکداون شما است. بنابراین، شما میتوانید به جای تنظیم ابزار، روی نوشتن محتوای با کیفیت تمرکز کنید.
|
||||
|
||||
## اعتبار
|
||||
|
||||
ترجمه فارسی مستندات توسط [گودرز جعفری](https://goudarzjafari.com/) انجام شده است.
|
||||
|
||||
هگزترا بدون ابزار و الهامات زیر ساخته نمیشود:
|
||||
|
||||
- [هیوگو](https://gohugo.io/)
|
||||
- [Tailwind CSS](https://tailwindcss.com/)
|
||||
- [Heroicons](https://heroicons.com/)
|
||||
- [Nextra](https://nextra.vercel.app/)
|
||||
- [Next.js](https://nextjs.org/)
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: このサイトについて
|
||||
toc: false
|
||||
---
|
||||
|
||||
Hextra は、モダンな静的サイトを構築するためのシンプルで高速かつ柔軟なテーマとして設計されています。特にドキュメントサイトの構築に適していますが、ブログやポートフォリオなど様々な種類のサイトにも利用可能です。
|
||||
|
||||
Hugo は Jekyll と同様に静的サイトジェネレータですが、単一のバイナリで構成されている点が特徴です。これにより様々なプラットフォームでのインストールと実行が容易で、極めて高速かつ信頼性が高く、数千ページあるサイトでもミリ秒単位でレンダリング可能です。
|
||||
|
||||
Hextra は最小限のフットプリントに焦点を当てた思想で構築されています。開始するにあたり、Node.js パッケージなどの追加依存関係は不要で、必要なのは単一の YAML 設定ファイルと Markdown コンテンツのみです。これにより、ツールのセットアップではなく質の高いコンテンツの作成に集中できます。
|
||||
|
||||
## クレジット
|
||||
|
||||
Hextra は以下のツールとインスピレーションなしには成り立ちません:
|
||||
|
||||
- [Hugo](https://gohugo.io/)
|
||||
- [Tailwind CSS](https://tailwindcss.com/)
|
||||
- [Heroicons](https://heroicons.com/)
|
||||
- [Nextra](https://nextra.vercel.app/)
|
||||
- [Next.js](https://nextjs.org/)
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: About
|
||||
toc: false
|
||||
---
|
||||
|
||||
Hextra is designed to be a simple, fast, and flexible theme for building modern static websites. It is especially well-suited for documentation websites but can also be used for various types of sites, such as blogs, portfolios, and more.
|
||||
|
||||
Hugo, like Jekyll, is a static site generator. What sets Hugo apart is that it is a single binary, making it easy to install and run on various platforms. It is also extremely fast and reliable, capable of rendering a site with thousands of pages in milliseconds.
|
||||
|
||||
Hextra is built with a mindset focused on having a minimal footprint. To get started, no extra dependencies like Node.js packages are required; all you need is a single YAML configuration file, along with your Markdown content. Thus, we can focus on writing quality content instead of setting up tooling.
|
||||
|
||||
## Credits
|
||||
|
||||
Hextra cannot be built without the following tools and inspirations:
|
||||
|
||||
- [Hugo](https://gohugo.io/)
|
||||
- [Tailwind CSS](https://tailwindcss.com/)
|
||||
- [Heroicons](https://heroicons.com/)
|
||||
- [Nextra](https://nextra.vercel.app/)
|
||||
- [Next.js](https://nextjs.org/)
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: 关于
|
||||
toc: false
|
||||
---
|
||||
|
||||
Hextra 是一款专为构建现代化静态网站而设计的简洁、快速且灵活的主题。它尤其适合搭建文档类网站，同时也能轻松驾驭博客、作品集等多种站点类型。
|
||||
|
||||
与 Jekyll 类似，Hugo 同样是一款静态网站生成器。其独特之处在于采用单一二进制文件，可在多平台轻松安装运行。Hugo 以极致的速度与稳定性著称，能在毫秒间渲染包含数千页面的网站。
|
||||
|
||||
Hextra 秉持极简理念开发。您无需安装 Node.js 等额外依赖，仅需一个 YAML 配置文件搭配 Markdown 内容即可快速开始。这让我们能专注于创作优质内容，而非配置工具链。
|
||||
|
||||
## 致谢
|
||||
|
||||
Hextra 的诞生离不开以下工具与灵感的启发：
|
||||
|
||||
- [Hugo](https://gohugo.io/)
|
||||
- [Tailwind CSS](https://tailwindcss.com/)
|
||||
- [Heroicons](https://heroicons.com/)
|
||||
- [Nextra](https://nextra.vercel.app/)
|
||||
- [Next.js](https://nextjs.org/)
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: آرشیو
|
||||
layout: archives
|
||||
toc: false
|
||||
---
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: アーカイブ
|
||||
layout: archives
|
||||
toc: false
|
||||
---
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: Archives
|
||||
layout: archives
|
||||
toc: false
|
||||
---
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: 归档
|
||||
layout: archives
|
||||
toc: false
|
||||
---
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: "وبلاگ"
|
||||
---
|
||||
|
||||
<div style="text-align: center; margin-top: 1em;">
|
||||
{{< hextra/hero-badge link="index.xml" >}}
|
||||
<span>فید RSS</span>
|
||||
{{< icon name="rss" attributes="height=14" >}}
|
||||
{{< /hextra/hero-badge >}}
|
||||
</div>
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: "ブログ"
|
||||
---
|
||||
|
||||
<div style="text-align: center; margin-top: 1em;">
|
||||
{{< hextra/hero-badge link="index.xml" >}}
|
||||
<span>RSS フィード</span>
|
||||
{{< icon name="rss" attributes="height=14" >}}
|
||||
{{< /hextra/hero-badge >}}
|
||||
</div>
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: "Blog"
|
||||
---
|
||||
|
||||
<div style="text-align: center; margin-top: 1em;">
|
||||
{{< hextra/hero-badge link="index.xml" >}}
|
||||
<span>RSS Feed</span>
|
||||
{{< icon name="rss" attributes="height=14" >}}
|
||||
{{< /hextra/hero-badge >}}
|
||||
</div>
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: "博客"
|
||||
---
|
||||
|
||||
<div style="text-align: center; margin-top: 1em;">
|
||||
{{< hextra/hero-badge link="index.xml" >}}
|
||||
<span>RSS 订阅</span>
|
||||
{{< icon name="rss" attributes="height=14" >}}
|
||||
{{< /hextra/hero-badge >}}
|
||||
</div>
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
title: راهنمای نحو Markdown
|
||||
date: 2020-01-01
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
- name: Octocat
|
||||
link: https://github.com/octocat
|
||||
image: https://github.com/octocat.png
|
||||
- name: Goudarz Jafari
|
||||
link: https://github.com/Goudarz
|
||||
image: https://github.com/Goudarz.png
|
||||
tags:
|
||||
- Markdown
|
||||
- مثال
|
||||
- راهنما
|
||||
excludeSearch: true
|
||||
---
|
||||
|
||||
این مقاله نمونهای از نحو پایهای Markdown را ارائه میدهد که میتوان در فایلهای محتوای Hugo استفاده کرد.
|
||||
<!--more-->
|
||||
|
||||
## نحو پایه
|
||||
|
||||
### سرتیترها
|
||||
|
||||
```
|
||||
# سرتیتر 1
|
||||
## سرتیتر 2
|
||||
### سرتیتر 3
|
||||
#### سرتیتر 4
|
||||
##### سرتیتر 5
|
||||
###### سرتیتر 6
|
||||
```
|
||||
|
||||
## سرتیتر 2
|
||||
### سرتیتر 3
|
||||
#### سرتیتر 4
|
||||
##### سرتیتر 5
|
||||
###### سرتیتر 6
|
||||
|
||||
### تأکید
|
||||
|
||||
```text
|
||||
*این متن به صورت ایتالیک نمایش داده میشود*
|
||||
_این نیز به صورت ایتالیک نمایش داده میشود_
|
||||
|
||||
**این متن به صورت پررنگ نمایش داده میشود**
|
||||
__این نیز به صورت پررنگ نمایش داده میشود__
|
||||
|
||||
_شما میتوانید **آنها را ترکیب** کنید_
|
||||
```
|
||||
|
||||
*این متن به صورت ایتالیک نمایش داده میشود*
|
||||
|
||||
_این نیز به صورت ایتالیک نمایش داده میشود_
|
||||
|
||||
**این متن به صورت پررنگ نمایش داده میشود**
|
||||
|
||||
__این نیز به صورت پررنگ نمایش داده میشود__
|
||||
|
||||
_شما میتوانید **آنها را ترکیب** کنید_
|
||||
|
||||
### فهرستها
|
||||
|
||||
#### بدون ترتیب
|
||||
|
||||
```
|
||||
* مورد ۱
|
||||
* مورد ۲
|
||||
* مورد ۲الف
|
||||
* مورد ۲ب
|
||||
```
|
||||
|
||||
* مورد ۱
|
||||
* مورد ۲
|
||||
* مورد ۲الف
|
||||
* مورد ۲ب
|
||||
|
||||
#### با ترتیب
|
||||
|
||||
```
|
||||
۱. مورد ۱
|
||||
۲. مورد ۲
|
||||
۳. مورد ۳
|
||||
۱. مورد ۳الف
|
||||
۲. مورد ۳ب
|
||||
```
|
||||
|
||||
### تصاویر
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
### پیوندها
|
||||
|
||||
```markdown
|
||||
[Hugo](https://gohugo.io)
|
||||
```
|
||||
|
||||
[Hugo](https://gohugo.io)
|
||||
|
||||
### نقلقولها
|
||||
|
||||
```markdown
|
||||
همانطور که نیوتن گفت:
|
||||
|
||||
> اگر من دورتر را دیدهام، به این دلیل است که بر شانههای غولها ایستادهام.
|
||||
```
|
||||
|
||||
> اگر من دورتر را دیدهام، به این دلیل است که بر شانههای غولها ایستادهام.
|
||||
|
||||
### کد درونخطی
|
||||
|
||||
```markdown
|
||||
کد `درونخطی` با `علامت back-tick` احاطه شده است.
|
||||
```
|
||||
|
||||
کد `درونخطی` با `علامت back-tick` احاطه شده است.
|
||||
|
||||
### بلوکهای کد
|
||||
|
||||
#### هایلایت سینتکس
|
||||
|
||||
````markdown
|
||||
```go
|
||||
func main() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
```go
|
||||
func main() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
```
|
||||
|
||||
### جداول
|
||||
|
||||
```markdown
|
||||
| سینتکس | توضیحات |
|
||||
| --------- | ----------- |
|
||||
| هدر | عنوان |
|
||||
| پاراگراف | متن |
|
||||
```
|
||||
|
||||
| سینتکس | توضیحات |
|
||||
| --------- | ----------- |
|
||||
| هدر | عنوان |
|
||||
| پاراگراف | متن |
|
||||
|
||||
## منابع
|
||||
|
||||
- [نحو Markdown](https://www.markdownguide.org/basic-syntax/)
|
||||
- [Markdown در Hugo](https://gohugo.io/content-management/formats/#markdown)
|
||||
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: Markdown 構文ガイド
|
||||
date: 2020-01-01
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
- name: Octocat
|
||||
link: https://github.com/octocat
|
||||
image: https://github.com/octocat.png
|
||||
tags:
|
||||
- Markdown
|
||||
- サンプル
|
||||
- ガイド
|
||||
excludeSearch: true
|
||||
---
|
||||
|
||||
この記事では、Hugo のコンテンツファイルで使用できる基本的な Markdown 構文のサンプルを紹介します。
|
||||
<!--more-->
|
||||
|
||||
## 基本構文
|
||||
|
||||
### 見出し
|
||||
|
||||
```
|
||||
# 見出し1
|
||||
## 見出し2
|
||||
### 見出し3
|
||||
#### 見出し4
|
||||
##### 見出し5
|
||||
###### 見出し6
|
||||
```
|
||||
|
||||
## 見出し2
|
||||
### 見出し3
|
||||
#### 見出し4
|
||||
##### 見出し5
|
||||
###### 見出し6
|
||||
|
||||
### 強調
|
||||
|
||||
```text
|
||||
*このテキストは斜体になります*
|
||||
_これも斜体になります_
|
||||
|
||||
**このテキストは太字になります**
|
||||
__これも太字になります__
|
||||
|
||||
_これらを**組み合わせる**こともできます_
|
||||
```
|
||||
|
||||
*このテキストは斜体になります*
|
||||
|
||||
_これも斜体になります_
|
||||
|
||||
**このテキストは太字になります**
|
||||
|
||||
__これも太字になります__
|
||||
|
||||
_これらを**組み合わせる**こともできます_
|
||||
|
||||
### リスト
|
||||
|
||||
#### 順序なしリスト
|
||||
|
||||
```
|
||||
* 項目1
|
||||
* 項目2
|
||||
* 項目2a
|
||||
* 項目2b
|
||||
```
|
||||
|
||||
* 項目1
|
||||
* 項目2
|
||||
* 項目2a
|
||||
* 項目2b
|
||||
|
||||
#### 順序付きリスト
|
||||
|
||||
```
|
||||
1. 項目1
|
||||
2. 項目2
|
||||
3. 項目3
|
||||
1. 項目3a
|
||||
2. 項目3b
|
||||
```
|
||||
|
||||
### 画像
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
### リンク
|
||||
|
||||
```markdown
|
||||
[Hugo](https://gohugo.io)
|
||||
```
|
||||
|
||||
[Hugo](https://gohugo.io)
|
||||
|
||||
### ブロッククォート
|
||||
|
||||
```markdown
|
||||
ニュートンはこう言いました:
|
||||
|
||||
> 私が遠くを見渡せたとしたら、それは巨人の肩の上に立っていたからです。
|
||||
```
|
||||
|
||||
> 私が遠くを見渡せたとしたら、それは巨人の肩の上に立っていたからです。
|
||||
|
||||
### インラインコード
|
||||
|
||||
```markdown
|
||||
インライン `コード` は `バッククォートで囲みます`。
|
||||
```
|
||||
|
||||
インライン `コード` は `バッククォートで囲みます`。
|
||||
|
||||
### コードブロック
|
||||
|
||||
#### シンタックスハイライト
|
||||
|
||||
````markdown
|
||||
```go
|
||||
func main() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
```go
|
||||
func main() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
```
|
||||
|
||||
### テーブル
|
||||
|
||||
```markdown
|
||||
| 構文 | 説明 |
|
||||
| --------- | ----------- |
|
||||
| 見出し | タイトル |
|
||||
| 段落 | テキスト |
|
||||
```
|
||||
|
||||
| 構文 | 説明 |
|
||||
| --------- | ----------- |
|
||||
| 見出し | タイトル |
|
||||
| 段落 | テキスト |
|
||||
|
||||
## 参考資料
|
||||
|
||||
- [Markdown 構文](https://www.markdownguide.org/basic-syntax/)
|
||||
- [Hugo Markdown](https://gohugo.io/content-management/formats/#markdown)
|
||||
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: Markdown Syntax Guide
|
||||
date: 2020-01-01
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
- name: Octocat
|
||||
link: https://github.com/octocat
|
||||
image: https://github.com/octocat.png
|
||||
tags:
|
||||
- Markdown
|
||||
- Example
|
||||
- Guide
|
||||
excludeSearch: true
|
||||
---
|
||||
|
||||
This article offers a sample of basic Markdown syntax that can be used in Hugo content files.
|
||||
<!--more-->
|
||||
|
||||
## Basic Syntax
|
||||
|
||||
### Headings
|
||||
|
||||
```
|
||||
# Heading 1
|
||||
## Heading 2
|
||||
### Heading 3
|
||||
#### Heading 4
|
||||
##### Heading 5
|
||||
###### Heading 6
|
||||
```
|
||||
|
||||
## Heading 2
|
||||
### Heading 3
|
||||
#### Heading 4
|
||||
##### Heading 5
|
||||
###### Heading 6
|
||||
|
||||
### Emphasis
|
||||
|
||||
```text
|
||||
*This text will be italic*
|
||||
_This will also be italic_
|
||||
|
||||
**This text will be bold**
|
||||
__This will also be bold__
|
||||
|
||||
_You **can** combine them_
|
||||
```
|
||||
|
||||
*This text will be italic*
|
||||
|
||||
_This will also be italic_
|
||||
|
||||
**This text will be bold**
|
||||
|
||||
__This will also be bold__
|
||||
|
||||
_You **can** combine them_
|
||||
|
||||
### Lists
|
||||
|
||||
#### Unordered
|
||||
|
||||
```
|
||||
* Item 1
|
||||
* Item 2
|
||||
* Item 2a
|
||||
* Item 2b
|
||||
```
|
||||
|
||||
* Item 1
|
||||
* Item 2
|
||||
* Item 2a
|
||||
* Item 2b
|
||||
|
||||
#### Ordered
|
||||
|
||||
```
|
||||
1. Item 1
|
||||
2. Item 2
|
||||
3. Item 3
|
||||
1. Item 3a
|
||||
2. Item 3b
|
||||
```
|
||||
|
||||
### Images
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Links
|
||||
|
||||
```markdown
|
||||
[Hugo](https://gohugo.io)
|
||||
```
|
||||
|
||||
[Hugo](https://gohugo.io)
|
||||
|
||||
### Blockquotes
|
||||
|
||||
```markdown
|
||||
As Newton said:
|
||||
|
||||
> If I have seen further it is by standing on the shoulders of Giants.
|
||||
```
|
||||
|
||||
> If I have seen further it is by standing on the shoulders of Giants.
|
||||
|
||||
### Inline Code
|
||||
|
||||
```markdown
|
||||
Inline `code` has `back-ticks around` it.
|
||||
```
|
||||
|
||||
Inline `code` has `back-ticks around` it.
|
||||
|
||||
### Code Blocks
|
||||
|
||||
#### Syntax Highlighting
|
||||
|
||||
````markdown
|
||||
```go
|
||||
func main() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
```go
|
||||
func main() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
```
|
||||
|
||||
### Tables
|
||||
|
||||
```markdown
|
||||
| Syntax | Description |
|
||||
| --------- | ----------- |
|
||||
| Header | Title |
|
||||
| Paragraph | Text |
|
||||
```
|
||||
|
||||
| Syntax | Description |
|
||||
| --------- | ----------- |
|
||||
| Header | Title |
|
||||
| Paragraph | Text |
|
||||
|
||||
## References
|
||||
|
||||
- [Markdown Syntax](https://www.markdownguide.org/basic-syntax/)
|
||||
- [Hugo Markdown](https://gohugo.io/content-management/formats/#markdown)
|
||||
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: Markdown 语法指南
|
||||
date: 2020-01-01
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
- name: Octocat
|
||||
link: https://github.com/octocat
|
||||
image: https://github.com/octocat.png
|
||||
tags:
|
||||
- Markdown
|
||||
- 示例
|
||||
- 指南
|
||||
excludeSearch: true
|
||||
---
|
||||
|
||||
本文展示了 Hugo 内容文件中可用的基础 Markdown 语法示例。
|
||||
<!--more-->
|
||||
|
||||
## 基础语法
|
||||
|
||||
### 标题
|
||||
|
||||
```
|
||||
# 一级标题
|
||||
## 二级标题
|
||||
### 三级标题
|
||||
#### 四级标题
|
||||
##### 五级标题
|
||||
###### 六级标题
|
||||
```
|
||||
|
||||
## 二级标题
|
||||
### 三级标题
|
||||
#### 四级标题
|
||||
##### 五级标题
|
||||
###### 六级标题
|
||||
|
||||
### 强调
|
||||
|
||||
```text
|
||||
*这段文字会显示为斜体*
|
||||
_这段文字也会显示为斜体_
|
||||
|
||||
**这段文字会显示为粗体**
|
||||
__这段文字也会显示为粗体__
|
||||
|
||||
_你可以**组合**使用_
|
||||
```
|
||||
|
||||
*这段文字会显示为斜体*
|
||||
|
||||
_这段文字也会显示为斜体_
|
||||
|
||||
**这段文字会显示为粗体**
|
||||
|
||||
__这段文字也会显示为粗体__
|
||||
|
||||
_你可以**组合**使用_
|
||||
|
||||
### 列表
|
||||
|
||||
#### 无序列表
|
||||
|
||||
```
|
||||
* 项目1
|
||||
* 项目2
|
||||
* 子项目2a
|
||||
* 子项目2b
|
||||
```
|
||||
|
||||
* 项目1
|
||||
* 项目2
|
||||
* 子项目2a
|
||||
* 子项目2b
|
||||
|
||||
#### 有序列表
|
||||
|
||||
```
|
||||
1. 项目1
|
||||
2. 项目2
|
||||
3. 项目3
|
||||
1. 子项目3a
|
||||
2. 子项目3b
|
||||
```
|
||||
|
||||
### 图片
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 链接
|
||||
|
||||
```markdown
|
||||
[Hugo](https://gohugo.io)
|
||||
```
|
||||
|
||||
[Hugo](https://gohugo.io)
|
||||
|
||||
### 引用块
|
||||
|
||||
```markdown
|
||||
正如牛顿所说：
|
||||
|
||||
> 如果说我看得比别人更远些，那是因为我站在巨人的肩膀上。
|
||||
```
|
||||
|
||||
> 如果说我看得比别人更远些，那是因为我站在巨人的肩膀上。
|
||||
|
||||
### 行内代码
|
||||
|
||||
```markdown
|
||||
行内`代码`会用`反引号包裹`起来。
|
||||
```
|
||||
|
||||
行内`代码`会用`反引号包裹`起来。
|
||||
|
||||
### 代码块
|
||||
|
||||
#### 语法高亮
|
||||
|
||||
````markdown
|
||||
```go
|
||||
func main() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
```go
|
||||
func main() {
|
||||
fmt.Println("Hello World")
|
||||
}
|
||||
```
|
||||
|
||||
### 表格
|
||||
|
||||
```markdown
|
||||
| 语法 | 描述 |
|
||||
| --------- | ----------- |
|
||||
| 标题 | 标题文本 |
|
||||
| 段落 | 正文内容 |
|
||||
```
|
||||
|
||||
| 语法 | 描述 |
|
||||
| --------- | ----------- |
|
||||
| 标题 | 标题文本 |
|
||||
| 段落 | 正文内容 |
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Markdown 语法](https://www.markdownguide.org/basic-syntax/)
|
||||
- [Hugo Markdown](https://gohugo.io/content-management/formats/#markdown)
|
||||
@@ -0,0 +1,247 @@
|
||||
---
|
||||
title: "Hextra v0.10"
|
||||
date: 2025-08-14
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- انتشار
|
||||
---
|
||||
|
||||
Hextra v0.10.0 یک انتشار بزرگ است که مملو از قابلیتهای جدید، ارتقاهای معماری و بهبودهای کیفیت زندگی میباشد.
|
||||
|
||||
<!--more-->
|
||||
|
||||
همچنین شامل مشارکتهای 10 [مشارکتکننده جدید](#contributors) بوده و درخواستهای دیرینه جامعه را برطرف میکند.
|
||||
|
||||
## راهنمای ارتقا
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **تغییرات شکستآمیز**: این انتشار شامل چندین تغییر شکستآمیز است. لطفاً قبل از ارتقا، چکلیست و [راهنمای مهاجرت](#migration-guide) را بررسی کنید.
|
||||
|
||||
قبل از ارتقا به v0.10.0، مطمئن شوید که:
|
||||
|
||||
- Hugo v0.146.0+ (نسخه extended) نصب شده است
|
||||
- CSS سفارشی را برای تغییرات نام کلاس بررسی کردهاید (به [تغییرات پیشوند کلاسهای CSS](#css-class-prefix-changes) و [Tailwind CSS v4](#tailwind-css-v4) مراجعه کنید)
|
||||
- تأیید کردهاید که محیط ساخت دسترسی به اینترنت برای دانلود داراییها هنگام استفاده از LaTeX و/یا Mermaid دارد
|
||||
|
||||
پس از آمادهسازی، ماژول Hugo را بهروزرسانی کنید:
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra@v0.10.0
|
||||
```
|
||||
|
||||
## ویژگیهای جدید
|
||||
|
||||
در زیر لیستی از ویژگیهای جدید قابل توجه در این انتشار آمده است:
|
||||
|
||||
- [**پشتیبانی از منوی کشویی در نوار ناوبری**](#dropdown-menu-support-in-navbar): ایجاد منوهای ناوبری سلسلهمراتبی
|
||||
- [**تجربه جستجوی بهبودیافته**](#enhanced-search-experience): جستجوی بهبودیافته در تمام سرتیترها با دقت بهتر
|
||||
- [**پشتیبانی از llms.txt**](#llmstxt-support): تولید خلاصه سایت مناسب برای هوش مصنوعی
|
||||
- [**هایلایت کردن اسکرول فهرست مطالب**](#table-of-contents-scroll-highlighting): هایلایت کردن خودکار سرتیترها هنگام اسکرول صفحه
|
||||
- [**تبدیل همگام تبها**](#synchronized-tab-switching): همگامسازی انتخاب تبها در چندین گروه تب
|
||||
- [**صفحهبندی لیست وبلاگ**](#blog-list-pagination): اضافه کردن کنترلهای صفحهبندی به صفحات لیست وبلاگ
|
||||
- [**پشتیبانی از MathJax**](#mathjax-support): موتور رندر ریاضی جایگزین در کنار KaTeX
|
||||
|
||||
### پشتیبانی از منوی کشویی در نوار ناوبری
|
||||
|
||||
منوهای کشویی را در نوار ناوبری خود برای سازماندهی بهتر موارد ناوبری ایجاد کنید.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: products
|
||||
name: "محصولات"
|
||||
- name: "محصول الف"
|
||||
parent: products
|
||||
url: "/product-a"
|
||||
- name: "محصول ب"
|
||||
parent: products
|
||||
url: "/product-b"
|
||||
```
|
||||
|
||||
|
||||
|
||||
### تجربه جستجوی بهبودیافته
|
||||
|
||||
- **جستجو در تمام سرتیترها**: یافتن محتوا در تمام سطوح سرتیترها، نه فقط عنوان صفحات
|
||||
- **دقت بهتر نتایج**: مدیریت بهتر عنوانها و دقت پیونددهی
|
||||
- **ناوبری ثابت نتایج**: نتایج جستجو اکنون به بخشهای صحیح صفحه پیوند میخورند
|
||||
|
||||
با تشکر ویژه از [@ldez](https://github.com/ldez) برای پیشبرد قابلیتهای جستجو!
|
||||
|
||||
|
||||
|
||||
### پشتیبانی از llms.txt
|
||||
|
||||
Hextra اکنون از فرمت خروجی [llms.txt](https://llmstxt.org/) برای سایت شما پشتیبانی میکند، که سایت شما را برای ابزارهای هوش مصنوعی و مدلهای زبانی برای زمینه و مرجع قابل دسترستر میسازد.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
home: [html, llms]
|
||||
```
|
||||
|
||||
این یک فایل `llms.txt` در ریشه سایت شما ایجاد میکند.
|
||||
|
||||
|
||||
|
||||
### هایلایت کردن اسکرول فهرست مطالب
|
||||
|
||||
فهرست مطالب اکنون بهطور خودکار بخش فعلی را هنگام اسکرول صفحه هایلایت میکند، که ناوبری را شهودیتر میسازد.
|
||||
|
||||
|
||||
|
||||
### تبدیل همگام تبها
|
||||
|
||||
تبهایی با موارد یکسان اکنون در سراسر صفحه همگام میشوند. هنگامی که همگامسازی فعال است، انتخاب یک تب تمام گروههای تب که لیست موارد یکسانی دارند را بهروزرسانی میکند (و انتخاب شما به خاطر سپرده میشود).
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
tabs:
|
||||
sync: true
|
||||
```
|
||||
|
||||
### صفحهبندی لیست وبلاگ
|
||||
|
||||
کنترلهای صفحهبندی پایه به صفحات لیست وبلاگ اضافه شدهاند.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
blog:
|
||||
list:
|
||||
pagerSize: 20 # پستها در هر صفحه
|
||||
```
|
||||
|
||||
|
||||
|
||||
### پشتیبانی از MathJax
|
||||
|
||||
عبارات ریاضی را با [MathJax](https://www.mathjax.org/) در کنار پشتیبانی پیشفرض KaTeX رندر کنید. موتوری را انتخاب کنید که بهترین تناسب را با نیازهای شما دارد.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: "mathjax" # پیشفرض "katex" است
|
||||
```
|
||||
|
||||
## بهبودهای فنی
|
||||
|
||||
### چارچوب و سیستم ساخت
|
||||
|
||||
- **مهاجرت به Tailwind CSS v4**: مهاجرت کامل به [Tailwind CSS v4](https://tailwindcss.com/blog/tailwindcss-v4) با پشتیبانی بهبودیافته سفارشیسازی.
|
||||
- **سیستم قالب Hugo**: سازگار با [سیستم قالب جدید Hugo](https://gohugo.io/templates/new-templatesystem-overview/) (v0.146.0+) برای سازگاری آینده.
|
||||
- **رندر سمت سرور ریاضی**: مدیریت بهتر رندر معادلات ریاضی با استفاده از رندر بومی Hugo بهصورت پیشفرض.
|
||||
- **ارتقای FlexSearch 0.8**: ارتقای موتور جستجو [FlexSearch](https://github.com/nextapps-de/flexsearch) برای نتایج سریعتر و دقیقتر با رمزگذاری بهبودیافته محتوای CJK (چینی، ژاپنی، کرهای).
|
||||
- **مدیریت بهبودیافته داراییها**: داراییهای KaTeX و Mermaid از بارگیری از CDN یا محلی پشتیبانی میکنند
|
||||
|
||||
## بهبودهای کیفیت زندگی
|
||||
|
||||
- **تغییر دینامیک favicon**: بهروزرسانی خودکار favicon بر اساس ترجیحات طرح رنگ
|
||||
- **صفحهبندی معکوس**: نویسندگان اکنون میتوانند `reversePagination` را در front matter صفحه تنظیم کنند
|
||||
- **کنترل نمایهسازی گوگل**: پارامتر صفحه جدید برای مسدود کردن نمایهسازی گوگل در صورت نیاز
|
||||
- **بهبودهای مدیریت عرض**: کنترلهای طراحی پاسخگو بهتر از طریق متغیرهای CSS
|
||||
- **بهبودهای استایل**: استایلهای مدرن برای جدول Markdown و خط افقی
|
||||
|
||||
## رفع اشکالات و پایداری
|
||||
|
||||
- **همگامسازی تم Giscus**: نظرات اکنون به درستی تغییرات حالت تاریک/روشن را دنبال میکنند
|
||||
- **دقت نتایج جستجو**: رفع مشکلات پیونددهی و فرار عنوان در نتایج جستجو
|
||||
- **تبدیل تبها**: رفع مشکلات ناوبری در حالت غیرهمگام تب
|
||||
- **اسکرول فانتوم**: رفع رفتار ناخواسته اسکرول هنگام غیرفعال بودن پاورقی
|
||||
- **دسترسی تصویر**: جلوگیری از رندر تکراری متن alt
|
||||
- **رندر پیوند**: بهبود مدیریت URL پایه برای ساختارهای پیچیده سایت
|
||||
|
||||
---
|
||||
|
||||
## راهنمای مهاجرت
|
||||
|
||||
- [**نیازمندیهای نسخه Hugo**](#hugo-version-requirements): نیاز به Hugo v0.146.0+ (نسخه extended) دارد
|
||||
- [**تغییرات پیشوند کلاسهای CSS**](#css-class-prefix-changes): کلاسهای CSS کامپوننت اکنون از پیشوند سازگار `hextra-` استفاده میکنند
|
||||
- [**مدیریت داراییها**](#asset-management-for-katex-and-mermaid): داراییهای KaTeX و Mermaid اکنون در زمان ساخت دانلود میشوند
|
||||
- [**Tailwind CSS v4**](#tailwind-css-v4): کامپایل CSS داخلی اکنون از Tailwind CSS v4.x با پیشوند `hx:` استفاده میکند
|
||||
|
||||
#### نیازمندیهای نسخه Hugo
|
||||
|
||||
**تأثیر**: سایتهایی که از نسخههای قدیمی Hugo استفاده میکنند
|
||||
|
||||
Hextra v0.10.0 به دلیل پذیرش سیستم قالب جدید، نیاز به Hugo v0.146.0 یا بالاتر (نسخه extended) دارد.
|
||||
|
||||
**اقدام مورد نیاز**: قبل از ارتقای Hextra، Hugo را به v0.146.0+ بهروزرسانی کنید
|
||||
|
||||
#### تغییرات پیشوند کلاسهای CSS
|
||||
|
||||
**تأثیر**: سایتهایی با CSS سفارشی که کلاسهای کامپوننت Hextra را هدف قرار میدهند
|
||||
|
||||
Hextra v0.10.0 پیشوند سازگار `hextra-` را برای اکثر کلاسهای CSS کامپوننت معرفی میکند تا قابلیت نگهداری را بهبود بخشد و از تداخل با استایلهای کاربر جلوگیری کند.
|
||||
|
||||
**اقدام مورد نیاز**: اگر CSS سفارشی دارید که کامپوننتهای Hextra را هدف قرار میدهد، نام کلاسهای زیر را بهروزرسانی کنید:
|
||||
|
||||
| حوزه | قبل | بعد |
|
||||
| -------------------- | ---------------------------- | ------------------------------------------------- |
|
||||
| جستجو (ظرف) | `.search-wrapper` | `.hextra-search-wrapper` |
|
||||
| جستجو (ورودی) | `.search-input` | `.hextra-search-input` |
|
||||
| جستجو (نتایج) | `.search-results` | `.hextra-search-results` |
|
||||
| جستجو (عنوان) | `.search-wrapper .title` | `.hextra-search-wrapper .hextra-search-title` |
|
||||
| جستجو (مورد فعال) | `.search-wrapper .active` | `.hextra-search-wrapper .hextra-search-active` |
|
||||
| جستجو (بدون نتیجه) | `.search-wrapper .no-result` | `.hextra-search-wrapper .hextra-search-no-result` |
|
||||
| جستجو (پیشوند) | `.search-wrapper .prefix` | `.hextra-search-wrapper .hextra-search-prefix` |
|
||||
| جستجو (گزیده) | `.search-wrapper .excerpt` | `.hextra-search-wrapper .hextra-search-excerpt` |
|
||||
| جستجو (مطابقت) | `.search-wrapper .match` | `.hextra-search-wrapper .hextra-search-match` |
|
||||
| تارنما محو | `.nav-container-blur` | `.hextra-nav-container-blur` |
|
||||
| منوی همبرگر | `.hamburger-menu` | `.hextra-hamburger-menu` |
|
||||
| تغییر تم | `.theme-toggle` | `.hextra-theme-toggle` |
|
||||
| تغییر زبان | `.language-switcher` | `.hextra-language-switcher` |
|
||||
| ظرف نوار کناری | `.sidebar-container` | `.hextra-sidebar-container` |
|
||||
| مورد فعال نوار کناری | `.sidebar-active-item` | `.hextra-sidebar-active-item` |
|
||||
| نام فایل کد | `.filename` | `.hextra-code-filename` |
|
||||
| آیکون کپی | `.copy-icon` | `.hextra-copy-icon` |
|
||||
| آیکون موفقیت | `.success-icon` | `.hextra-success-icon` |
|
||||
| مراحل | `.steps` | `.hextra-steps` |
|
||||
|
||||
#### مدیریت داراییها برای KaTeX و Mermaid
|
||||
|
||||
**تأثیر**: سایتهایی که از KaTeX یا Mermaid استفاده میکنند
|
||||
|
||||
Hextra v0.10.0 اکنون داراییهای KaTeX و Mermaid را از CDN در زمان ساخت دانلود میکند.
|
||||
|
||||
**چه چیزی تغییر کرده است:**
|
||||
|
||||
- فرآیند ساخت اکنون نیاز به دسترسی به اینترنت برای دانلود این داراییها دارد
|
||||
- دیگر پس از ساخت، فراخوانی CDN خارجی برای این داراییها وجود ندارد
|
||||
|
||||
**اقدام مورد نیاز**:
|
||||
|
||||
- مطمئن شوید که محیط ساخت شما دسترسی به اینترنت برای دانلود داراییها دارد
|
||||
- سایتهای در محیطهای ایزوله ممکن است نیاز به پیشدانلود این داراییها و پیکربندی Hextra برای بارگیری آنها داشته باشند
|
||||
|
||||
#### Tailwind CSS v4
|
||||
|
||||
**تأثیر**: سایتهایی با CSS سفارشی گسترده که کلاسهای Tailwind Hextra `hx-*` را هدف قرار میدهند
|
||||
|
||||
در حالی که Hextra مهاجرت Tailwind CSS v4 را به صورت داخلی مدیریت میکند، سایتهایی با سفارشیسازیهای سنگین ممکن است نیاز به تنظیمات بیشتری داشته باشند.
|
||||
|
||||
**چه چیزی تغییر کرده است:**
|
||||
|
||||
- کامپایل CSS داخلی اکنون از Tailwind CSS v4.x استفاده میکند
|
||||
- کلاسهای ابزار اکنون با پیشوند `hx:` به جای `hx-` هستند
|
||||
|
||||
## مشارکتکنندگان
|
||||
|
||||
این انتشار با مشارکتهای 10 مشارکتکننده جدید ممکن شد:
|
||||
|
||||
- [@oosquare](https://github.com/oosquare) - فونتهای KaTeX، قلابهای رندر تصویر، بهبودهای مدیریت پیوند
|
||||
- [@Zabriskije](https://github.com/Zabriskije) - رفع اسکرول فانتوم
|
||||
- [@miniwater](https://github.com/miniwater) - مرکزسازی پاورقی سفارشی، بهبودهای متن alt تصویر
|
||||
- [@MattDodsonEnglish](https://github.com/MattDodsonEnglish) - کنترلهای نمایهسازی گوگل، مستندات OpenGraph
|
||||
- [@KStocky](https://github.com/KStocky) - ویژگی صفحهبندی معکوس
|
||||
- [@PrintN](https://github.com/PrintN) - اضافه شدن نمایش مستندات
|
||||
- [@hobobandy](https://github.com/hobobandy) - بهبودهای فاصله عنوان
|
||||
- [@dlwocks31](https://github.com/dlwocks31) - بهروزرسانی ترجمه کرهای
|
||||
- [@TwoAnts](https://github.com/TwoAnts) - رفع تغییر تم Giscus
|
||||
- [@ldez](https://github.com/ldez) - بهبودهای جستجو و رفع اشکالات
|
||||
|
||||
با تشکر ویژه از مشارکتکنندگان بازگشتی [@deining](https://github.com/deining) و [@yuri1969](https://github.com/yuri1969) برای حمایت مستمرشان در مستندات، ترجمهها و بهبودهای فنی.
|
||||
|
||||
**تغییرات کامل**: https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0
|
||||
@@ -0,0 +1,247 @@
|
||||
---
|
||||
title: "Hextra v0.10"
|
||||
date: 2025-08-14
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.10.0 は、新機能、アーキテクチャの刷新、利便性向上を詰め込んだ大きなリリースです。
|
||||
|
||||
<!--more-->
|
||||
|
||||
また、10名の[新規コントリビューター](#contributors)からの貢献と、長らく要望のあった機能の実装も含まれています。
|
||||
|
||||
## アップグレードガイド
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **破壊的変更**: このリリースにはいくつかの破壊的変更が含まれています。アップグレード前にチェックリストと[移行ガイド](#migration-guide)を確認してください。
|
||||
|
||||
v0.10.0 にアップグレードする前に、以下を確認してください:
|
||||
|
||||
- Hugo v0.146.0+ (extended 版) がインストールされていること
|
||||
- カスタムCSSのクラス名変更を確認 ( [CSSクラスプレフィックス変更](#css-class-prefix-changes) と [Tailwind CSS v4](#tailwind-css-v4) を参照)
|
||||
- LaTeX や Mermaid を使用する場合、ビルド環境がアセットダウンロードのためインターネットに接続できること
|
||||
|
||||
準備が整ったら、Hugoモジュールを更新します:
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra@v0.10.0
|
||||
```
|
||||
|
||||
## 新機能
|
||||
|
||||
このリリースの主な新機能は以下の通りです:
|
||||
|
||||
- [**ナビゲーションバーのドロップダウンメニューサポート**](#dropdown-menu-support-in-navbar): 階層型ナビゲーションメニューの作成
|
||||
- [**検索機能の強化**](#enhanced-search-experience): すべての見出しを対象にした精度向上した検索
|
||||
- [**llms.txt サポート**](#llmstxt-support): AI向けサイトアウトラインの生成
|
||||
- [**目次のスクロールハイライト**](#table-of-contents-scroll-highlighting): ページスクロール中の見出し自動ハイライト
|
||||
- [**タブの同期切り替え**](#synchronized-tab-switching): 複数のタブグループ間でのタブ選択の同期
|
||||
- [**ブログ一覧のページネーション**](#blog-list-pagination): ブログ一覧ページへのページネーションコントロール追加
|
||||
- [**MathJax サポート**](#mathjax-support): KaTeXに加えてMathJaxを数式レンダリングエンジンとして選択可能
|
||||
|
||||
### ナビゲーションバーのドロップダウンメニューサポート
|
||||
|
||||
ナビゲーションバーにドロップダウンメニューを作成し、ナビゲーション項目を整理できます。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: products
|
||||
name: "製品"
|
||||
- name: "製品A"
|
||||
parent: products
|
||||
url: "/product-a"
|
||||
- name: "製品B"
|
||||
parent: products
|
||||
url: "/product-b"
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 検索機能の強化
|
||||
|
||||
- **すべての見出しを検索**: ページタイトルだけでなく、すべてのレベルの見出しからコンテンツを検索
|
||||
- **検索結果の精度向上**: タイトル処理とリンク精度の改善
|
||||
- **結果ナビゲーションの修正**: 検索結果が正しいページセクションにリンクするようになりました
|
||||
|
||||
検索機能の強化に貢献してくださった [@ldez](https://github.com/ldez) に感謝します!
|
||||
|
||||
|
||||
|
||||
### llms.txt サポート
|
||||
|
||||
Hextra はサイトの [llms.txt](https://llmstxt.org/) 出力形式をサポートし、AIツールや言語モデルがコンテキストや参照のためにサイトをよりアクセスしやすくします。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
home: [html, llms]
|
||||
```
|
||||
|
||||
これにより、サイトのルートに `llms.txt` ファイルが生成されます。
|
||||
|
||||
|
||||
|
||||
### 目次のスクロールハイライト
|
||||
|
||||
ページをスクロールする際に、目次が現在のセクションを自動的にハイライトするようになり、ナビゲーションがより直感的になりました。
|
||||
|
||||
|
||||
|
||||
### タブの同期切り替え
|
||||
|
||||
同じ項目を持つタブはページ全体で同期されるようになりました。同期が有効な場合、タブを選択すると同じ項目リストを共有するすべてのタブグループが更新されます（選択内容は記憶されます）。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
tabs:
|
||||
sync: true
|
||||
```
|
||||
|
||||
### ブログ一覧のページネーション
|
||||
|
||||
ブログ一覧ページに基本的なページネーションコントロールが追加されました。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
blog:
|
||||
list:
|
||||
pagerSize: 20 # 1ページあたりの投稿数
|
||||
```
|
||||
|
||||
|
||||
|
||||
### MathJax サポート
|
||||
|
||||
デフォルトのKaTeXサポートに加えて、[MathJax](https://www.mathjax.org/) で数式をレンダリングできるようになりました。ニーズに合ったエンジンを選択できます。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: "mathjax" # デフォルトは "katex"
|
||||
```
|
||||
|
||||
## 技術的改善
|
||||
|
||||
### フレームワークとビルドシステム
|
||||
|
||||
- **Tailwind CSS v4 移行**: [Tailwind CSS v4](https://tailwindcss.com/blog/tailwindcss-v4) への完全移行とカスタマイズサポートの改善
|
||||
- **Hugoテンプレートシステム**: Hugoの[新しいテンプレートシステム](https://gohugo.io/templates/new-templatesystem-overview/) (v0.146.0+) への対応
|
||||
- **数式のサーバーサイドレンダリング**: Hugoネイティブレンダリングを使用した数式レンダリングの改善
|
||||
- **FlexSearch 0.8 アップグレード**: 検索エンジン [FlexSearch](https://github.com/nextapps-de/flexsearch) のアップグレードにより、CJK (中国語、日本語、韓国語) コンテンツのエンコーディング改善と高速化・精度向上
|
||||
- **アセット管理の強化**: KaTeXとMermaidアセットのCDNまたはローカルからの読み込みサポート
|
||||
|
||||
## 利便性の向上
|
||||
|
||||
- **動的ファビコン切り替え**: カラースキーム設定に基づくファビコンの自動更新
|
||||
- **逆順ページネーション**: ページフロントマターで `reversePagination` を設定可能に
|
||||
- **Googleインデックス制御**: Googleのインデックスをブロックする新しいページパラメータ
|
||||
- **幅の処理改善**: CSS変数によるレスポンシブデザイン制御の強化
|
||||
- **スタイリング改善**: Markdownテーブルと水平線のモダンなスタイル
|
||||
|
||||
## バグ修正と安定性
|
||||
|
||||
- **Giscusテーマ同期**: コメントがダーク/ライトモードの切り替えに正しく追従
|
||||
- **検索結果の精度**: 検索結果のリンク問題とタイトルエスケープの修正
|
||||
- **タブ切り替え**: 非同期タブモードでのナビゲーション問題の解決
|
||||
- **ファントムスクロール**: フッター無効時の不要なスクロール動作の修正
|
||||
- **画像アクセシビリティ**: 重複したaltテキストレンダリングの防止
|
||||
- **リンクレンダリング**: 複雑なサイト構造におけるベースURL処理の改善
|
||||
|
||||
---
|
||||
|
||||
## 移行ガイド
|
||||
|
||||
- [**Hugoバージョン要件**](#hugo-version-requirements): Hugo v0.146.0+ (extended版) が必要
|
||||
- [**CSSクラスプレフィックス変更**](#css-class-prefix-changes): コンポーネントCSSクラスに一貫した `hextra-` プレフィックスを採用
|
||||
- [**アセット管理**](#asset-management-for-katex-and-mermaid): KaTeXとMermaidアセットはビルド時にダウンロード
|
||||
- [**Tailwind CSS v4**](#tailwind-css-v4): 内部CSSコンパイルにTailwind CSS v4.xを採用し `hx:` プレフィックスを使用
|
||||
|
||||
#### Hugoバージョン要件
|
||||
|
||||
**影響**: 古いHugoバージョンで動作しているサイト
|
||||
|
||||
Hextra v0.10.0 は新しいテンプレートシステムを採用しているため、Hugo v0.146.0以降 (extended版) が必要です。
|
||||
|
||||
**必要な対応**: Hextraをアップグレードする前にHugoをv0.146.0+に更新
|
||||
|
||||
#### CSSクラスプレフィックス変更
|
||||
|
||||
**影響**: HextraコンポーネントクラスをターゲットにしたカスタムCSSがあるサイト
|
||||
|
||||
Hextra v0.10.0 では、メンテナンス性向上とユーザースタイルとの衝突防止のため、ほとんどのコンポーネントCSSクラスに一貫した `hextra-` プレフィックスを導入しました。
|
||||
|
||||
**必要な対応**: HextraコンポーネントをターゲットにしたカスタムCSSがある場合、以下のクラス名を更新してください:
|
||||
|
||||
| 領域 | 変更前 | 変更後 |
|
||||
| -------------------- | ---------------------------- | ------------------------------------------------- |
|
||||
| 検索 (コンテナ) | `.search-wrapper` | `.hextra-search-wrapper` |
|
||||
| 検索 (入力) | `.search-input` | `.hextra-search-input` |
|
||||
| 検索 (結果) | `.search-results` | `.hextra-search-results` |
|
||||
| 検索 (タイトル) | `.search-wrapper .title` | `.hextra-search-wrapper .hextra-search-title` |
|
||||
| 検索 (アクティブ項目)| `.search-wrapper .active` | `.hextra-search-wrapper .hextra-search-active` |
|
||||
| 検索 (結果なし) | `.search-wrapper .no-result` | `.hextra-search-wrapper .hextra-search-no-result` |
|
||||
| 検索 (プレフィックス)| `.search-wrapper .prefix` | `.hextra-search-wrapper .hextra-search-prefix` |
|
||||
| 検索 (抜粋) | `.search-wrapper .excerpt` | `.hextra-search-wrapper .hextra-search-excerpt` |
|
||||
| 検索 (マッチ) | `.search-wrapper .match` | `.hextra-search-wrapper .hextra-search-match` |
|
||||
| ナビバーブラー | `.nav-container-blur` | `.hextra-nav-container-blur` |
|
||||
| ハンバーガーメニュー | `.hamburger-menu` | `.hextra-hamburger-menu` |
|
||||
| テーマトグル | `.theme-toggle` | `.hextra-theme-toggle` |
|
||||
| 言語スイッチャー | `.language-switcher` | `.hextra-language-switcher` |
|
||||
| サイドバーコンテナ | `.sidebar-container` | `.hextra-sidebar-container` |
|
||||
| サイドバーアクティブ項目 | `.sidebar-active-item` | `.hextra-sidebar-active-item` |
|
||||
| コードファイル名 | `.filename` | `.hextra-code-filename` |
|
||||
| コピーアイコン | `.copy-icon` | `.hextra-copy-icon` |
|
||||
| 成功アイコン | `.success-icon` | `.hextra-success-icon` |
|
||||
| ステップ | `.steps` | `.hextra-steps` |
|
||||
|
||||
#### KaTeXとMermaidのアセット管理
|
||||
|
||||
**影響**: KaTeXまたはMermaidを使用しているサイト
|
||||
|
||||
Hextra v0.10.0 では、KaTeXとMermaidアセットをビルド時にCDNからダウンロードするようになりました。
|
||||
|
||||
**変更点:**
|
||||
|
||||
- これらのアセットをダウンロードするため、ビルドプロセスでインターネットアクセスが必要
|
||||
- ビルド後はこれらのアセットに対する外部CDN呼び出しが不要
|
||||
|
||||
**必要な対応**:
|
||||
|
||||
- アセットをダウンロードするため、ビルド環境がインターネットに接続できることを確認
|
||||
- エアギャップ環境のサイトでは、これらのアセットを事前にダウンロードし、Hextraがそれらを読み込むように設定する必要がある場合があります
|
||||
|
||||
#### Tailwind CSS v4
|
||||
|
||||
**影響**: HextraのTailwindクラス `hx-*` を広範囲にカスタマイズしているサイト
|
||||
|
||||
HextraはTailwind CSS v4移行を内部で処理しますが、高度にカスタマイズされたサイトでは追加の調整が必要な場合があります。
|
||||
|
||||
**変更点:**
|
||||
|
||||
- 内部CSSコンパイルにTailwind CSS v4.xを使用
|
||||
- ユーティリティクラスのプレフィックスが `hx-` から `hx:` に変更
|
||||
|
||||
## コントリビューター
|
||||
|
||||
このリリースは、10名の新規コントリビューターの貢献によって実現されました:
|
||||
|
||||
- [@oosquare](https://github.com/oosquare) - KaTeXフォント、画像レンダーフック、リンク処理の改善
|
||||
- [@Zabriskije](https://github.com/Zabriskije) - ファントムスクロールの修正
|
||||
- [@miniwater](https://github.com/miniwater) - カスタムフッターの中央揃え、画像altテキストの改善
|
||||
- [@MattDodsonEnglish](https://github.com/MattDodsonEnglish) - Googleインデックス制御、OpenGraphドキュメント
|
||||
- [@KStocky](https://github.com/KStocky) - 逆順ページネーション機能
|
||||
- [@PrintN](https://github.com/PrintN) - ドキュメントショーケースの追加
|
||||
- [@hobobandy](https://github.com/hobobandy) - タイトル間隔の改善
|
||||
- [@dlwocks31](https://github.com/dlwocks31) - 韓国語翻訳の更新
|
||||
- [@TwoAnts](https://github.com/TwoAnts) - Giscusテーマ切り替えの修正
|
||||
- [@ldez](https://github.com/ldez) - 検索機能の改善とバグ修正
|
||||
|
||||
継続的なサポート、ドキュメント、翻訳、技術的改善を提供してくださった [@deining](https://github.com/deining) と [@yuri1969](https://github.com/yuri1969) にも感謝します。
|
||||
|
||||
**完全な変更履歴**: https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0
|
||||
@@ -0,0 +1,247 @@
|
||||
---
|
||||
title: "Hextra v0.10"
|
||||
date: 2025-08-14
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.10.0 is a big release packed with new capabilities, architectural upgrades, and quality-of-life improvements.
|
||||
|
||||
<!--more-->
|
||||
|
||||
It also includes contributions from 10 [new contributors](#contributors) and addresses long-standing community requests.
|
||||
|
||||
## Upgrade Guide
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Breaking Changes**: This release includes several breaking changes. Please review the checklist and the [Migration Guide](#migration-guide) before upgrading.
|
||||
|
||||
Before upgrading to v0.10.0, ensure that you have:
|
||||
|
||||
- Hugo v0.146.0+ (extended version) installed
|
||||
- Reviewed custom CSS for class name changes (see [CSS Class Prefix Changes](#css-class-prefix-changes) and [Tailwind CSS v4](#tailwind-css-v4))
|
||||
- Verified that build environment has internet access for asset downloads when LaTeX and/or Mermaid is used
|
||||
|
||||
Once ready, update the Hugo module:
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra@v0.10.0
|
||||
```
|
||||
|
||||
## New Features
|
||||
|
||||
Here is a list of notable new features in this release:
|
||||
|
||||
- [**Dropdown Menu Support in Navbar**](#dropdown-menu-support-in-navbar): create hierarchical navigation menus
|
||||
- [**Enhanced Search Experience**](#enhanced-search-experience): improved search across all headings with better accuracy
|
||||
- [**llms.txt Support**](#llmstxt-support): generate AI-friendly site outline
|
||||
- [**Table of Contents Scroll Highlighting**](#table-of-contents-scroll-highlighting): automatic heading highlighting during page scroll
|
||||
- [**Synchronized Tab Switching**](#synchronized-tab-switching): synchronize tab selections across multiple tab groups
|
||||
- [**Blog List Pagination**](#blog-list-pagination): add pagination controls to blog listing pages
|
||||
- [**MathJax Support**](#mathjax-support): alternative math rendering engine alongside KaTeX
|
||||
|
||||
### Dropdown Menu Support in Navbar
|
||||
|
||||
Create dropdown menus in your navigation bar for better navigation items organization.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: products
|
||||
name: "Products"
|
||||
- name: "Product A"
|
||||
parent: products
|
||||
url: "/product-a"
|
||||
- name: "Product B"
|
||||
parent: products
|
||||
url: "/product-b"
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Enhanced Search Experience
|
||||
|
||||
- **Search in all headings**: find content across all heading levels, not just page titles
|
||||
- **Improved result accuracy**: better title handling and linking precision
|
||||
- **Fixed result navigation**: search results now link to the correct page sections
|
||||
|
||||
Huge thanks to [@ldez](https://github.com/ldez) for pushing the search capabilities forward!
|
||||
|
||||
|
||||
|
||||
### llms.txt Support
|
||||
|
||||
Hextra now supports [llms.txt](https://llmstxt.org/) output format for your site, making your site more accessible to AI tools and language models for context and reference.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
home: [html, llms]
|
||||
```
|
||||
|
||||
This will generate an `llms.txt` file at your site's root.
|
||||
|
||||
|
||||
|
||||
### Table of Contents Scroll Highlighting
|
||||
|
||||
The table of contents now automatically highlights the current section as you scroll through the page, making navigation more intuitive.
|
||||
|
||||
|
||||
|
||||
### Synchronized Tab Switching
|
||||
|
||||
Tabs with the same items now synchronize across the page. When sync is enabled, selecting a tab updates all tab groups that share the same items list (and your selection is remembered).
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
tabs:
|
||||
sync: true
|
||||
```
|
||||
|
||||
### Blog List Pagination
|
||||
|
||||
Basic pagination controls have been added to blog listing pages.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
blog:
|
||||
list:
|
||||
pagerSize: 20 # Posts per page
|
||||
```
|
||||
|
||||
|
||||
|
||||
### MathJax Support
|
||||
|
||||
Render mathematical expressions with [MathJax](https://www.mathjax.org/) alongside the default KaTeX support. Choose the engine that best fits your needs.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: "mathjax" # default is "katex"
|
||||
```
|
||||
|
||||
## Technical Improvements
|
||||
|
||||
### Framework and Build System
|
||||
|
||||
- **Tailwind CSS v4 Migration**: complete migration to [Tailwind CSS v4](https://tailwindcss.com/blog/tailwindcss-v4) with improved customization support.
|
||||
- **Hugo Template System**: adapted to Hugo's [new template system](https://gohugo.io/templates/new-templatesystem-overview/) (v0.146.0+) for future compatibility.
|
||||
- **Math Server-Side Rendering**: better handling of math equation rendering using Hugo native rendering by default.
|
||||
- **FlexSearch 0.8 Upgrade**: upgraded search engine [FlexSearch](https://github.com/nextapps-de/flexsearch) for faster, more accurate results with improved CJK (Chinese, Japanese, Korean) content encoding.
|
||||
- **Enhanced Asset Management**: KaTeX and Mermaid assets support loading from CDN or local
|
||||
|
||||
## Quality of Life Improvements
|
||||
|
||||
- **Dynamic favicon switching**: automatic favicon updates based on color scheme preferences
|
||||
- **Reverse pagination**: authors can now set `reversePagination` in page front matter
|
||||
- **Google indexing control**: new page parameter to block Google indexing when needed
|
||||
- **Width handling improvements**: better responsive design controls via CSS variables
|
||||
- **Styling improvements**: modern styles for Markdown table and horizontal line
|
||||
|
||||
## Bug Fixes and Stability
|
||||
|
||||
- **Giscus theme synchronization**: comments now properly follow dark/light mode switches
|
||||
- **Search result accuracy**: fixed linking issues and title escaping in search results
|
||||
- **Tab switching**: resolved navigation issues in non-synced tab mode
|
||||
- **Phantom scrolling**: fixed unwanted scroll behavior when footer is disabled
|
||||
- **Image accessibility**: prevented duplicate alt text rendering
|
||||
- **Link rendering**: improved base URL handling for complex site structures
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide
|
||||
|
||||
- [**Hugo Version Requirements**](#hugo-version-requirements): Requires Hugo v0.146.0+ (extended version)
|
||||
- [**CSS Class Prefix Changes**](#css-class-prefix-changes): Component CSS classes now use consistent `hextra-` prefixing
|
||||
- [**Asset Management**](#asset-management-for-katex-and-mermaid): KaTeX and Mermaid assets now download during build time
|
||||
- [**Tailwind CSS v4**](#tailwind-css-v4): Internal CSS compilation now uses Tailwind CSS v4.x with `hx:` prefix
|
||||
|
||||
#### Hugo Version Requirements
|
||||
|
||||
**Impact**: Sites running older Hugo versions
|
||||
|
||||
Hextra v0.10.0 requires Hugo v0.146.0 or later (extended version) due to the new template system adoption.
|
||||
|
||||
**Action required**: Update Hugo to v0.146.0+ before upgrading Hextra
|
||||
|
||||
#### CSS Class Prefix Changes
|
||||
|
||||
**Impact**: Sites with custom CSS targeting Hextra component classes
|
||||
|
||||
Hextra v0.10.0 introduces consistent `hextra-` prefixing for majority of component CSS classes to improve maintainability and prevent conflicts with user styles.
|
||||
|
||||
**Action required**: If you have custom CSS targeting Hextra components, update the following class names:
|
||||
|
||||
| Area | Before | After |
|
||||
| -------------------- | ---------------------------- | ------------------------------------------------- |
|
||||
| Search (container) | `.search-wrapper` | `.hextra-search-wrapper` |
|
||||
| Search (input) | `.search-input` | `.hextra-search-input` |
|
||||
| Search (results) | `.search-results` | `.hextra-search-results` |
|
||||
| Search (title) | `.search-wrapper .title` | `.hextra-search-wrapper .hextra-search-title` |
|
||||
| Search (active item) | `.search-wrapper .active` | `.hextra-search-wrapper .hextra-search-active` |
|
||||
| Search (no result) | `.search-wrapper .no-result` | `.hextra-search-wrapper .hextra-search-no-result` |
|
||||
| Search (prefix) | `.search-wrapper .prefix` | `.hextra-search-wrapper .hextra-search-prefix` |
|
||||
| Search (excerpt) | `.search-wrapper .excerpt` | `.hextra-search-wrapper .hextra-search-excerpt` |
|
||||
| Search (match) | `.search-wrapper .match` | `.hextra-search-wrapper .hextra-search-match` |
|
||||
| Navbar blur | `.nav-container-blur` | `.hextra-nav-container-blur` |
|
||||
| Hamburger menu | `.hamburger-menu` | `.hextra-hamburger-menu` |
|
||||
| Theme toggle | `.theme-toggle` | `.hextra-theme-toggle` |
|
||||
| Language switcher | `.language-switcher` | `.hextra-language-switcher` |
|
||||
| Sidebar container | `.sidebar-container` | `.hextra-sidebar-container` |
|
||||
| Sidebar active item | `.sidebar-active-item` | `.hextra-sidebar-active-item` |
|
||||
| Code filename | `.filename` | `.hextra-code-filename` |
|
||||
| Copy icon | `.copy-icon` | `.hextra-copy-icon` |
|
||||
| Success icon | `.success-icon` | `.hextra-success-icon` |
|
||||
| Steps | `.steps` | `.hextra-steps` |
|
||||
|
||||
#### Asset Management for KaTeX and Mermaid
|
||||
|
||||
**Impact**: Sites using KaTeX or Mermaid
|
||||
|
||||
Hextra v0.10.0 now downloads KaTeX and Mermaid assets from CDN during build time.
|
||||
|
||||
**What's changed:**
|
||||
|
||||
- Build process now requires internet access to download these assets
|
||||
- No more external CDN calls for these assets after build
|
||||
|
||||
**Action required**:
|
||||
|
||||
- Ensure your build environment has internet access to download assets
|
||||
- Sites in air-gapped environments may need to pre-download these assets and configure Hextra to load them
|
||||
|
||||
#### Tailwind CSS v4
|
||||
|
||||
**Impact**: Sites with extensive custom CSS targeting Hextra Tailwind classes `hx-*`
|
||||
|
||||
While Hextra handles the Tailwind CSS v4 migration internally, sites with heavy customizations may need further adjustments.
|
||||
|
||||
**What's changed:**
|
||||
|
||||
- Internal CSS compilation now uses Tailwind CSS v4.x
|
||||
- Utility classes now prefix with `hx:` rather than `hx-`
|
||||
|
||||
## Contributors
|
||||
|
||||
This release was made possible by contributions from 10 new contributors:
|
||||
|
||||
- [@oosquare](https://github.com/oosquare) - KaTeX fonts, image render hooks, link handling improvements
|
||||
- [@Zabriskije](https://github.com/Zabriskije) - Phantom scroll fix
|
||||
- [@miniwater](https://github.com/miniwater) - Custom footer centering, image alt text improvements
|
||||
- [@MattDodsonEnglish](https://github.com/MattDodsonEnglish) - Google indexing controls, OpenGraph documentation
|
||||
- [@KStocky](https://github.com/KStocky) - Reverse pagination feature
|
||||
- [@PrintN](https://github.com/PrintN) - Documentation showcase additions
|
||||
- [@hobobandy](https://github.com/hobobandy) - Title spacing improvements
|
||||
- [@dlwocks31](https://github.com/dlwocks31) - Korean translation updates
|
||||
- [@TwoAnts](https://github.com/TwoAnts) - Giscus theme switching fix
|
||||
- [@ldez](https://github.com/ldez) - Search improvements and bug fixes
|
||||
|
||||
Additional thanks to returning contributors [@deining](https://github.com/deining) and [@yuri1969](https://github.com/yuri1969) for their continued support with documentation, translations, and technical improvements.
|
||||
|
||||
**Full Changelog**: https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0
|
||||
@@ -0,0 +1,247 @@
|
||||
---
|
||||
title: "Hextra v0.10"
|
||||
date: 2025-08-14
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.10.0 是一个重大版本更新，包含多项新功能、架构升级和使用体验优化。
|
||||
|
||||
<!--more-->
|
||||
|
||||
本次更新还包含了来自 10 位 [新贡献者](#contributors) 的代码提交，并解决了社区长期期待的功能需求。
|
||||
|
||||
## 升级指南
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **破坏性变更**：此版本包含多项不兼容改动。升级前请仔细阅读检查清单和 [迁移指南](#migration-guide)。
|
||||
|
||||
升级至 v0.10.0 前，请确保：
|
||||
|
||||
- 已安装 Hugo v0.146.0+（扩展版）
|
||||
- 检查自定义 CSS 的类名变更（参见 [CSS 类前缀变更](#css-class-prefix-changes) 和 [Tailwind CSS v4](#tailwind-css-v4)）
|
||||
- 确认构建环境可访问互联网以下载 LaTeX 和/或 Mermaid 资源
|
||||
|
||||
准备就绪后，更新 Hugo 模块：
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra@v0.10.0
|
||||
```
|
||||
|
||||
## 新功能
|
||||
|
||||
以下是本版本值得关注的新特性：
|
||||
|
||||
- [**导航栏下拉菜单支持**](#dropdown-menu-support-in-navbar)：创建层级导航菜单
|
||||
- [**增强搜索体验**](#enhanced-search-experience)：改进全标题搜索精度
|
||||
- [**llms.txt 支持**](#llmstxt-support)：生成 AI 友好的站点大纲
|
||||
- [**目录滚动高亮**](#table-of-contents-scroll-highlighting)：滚动时自动高亮当前章节
|
||||
- [**同步标签页切换**](#synchronized-tab-switching)：跨多组标签页同步选择状态
|
||||
- [**博客列表分页**](#blog-list-pagination)：为博客列表添加分页控件
|
||||
- [**MathJax 支持**](#mathjax-support)：在 KaTeX 外新增数学公式渲染引擎
|
||||
|
||||
### 导航栏下拉菜单支持
|
||||
|
||||
在导航栏中创建下拉菜单，优化导航项组织方式。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: products
|
||||
name: "产品"
|
||||
- name: "产品A"
|
||||
parent: products
|
||||
url: "/product-a"
|
||||
- name: "产品B"
|
||||
parent: products
|
||||
url: "/product-b"
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 增强搜索体验
|
||||
|
||||
- **全标题搜索**：可搜索所有层级标题内容，不限于页面标题
|
||||
- **提升结果精度**：改进标题处理和链接准确性
|
||||
- **修复结果导航**：搜索结果现在能正确跳转到对应章节
|
||||
|
||||
特别感谢 [@ldez](https://github.com/ldez) 推动搜索功能升级！
|
||||
|
||||
|
||||
|
||||
### llms.txt 支持
|
||||
|
||||
现支持生成 [llms.txt](https://llmstxt.org/) 格式输出，使站点内容更便于 AI 工具和语言模型获取上下文参考。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
home: [html, llms]
|
||||
```
|
||||
|
||||
这将在站点根目录生成 `llms.txt` 文件。
|
||||
|
||||
|
||||
|
||||
### 目录滚动高亮
|
||||
|
||||
滚动页面时，目录会自动高亮当前章节，使导航更加直观。
|
||||
|
||||
|
||||
|
||||
### 同步标签页切换
|
||||
|
||||
相同内容的标签页现在支持跨组同步。启用同步后，选择某个标签会更新所有包含相同项目的标签组（且会记住选择状态）。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
tabs:
|
||||
sync: true
|
||||
```
|
||||
|
||||
### 博客列表分页
|
||||
|
||||
为博客列表页面添加基础分页控件。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
blog:
|
||||
list:
|
||||
pagerSize: 20 # 每页文章数
|
||||
```
|
||||
|
||||
|
||||
|
||||
### MathJax 支持
|
||||
|
||||
除默认的 KaTeX 外，新增 [MathJax](https://www.mathjax.org/) 数学公式渲染引擎支持，可按需选择。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: "mathjax" # 默认为 "katex"
|
||||
```
|
||||
|
||||
## 技术改进
|
||||
|
||||
### 框架与构建系统
|
||||
|
||||
- **Tailwind CSS v4 迁移**：完整迁移至 [Tailwind CSS v4](https://tailwindcss.com/blog/tailwindcss-v4)，提供更好的定制支持
|
||||
- **Hugo 模板系统**：适配 Hugo [新版模板系统](https://gohugo.io/templates/new-templatesystem-overview/)（v0.146.0+）以确保未来兼容性
|
||||
- **数学公式服务端渲染**：默认使用 Hugo 原生渲染改进数学公式处理
|
||||
- **FlexSearch 0.8 升级**：搜索引擎升级至 [FlexSearch](https://github.com/nextapps-de/flexsearch) 0.8，提升 CJK（中日韩）内容编码处理能力
|
||||
- **增强资源管理**：KaTeX 和 Mermaid 资源支持从 CDN 或本地加载
|
||||
|
||||
## 使用体验优化
|
||||
|
||||
- **动态 favicon 切换**：根据色彩偏好自动更新网站图标
|
||||
- **反向分页**：支持通过页面 front matter 设置 `reversePagination`
|
||||
- **Google 索引控制**：新增页面参数控制是否允许 Google 索引
|
||||
- **宽度处理改进**：通过 CSS 变量优化响应式设计控制
|
||||
- **样式改进**：现代化 Markdown 表格和水平线样式
|
||||
|
||||
## 错误修复与稳定性
|
||||
|
||||
- **Giscus 主题同步**：评论模块现在正确跟随暗黑/明亮模式切换
|
||||
- **搜索结果准确性**：修复搜索结果链接和标题转义问题
|
||||
- **标签页切换**：解决非同步模式下的导航问题
|
||||
- **幽灵滚动**：修复禁用页脚时出现的异常滚动行为
|
||||
- **图片可访问性**：避免重复渲染 alt 文本
|
||||
- **链接渲染**：改进复杂站点结构下的基础 URL 处理
|
||||
|
||||
---
|
||||
|
||||
## 迁移指南
|
||||
|
||||
- [**Hugo 版本要求**](#hugo-version-requirements)：需 Hugo v0.146.0+（扩展版）
|
||||
- [**CSS 类前缀变更**](#css-class-prefix-changes)：组件 CSS 类现统一使用 `hextra-` 前缀
|
||||
- [**资源管理**](#asset-management-for-katex-and-mermaid)：KaTeX 和 Mermaid 资源改为构建时下载
|
||||
- [**Tailwind CSS v4**](#tailwind-css-v4)：内部 CSS 编译现使用 Tailwind CSS v4.x 并采用 `hx:` 前缀
|
||||
|
||||
#### Hugo 版本要求
|
||||
|
||||
**影响**：使用旧版 Hugo 的站点
|
||||
|
||||
Hextra v0.10.0 因采用新模板系统，要求 Hugo v0.146.0 或更高版本（扩展版）。
|
||||
|
||||
**需执行操作**：升级 Hextra 前先更新 Hugo 至 v0.146.0+
|
||||
|
||||
#### CSS 类前缀变更
|
||||
|
||||
**影响**：自定义 CSS 中引用了 Hextra 组件类的站点
|
||||
|
||||
v0.10.0 为大多数组件 CSS 类引入统一的 `hextra-` 前缀，以提高可维护性并避免与用户样式冲突。
|
||||
|
||||
**需执行操作**：如果自定义 CSS 中引用了 Hextra 组件，请更新以下类名：
|
||||
|
||||
| 区域 | 旧类名 | 新类名 |
|
||||
| -------------------- | -------------------------- | ----------------------------------------------- |
|
||||
| 搜索（容器） | `.search-wrapper` | `.hextra-search-wrapper` |
|
||||
| 搜索（输入框） | `.search-input` | `.hextra-search-input` |
|
||||
| 搜索（结果） | `.search-results` | `.hextra-search-results` |
|
||||
| 搜索（标题） | `.search-wrapper .title` | `.hextra-search-wrapper .hextra-search-title` |
|
||||
| 搜索（活动项） | `.search-wrapper .active` | `.hextra-search-wrapper .hextra-search-active` |
|
||||
| 搜索（无结果） | `.search-wrapper .no-result` | `.hextra-search-wrapper .hextra-search-no-result` |
|
||||
| 搜索（前缀） | `.search-wrapper .prefix` | `.hextra-search-wrapper .hextra-search-prefix` |
|
||||
| 搜索（摘要） | `.search-wrapper .excerpt` | `.hextra-search-wrapper .hextra-search-excerpt` |
|
||||
| 搜索（匹配项） | `.search-wrapper .match` | `.hextra-search-wrapper .hextra-search-match` |
|
||||
| 导航栏模糊效果 | `.nav-container-blur` | `.hextra-nav-container-blur` |
|
||||
| 汉堡菜单 | `.hamburger-menu` | `.hextra-hamburger-menu` |
|
||||
| 主题切换 | `.theme-toggle` | `.hextra-theme-toggle` |
|
||||
| 语言切换器 | `.language-switcher` | `.hextra-language-switcher` |
|
||||
| 侧边栏容器 | `.sidebar-container` | `.hextra-sidebar-container` |
|
||||
| 侧边栏活动项 | `.sidebar-active-item` | `.hextra-sidebar-active-item` |
|
||||
| 代码文件名 | `.filename` | `.hextra-code-filename` |
|
||||
| 复制图标 | `.copy-icon` | `.hextra-copy-icon` |
|
||||
| 成功图标 | `.success-icon` | `.hextra-success-icon` |
|
||||
| 步骤组件 | `.steps` | `.hextra-steps` |
|
||||
|
||||
#### KaTeX 和 Mermaid 资源管理
|
||||
|
||||
**影响**：使用 KaTeX 或 Mermaid 的站点
|
||||
|
||||
v0.10.0 改为在构建时从 CDN 下载 KaTeX 和 Mermaid 资源。
|
||||
|
||||
**变更内容：**
|
||||
|
||||
- 构建过程需要联网下载这些资源
|
||||
- 构建后不再需要外部 CDN 调用
|
||||
|
||||
**需执行操作：**
|
||||
|
||||
- 确保构建环境可访问互联网以下载资源
|
||||
- 隔离环境中的站点需预下载资源并配置 Hextra 加载路径
|
||||
|
||||
#### Tailwind CSS v4
|
||||
|
||||
**影响**：大量自定义 CSS 引用了 `hx-*` 类名的站点
|
||||
|
||||
虽然 Hextra 内部已处理 Tailwind CSS v4 迁移，但深度定制的站点可能需要额外调整。
|
||||
|
||||
**变更内容：**
|
||||
|
||||
- 内部 CSS 编译使用 Tailwind CSS v4.x
|
||||
- 工具类前缀改为 `hx:` 而非 `hx-`
|
||||
|
||||
## 贡献者
|
||||
|
||||
本次发布得益于 10 位新贡献者的代码提交：
|
||||
|
||||
- [@oosquare](https://github.com/oosquare) - KaTeX 字体、图片渲染钩子、链接处理改进
|
||||
- [@Zabriskije](https://github.com/Zabriskije) - 修复幽灵滚动问题
|
||||
- [@miniwater](https://github.com/miniwater) - 自定义页脚居中、图片 alt 文本优化
|
||||
- [@MattDodsonEnglish](https://github.com/MattDodsonEnglish) - Google 索引控制、OpenGraph 文档
|
||||
- [@KStocky](https://github.com/KStocky) - 反向分页功能
|
||||
- [@PrintN](https://github.com/PrintN) - 文档展示增强
|
||||
- [@hobobandy](https://github.com/hobobandy) - 标题间距优化
|
||||
- [@dlwocks31](https://github.com/dlwocks31) - 韩语翻译更新
|
||||
- [@TwoAnts](https://github.com/TwoAnts) - 修复 Giscus 主题切换
|
||||
- [@ldez](https://github.com/ldez) - 搜索功能改进与错误修复
|
||||
|
||||
同时感谢长期贡献者 [@deining](https://github.com/deining) 和 [@yuri1969](https://github.com/yuri1969) 在文档、翻译和技术改进方面的持续支持。
|
||||
|
||||
**完整更新日志**：https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: "Hextra v0.11"
|
||||
date: 2025-08-30
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- انتشار
|
||||
---
|
||||
|
||||
Hextra v0.11.0 بر صیقل UX و مؤلفههای جدید کاربردی تمرکز دارد: بنر سراسری سایت، کالاوتها و بجهای بهبودیافته، کارتهای غنیتر، یکپارچهسازی تحلیلگرها، و چند بهبود ناوبری. همچنین شامل رفع اشکالات پایداری و بهروزرسانیهای مستندات است.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## راهنمای ارتقا
|
||||
|
||||
برای بیشتر سایتها تغییر شکستآمیزی وجود ندارد. با استفاده از [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) بهروزرسانی کنید:
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
## نکات برجسته
|
||||
|
||||
- مؤلفه بنر بالایی برای اعلانها
|
||||
- بازطراحی کالاوتها با سبکهای شفافتر
|
||||
- پشتیبانی از تحلیلگرهای Umami و Matomo
|
||||
- شورتکد Asciinema برای ضبطهای ترمینال
|
||||
- گزینهٔ تزئین پیوندهای خارجی
|
||||
- مسیر راهنما برای صفحات تکی (غیرِ مستندات/غیرِ وبلاگ)
|
||||
- بهبودهای نوار ناوبری: مورد پیوند با آیکون و جایگذاری بهتر
|
||||
- سفارشیسازی بهتر بجها و کارتها
|
||||
- کلید تغییر تم از گزینه «System» پشتیبانی میکند
|
||||
|
||||
## ویژگیهای جدید
|
||||
|
||||
### بنر بالایی
|
||||
|
||||
یک بنر سراسری و قابلِ بستن برای اعلانها، لانچها یا پیامهای وضعیت اضافه کنید.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
banner:
|
||||
key: "announcement"
|
||||
message: Welcome!
|
||||
```
|
||||
|
||||
|
||||
|
||||
### بازطراحی Callout
|
||||
|
||||
[Callout]({{% relref "docs/guide/shortcodes/callout" %}}) برای خوانایی بهتر و تأکید مناسب در تمام تمها بازطراحی شده است.
|
||||
|
||||
|
||||
|
||||
### تحلیلگرها: Umami و Matomo
|
||||
|
||||
پیکربندی داخلی برای فراهمکنندگان تحلیلگر:
|
||||
- [Umami]({{% relref "docs/guide/configuration.md#umami-analytics" %}})
|
||||
- [Matomo]({{% relref "docs/guide/configuration.md#matomo-analytics" %}})
|
||||
|
||||
### شورتکد Asciinema
|
||||
|
||||
با استفاده از [Asciinema](https://www.asciinema.org/) و [شورتکد Asciinema]({{% relref "docs/guide/shortcodes/asciinema.md" %}}) ضبطهای ترمینال را درونگذاری کنید.
|
||||
|
||||
```md
|
||||
{{</* asciinema id="123456" autoplay=true loop=true */>}}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### بهبودهای نوار ناوبری
|
||||
|
||||
- پشتیبانی از آیکون برای موارد پیوند در نوار ناوبری
|
||||
- بهبود موقعیت منو برای هماهنگی با سوییچر زبان و سایر موارد
|
||||
|
||||
|
||||
|
||||
قابل ذکر است، نسخه [0.10.2](https://github.com/imfing/hextra/releases/tag/v0.10.2) امکان افزودن سوییچر زبان و کلید تغییر تم به نوار ناوبری را فراهم میکند.
|
||||
|
||||
### تزئین پیوند خارجی
|
||||
|
||||
بهصورت اختیاری یک تزئین ظریفِ «پیوند خارجی» به پیوندهای خروجی اضافه کنید.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
externalLinkDecoration: true
|
||||
```
|
||||
|
||||
### فعالسازی مسیر راهنما
|
||||
|
||||
با قرار دادن `breadcrumbs: true` در فرانتمتر، مسیر راهنما را روی صفحات تکی (غیرِ مستندات/وبلاگ) فعال کنید.
|
||||
|
||||
```yaml {filename="content/about.md"}
|
||||
---
|
||||
title: About
|
||||
breadcrumbs: true
|
||||
---
|
||||
```
|
||||
|
||||
### بهبود کارتها و بجها
|
||||
|
||||
- [کارتها]({{% relref "docs/guide/shortcodes/cards.md" %}}): گزینههای جدید `tagIcon` و `tagBorder`.
|
||||
- [بجها]({{% relref "docs/guide/shortcodes/others.md" %}}): رنگها و سبکهای حاشیهٔ جدید.
|
||||
|
||||
## بهبودهای کیفیت زندگی
|
||||
|
||||
- تغییر تم: افزودن گزینه «System»
|
||||
|
||||
- تایپوگرافی: سبکهای بهتر فهرست کار با چکباکس
|
||||
|
||||
- سوییچر زبان: ترتیبدهی بهبود یافته همراه با موارد منوییِ آیکوندار
|
||||
|
||||
## رفع اشکالات
|
||||
|
||||
- Giscus: همگامسازی صحیح تم و زبان
|
||||
- کارتها: رفع رندر بج در حالت RTL
|
||||
- نوار ناوبری: بهبود موقعیت و تعاملات منو
|
||||
|
||||
## مستندات و بومیسازی
|
||||
|
||||
- مستندات: صفحهٔ جدیدی دربارهٔ شورتکدهای Hextra
|
||||
- i18n: افزودن ترجمههای `copyCode` و `system` به `zh-cn`
|
||||
|
||||
---
|
||||
|
||||
**تغییرات کامل**: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: "Hextra v0.11"
|
||||
date: 2025-08-30
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.11.0 は、UX の磨き込みと便利な新コンポーネントに注力したリリースです。サイト全体バナー、改良されたコールアウトとバッジ、よりリッチなカード、アナリティクス連携、そしていくつかのナビゲーション改善を含みます。安定性の修正とドキュメント更新も同梱しています。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## アップグレードガイド
|
||||
|
||||
ほとんどのサイトで破壊的変更はありません。[Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) を使って更新してください:
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
## ハイライト
|
||||
|
||||
- お知らせ用のトップバナーコンポーネント
|
||||
- より見やすくなったコールアウトの刷新
|
||||
- Umami と Matomo のアナリティクス対応
|
||||
- 端末録画のための Asciinema ショートコード
|
||||
- 外部リンク装飾オプション
|
||||
- 単一ページ（ドキュメント・ブログ以外）向けのパンくずリスト
|
||||
- ナビバー改善: アイコン付きリンク項目と配置の改善
|
||||
- バッジとカードのカスタマイズ性向上
|
||||
- テーマ切り替えに「System」オプションを追加
|
||||
|
||||
## 新機能
|
||||
|
||||
### トップバナー
|
||||
|
||||
告知やリリース、ステータスメッセージ向けに、サイト全体で表示できる閉じられるバナーを追加します。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
banner:
|
||||
key: "announcement"
|
||||
message: Welcome!
|
||||
```
|
||||
|
||||
|
||||
|
||||
### コールアウト刷新
|
||||
|
||||
[Callout]({{% relref "docs/guide/shortcodes/callout" %}}) のデザインを刷新し、テーマを問わず可読性と強調表現を向上しました。
|
||||
|
||||
|
||||
|
||||
### アナリティクス: Umami と Matomo
|
||||
|
||||
以下のアナリティクスプロバイダに組み込み設定で対応:
|
||||
- [Umami]({{% relref "docs/guide/configuration.md#umami-analytics" %}})
|
||||
- [Matomo]({{% relref "docs/guide/configuration.md#matomo-analytics" %}})
|
||||
|
||||
### Asciinema ショートコード
|
||||
|
||||
[Asciinema](https://www.asciinema.org/) の端末録画を、新しい [Asciinema ショートコード]({{% relref "docs/guide/shortcodes/asciinema.md" %}}) で埋め込みできます。
|
||||
|
||||
```md
|
||||
{{</* asciinema id="123456" autoplay=true loop=true */>}}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### ナビバーの改善
|
||||
|
||||
- ナビバーのリンク項目でアイコンをサポート
|
||||
- 言語スイッチャー等との兼ね合いを考慮してメニュー配置を最適化
|
||||
|
||||
|
||||
|
||||
特に、[0.10.2](https://github.com/imfing/hextra/releases/tag/v0.10.2) ではナビバーに言語スイッチャーとテーマトグルを追加可能になりました。
|
||||
|
||||
### 外部リンク装飾
|
||||
|
||||
外部リンクに控えめな装飾をオプションで付与できます。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
externalLinkDecoration: true
|
||||
```
|
||||
|
||||
### パンくずリストの有効化
|
||||
|
||||
フロントマターで `breadcrumbs: true` を設定すると、単一ページ（ドキュメント・ブログ以外）でパンくずリストを有効化できます。
|
||||
|
||||
```yaml {filename="content/about.md"}
|
||||
---
|
||||
title: About
|
||||
breadcrumbs: true
|
||||
---
|
||||
```
|
||||
|
||||
### カードとバッジの改善
|
||||
|
||||
- [カード]({{% relref "docs/guide/shortcodes/cards.md" %}}): 新オプション `tagIcon` と `tagBorder`
|
||||
- [バッジ]({{% relref "docs/guide/shortcodes/others.md" %}}): 新しい色とボーダースタイル
|
||||
|
||||
## 利便性の向上
|
||||
|
||||
- テーマ切り替え: 「System」オプションを追加
|
||||
|
||||
- タイポグラフィ: チェックボックス付きタスクリストのスタイル改善
|
||||
|
||||
- 言語スイッチャー: アイコンメニュー項目との並び順を改善
|
||||
|
||||
## 修正
|
||||
|
||||
- Giscus: テーマと言語の同期を適切に実施
|
||||
- カード: RTL でのバッジ描画を修正
|
||||
- ナビバー: メニュー配置とインタラクションを調整
|
||||
|
||||
## ドキュメントと i18n
|
||||
|
||||
- Docs: Hextra のショートコードをまとめた新ページ
|
||||
- i18n: `zh-cn` に `copyCode` と `system` の翻訳を追加
|
||||
|
||||
---
|
||||
|
||||
**完全な変更履歴**: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: "Hextra v0.11"
|
||||
date: 2025-08-30
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.11.0 focuses on UX polish and useful new components: site-wide banner, improved callouts and badges, richer cards, analytics integrations, and several navigation refinements. It also ships stability fixes and documentation updates.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Upgrade Guide
|
||||
|
||||
No breaking changes are expected for most sites. Update using [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/):
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
## Highlights
|
||||
|
||||
- Top banner component for announcements
|
||||
- Revamped callouts with clearer styles
|
||||
- Umami and Matomo analytics support
|
||||
- Asciinema shortcode for terminal recordings
|
||||
- External link decoration option
|
||||
- Breadcrumbs for single pages (non-docs, non-blogs)
|
||||
- Navbar enhancements: icon link item and improved positions
|
||||
- Improved badges and cards customization
|
||||
- Theme toggle supports "System"
|
||||
|
||||
## New Features
|
||||
|
||||
### Top Banner
|
||||
|
||||
Add a site-wide, dismissible banner for announcements, launches, or status messages.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
banner:
|
||||
key: "announcement"
|
||||
message: Welcome!
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Callout Revamp
|
||||
|
||||
[Callout]({{% relref "docs/guide/shortcodes/callout" %}}) receive a design refresh for better readability and emphasis across themes.
|
||||
|
||||
|
||||
|
||||
### Analytics: Umami and Matomo
|
||||
|
||||
Built-in configuration for analytics providers:
|
||||
- [Umami]({{% relref "docs/guide/configuration.md#umami-analytics" %}})
|
||||
- [Matomo]({{% relref "docs/guide/configuration.md#matomo-analytics" %}})
|
||||
|
||||
### Asciinema Shortcode
|
||||
|
||||
Embed terminal recordings from [Asciinema](https://www.asciinema.org/) using the new [Asciinema shortcode]({{% relref "docs/guide/shortcodes/asciinema.md" %}}).
|
||||
|
||||
```md
|
||||
{{</* asciinema id="123456" autoplay=true loop=true */>}}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Navbar Enhancements
|
||||
|
||||
- Support icons for link items in the navbar
|
||||
- Refine menu positions to play nicely with the language switcher and other items
|
||||
|
||||
|
||||
|
||||
Notably, version [0.10.2](https://github.com/imfing/hextra/releases/tag/v0.10.2) enables the addition of language switchers and theme toggles to the navbar.
|
||||
|
||||
### External Link Decoration
|
||||
|
||||
Optionally add a subtle external-link decoration to outbound links.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
externalLinkDecoration: true
|
||||
```
|
||||
|
||||
### Breadcrumbs Enablement
|
||||
|
||||
Enable breadcrumbs on single pages (non-docs, non-blogs) by setting `breadcrumbs: true` in front matter.
|
||||
|
||||
```yaml {filename="content/about.md"}
|
||||
---
|
||||
title: About
|
||||
breadcrumbs: true
|
||||
---
|
||||
```
|
||||
|
||||
### Cards and Badges Improvements
|
||||
|
||||
- [Cards]({{% relref "docs/guide/shortcodes/cards.md" %}}): new `tagIcon` and `tagBorder` options.
|
||||
- [Badges]({{% relref "docs/guide/shortcodes/others.md" %}}): new colors and border styles.
|
||||
|
||||
## Quality of Life
|
||||
|
||||
- Theme toggle: add "System" option
|
||||
|
||||
- Typography: better task list styles with checkboxes
|
||||
|
||||
- Language switcher: improved ordering with icon menu items
|
||||
|
||||
## Fixes
|
||||
|
||||
- Giscus: sync theme and language properly
|
||||
- Cards: fix badge rendering with RTL
|
||||
- Navbar: refine menu positions and interactions
|
||||
|
||||
## Documentation & i18n
|
||||
|
||||
- Docs: new page covering Hextra shortcodes
|
||||
- i18n: add `copyCode` and `system` translations to `zh-cn`
|
||||
|
||||
---
|
||||
|
||||
**Full Changelog**: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
title: "Hextra v0.11"
|
||||
date: 2025-08-30
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.11.0 专注于打磨使用体验并带来数个实用新组件：站点级顶部横幅、改进的提示框与徽章、更丰富的卡片、分析工具集成，以及多项导航优化。同时包含稳定性修复和文档更新。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## 升级指南
|
||||
|
||||
对大多数站点而言没有破坏性变更。使用 [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) 更新：
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
## 亮点
|
||||
|
||||
- 用于公告的顶栏横幅组件
|
||||
- 重新设计的提示框，样式更清晰
|
||||
- 支持 Umami 与 Matomo 分析
|
||||
- Asciinema 短代码用于终端录屏
|
||||
- 外链装饰选项
|
||||
- 单页（非文档、非博客）支持面包屑
|
||||
- 导航栏增强：图标链接项与更优布局
|
||||
- 徽章与卡片的自定义能力提升
|
||||
- 主题切换增加「System」选项
|
||||
|
||||
## 新功能
|
||||
|
||||
### 顶部横幅
|
||||
|
||||
为公告、发布或状态消息添加一个站点级、可关闭的横幅。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
banner:
|
||||
key: "announcement"
|
||||
message: Welcome!
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 提示框重设计
|
||||
|
||||
[Callout]({{% relref "docs/guide/shortcodes/callout" %}}) 获得样式刷新，在各主题下具备更好的可读性与强调效果。
|
||||
|
||||
|
||||
|
||||
### 分析：Umami 与 Matomo
|
||||
|
||||
内置以下分析平台的配置支持：
|
||||
- [Umami]({{% relref "docs/guide/configuration.md#umami-analytics" %}})
|
||||
- [Matomo]({{% relref "docs/guide/configuration.md#matomo-analytics" %}})
|
||||
|
||||
### Asciinema 短代码
|
||||
|
||||
使用全新的 [Asciinema 短代码]({{% relref "docs/guide/shortcodes/asciinema.md" %}}) 嵌入 [Asciinema](https://www.asciinema.org/) 终端录屏。
|
||||
|
||||
```md
|
||||
{{</* asciinema id="123456" autoplay=true loop=true */>}}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 导航栏增强
|
||||
|
||||
- 支持在导航栏链接项中使用图标
|
||||
- 优化菜单的相对位置，使其与语言切换器等项协同更佳
|
||||
|
||||
|
||||
|
||||
值得一提的是，版本 [0.10.2](https://github.com/imfing/hextra/releases/tag/v0.10.2) 已支持在导航栏添加语言切换器与主题切换。
|
||||
|
||||
### 外链装饰
|
||||
|
||||
可选地为外部链接添加轻量的外链标识装饰。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
externalLinkDecoration: true
|
||||
```
|
||||
|
||||
### 启用面包屑
|
||||
|
||||
在单页（非文档、非博客）上，通过在 Front Matter 中设置 `breadcrumbs: true` 启用面包屑。
|
||||
|
||||
```yaml {filename="content/about.md"}
|
||||
---
|
||||
title: About
|
||||
breadcrumbs: true
|
||||
---
|
||||
```
|
||||
|
||||
### 卡片与徽章的改进
|
||||
|
||||
- [卡片]({{% relref "docs/guide/shortcodes/cards.md" %}})：新增 `tagIcon` 与 `tagBorder` 选项。
|
||||
- [徽章]({{% relref "docs/guide/shortcodes/others.md" %}})：新增颜色与边框样式。
|
||||
|
||||
## 使用体验优化
|
||||
|
||||
- 主题切换：增加「System」选项
|
||||
|
||||
- 字体排版：改进带复选框的任务列表样式
|
||||
|
||||
- 语言切换器：与图标菜单项的排序更合理
|
||||
|
||||
## 修复
|
||||
|
||||
- Giscus：正确同步主题与语言
|
||||
- 卡片：修复 RTL 场景下的徽章渲染
|
||||
- 导航栏：优化菜单位置与交互
|
||||
|
||||
## 文档与 i18n
|
||||
|
||||
- 文档：新增页面介绍 Hextra 的短代码
|
||||
- i18n：为 `zh-cn` 增加 `copyCode` 与 `system` 翻译
|
||||
|
||||
---
|
||||
|
||||
**完整变更日志**: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0
|
||||
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
title: "Hextra v0.12"
|
||||
date: 2026-02-20
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- انتشار
|
||||
---
|
||||
|
||||
Hextra v0.12.0 مجموعهای غنی از ویژگیهای جدید شامل منوی زمینه صفحه، زوم تصویر، تبهای بازطراحیشده و موارد بیشتر، به همراه بهبودهای جامع دسترسپذیری WCAG 2.2 AA و رفع اشکالات متعدد ارائه میدهد.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## راهنمای ارتقا
|
||||
|
||||
برای بیشتر سایتها تغییر شکستآمیزی وجود ندارد. با استفاده از [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) بهروزرسانی کنید:
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
## نکات برجسته
|
||||
|
||||
- منوی زمینه صفحه برای کپی/مشاهده سورس Markdown
|
||||
- بازطراحی شورتکد تبها با نامگذاری هر تب و پشتیبانی از آیکون
|
||||
- زوم با کلیک برای تصاویر Markdown
|
||||
- پشتیبانی از تحلیلگر GoatCounter
|
||||
- گزینه مخفیکردن نوار کناری اصلی در دسکتاپ
|
||||
- نمایش آخرین نویسنده ویرایشکننده از طریق GitInfo
|
||||
- گزینه غیرفعالسازی ناوبری قبلی/بعدی
|
||||
- صفحه آرشیو داخلی برای فهرست زمانی نوشتههای وبلاگ
|
||||
- شورتکد و چیدمان واژهنامه
|
||||
- حذف صفحات/بخشها از llms.txt
|
||||
- ترتیب و برچسبهای نوار کناری موبایل همراستا با `menu.main`
|
||||
- عرض محتوای پایدار با پشتیبانی از بازنویسی متغیر CSS
|
||||
- بهبودهای جامع دسترسپذیری WCAG 2.2 AA
|
||||
|
||||
## ویژگیهای جدید
|
||||
|
||||
### منوی زمینه صفحه
|
||||
|
||||
|
||||
|
||||
منوی زمینه صفحه دکمهای کشویی فراهم میکند که با آن میتوانید محتوای صفحه را بهصورت Markdown کپی کنید یا سورس خام Markdown را مشاهده نمایید. با افزایش کاربرانی که مستندات را به ابزارهای هوش مصنوعی مولّد میدهند، دسترسی سریع به Markdown تمیز بسیار مفید است. پیوندهای سفارشی با متغیرهای قالب (`{url}`، `{title}`، `{markdown_url}`) به شما امکان میدهند میانبرهای «از AI بپرس» یا سایر یکپارچهسازیها را مستقیماً در منو ایجاد کنید.
|
||||
|
||||
برای استفاده از قابلیتهای «مشاهده بهصورت Markdown» و `{markdown_url}`، فرمت خروجی Markdown را در پیکربندی سایت فعال کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
page: [html, markdown]
|
||||
section: [html, rss, markdown]
|
||||
```
|
||||
|
||||
سپس منوی زمینه را پیکربندی کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
links:
|
||||
- name: "Ask AI"
|
||||
url: "https://example.com?content={markdown_url}"
|
||||
icon: "sparkles"
|
||||
```
|
||||
|
||||
### بازطراحی تبها و پشتیبانی از آیکون
|
||||
|
||||
[شورتکد تبها]({{% relref "docs/guide/shortcodes/tabs" %}}) بازطراحی شده است. اکنون میتوان نام تبها را مستقیماً روی هر شورتکد `tab` تنظیم کرد و پارامتر اختیاری `icon` یک آیکون قبل از برچسب تب نمایش میدهد. نحو قبلی همچنان پشتیبانی میشود.
|
||||
|
||||
```md
|
||||
{{</* tabs */>}}
|
||||
{{</* tab name="Photos" icon="photograph" */>}}مدیریت و سازماندهی کتابخانه عکسهای شما.{{</* /tab */>}}
|
||||
{{</* tab name="Music" icon="music-note" */>}}مرور و پخش آهنگهای مورد علاقه شما.{{</* /tab */>}}
|
||||
{{</* tab name="Videos" icon="film" */>}}تماشا و پخش محتوای ویدیویی.{{</* /tab */>}}
|
||||
{{</* /tabs */>}}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### زوم تصویر
|
||||
|
||||
با یک گزینه پیکربندی جدید، زوم با کلیک را روی تصاویر Markdown فعال کنید. این قابلیت از [medium-zoom](https://github.com/francoischalifour/medium-zoom) استفاده میکند.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
```
|
||||
|
||||
### تحلیلگر GoatCounter
|
||||
|
||||
پشتیبانی داخلی از تحلیلگر [GoatCounter](https://www.goatcounter.com/) در کنار یکپارچهسازیهای موجود Google Analytics، Umami و Matomo.
|
||||
|
||||
### مخفیکردن نوار کناری اصلی
|
||||
|
||||
یک پارامتر جدید فرانتمتر امکان مخفیکردن نوار کناری اصلی در دسکتاپ را فراهم میکند تا صفحات محتوا عرض کامل داشته باشند.
|
||||
|
||||
```yaml {filename="content/my-page.md"}
|
||||
---
|
||||
title: My Page
|
||||
sidebar:
|
||||
hide: true
|
||||
---
|
||||
```
|
||||
|
||||
### آخرین نویسنده ویرایشکننده
|
||||
|
||||
با استفاده از GitInfo هوگو، آخرین نویسنده کامیت را در کنار تاریخ «آخرین بهروزرسانی» نمایش دهید.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
displayUpdatedAuthor: true
|
||||
```
|
||||
|
||||
|
||||
|
||||
### غیرفعالسازی ناوبری قبلی/بعدی
|
||||
|
||||
دکمههای ناوبری قبلی/بعدی را در سطح سایت غیرفعال کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
displayPagination: false
|
||||
```
|
||||
|
||||
### حذف از LLMs.txt
|
||||
|
||||
با تنظیم `llms: false` در فرانتمتر، صفحات یا بخشهای کامل را از خروجی `llms.txt` حذف کنید.
|
||||
|
||||
```yaml {filename="content/private-page.md"}
|
||||
---
|
||||
title: "Private Page"
|
||||
llms: false
|
||||
---
|
||||
```
|
||||
|
||||
### صفحه آرشیو
|
||||
|
||||
چیدمان جدید داخلی `archives` نوشتههای وبلاگ را در یک خط زمانی گروهبندیشده بر اساس سال نمایش میدهد و برچسبها بهصورت درونخطی پس از عنوان هر نوشته نشان داده میشوند.
|
||||
|
||||
```yaml {filename="content/archives/_index.md"}
|
||||
---
|
||||
title: Archives
|
||||
layout: archives
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
|
||||
### واژهنامه
|
||||
|
||||
یک [واژهنامه]({{% relref "docs/guide/shortcodes/term" %}}) اصطلاحات سراسری سایت با صفحه فهرست اختصاصی و شورتکد `term` برای تعاریف درونخطی.
|
||||
|
||||
## دسترسپذیری
|
||||
|
||||
بهبودهای جامع دسترسپذیری WCAG 2.2 AA (#924):
|
||||
|
||||
- پیوند رفتن به محتوا و نقشهای نشانهای ARIA در تمام صفحات
|
||||
- ویژگیهای ARIA برای تمام ابزارکهای تعاملی (کلید تغییر تم، تبها، نوار کناری، درخت فایل، منوهای بازشو، جستجو، منوها)
|
||||
- ناوبری صفحهکلیدی برای تبها و کلید تغییر تم (کلیدهای جهتی، Enter، Escape)
|
||||
- پشتیبانی از `prefers-reduced-motion` و سبکهای سراسری `focus-visible`
|
||||
- ۱۵ کلید دسترسپذیری i18n جدید با ترجمه کامل در تمام ۲۱ محلیسازی
|
||||
- جایگزینی تمام رشتههای انگلیسی `aria-label` که بهصورت هاردکد بودند با جستجوی i18n
|
||||
|
||||
## بهبودهای کیفیت زندگی
|
||||
|
||||
- بهبود سبکهای خوانایی جدول
|
||||
- پشتیبانی از ویژگیهای Markdown برای سرتیترها
|
||||
- تشخیص بهتر پیوند فعال برای صفحات فرود بخش چندزبانه
|
||||
- پشتیبانی شورتکد کارت از پارامتر اختیاری `alt` برای تصاویر
|
||||
- پشتیبانی از تصاویر بسته صفحه در ابرداده OpenGraph
|
||||
- عرض محتوا اکنون بهصورت پیشفرض ثابت است، با پشتیبانی از بازنویسی متغیر CSS برای چیدمانهای سفارشی
|
||||
|
||||
## رفع اشکالات
|
||||
|
||||
- جلوگیری از پیشوند پایه دوگانه `relref` در render-link
|
||||
- رفع رندر تبها هنگام تودرتوبودن در مراحل
|
||||
- همراستاسازی ترتیب و برچسبهای نوار کناری موبایل با `menu.main`
|
||||
- رعایت `search.enable` در نوار کناری
|
||||
- رعایت پارامتر صفحه `toc` در منوی بازشو موبایل
|
||||
- بهبود برجستهسازی تطبیق FlexSearch و دستکاری امن DOM
|
||||
- رفع موقعیت زیرعنوان کارت
|
||||
- مدیریت اسلشهای ابتدایی در مسیرهای تصویر OG برای استقرارهای زیرمسیر
|
||||
- رفع بازگرداندن صفحات نتیجه کمتر از حد انتظار توسط FlexSearch
|
||||
- تغییر فایل پیشفرض Umami analytics به `script.js`
|
||||
- رفع جستجوی نویسنده RSS برای Hugo v0.156.0+ (`.Site.Params.Author`)
|
||||
|
||||
## مستندات و بومیسازی
|
||||
|
||||
- افزودن بومیسازی ایتالیایی
|
||||
- پیوند مستندات KaTeX
|
||||
- بهروزرسانی مستندات شورتکد details به نحو angle bracket
|
||||
|
||||
## مشارکتکنندگان
|
||||
|
||||
این انتشار با مشارکت ۱۱ مشارکتکننده جدید ممکن شد:
|
||||
|
||||
- [@ghac101](https://github.com/ghac101) - رفع Umami analytics، غیرفعالسازی ناوبری قبلی/بعدی
|
||||
- [@pmarrapese](https://github.com/pmarrapese) - پشتیبانی از ویژگیهای Markdown برای سرتیترها
|
||||
- [@Bubbler-4](https://github.com/Bubbler-4) - مستندات شورتکد details
|
||||
- [@bloovis](https://github.com/bloovis) - رفع تعداد نتایج FlexSearch
|
||||
- [@AntoninPvr](https://github.com/AntoninPvr) - رفع موقعیت زیرعنوان کارت
|
||||
- [@illia-v](https://github.com/illia-v) - رفع TOC موبایل و کلید تغییر جستجو
|
||||
- [@gallochri](https://github.com/gallochri) - بومیسازی ایتالیایی
|
||||
- [@MatheusFlausino](https://github.com/MatheusFlausino) - حذف از LLMs.txt
|
||||
- [@daniseijo](https://github.com/daniseijo) - قابلیت آخرین نویسنده ویرایشکننده
|
||||
- [@confusedkernel](https://github.com/confusedkernel) - صفحه آرشیو
|
||||
- [@Fenyutanchan](https://github.com/Fenyutanchan) - رفع سازگاری نویسنده RSS با Hugo v0.156.0
|
||||
|
||||
همچنین از مشارکتکنندگان بازگشته [@KStocky](https://github.com/KStocky)، [@ldez](https://github.com/ldez)، [@kowyo](https://github.com/kowyo)، [@torbjornbp](https://github.com/torbjornbp)، [@yuri1969](https://github.com/yuri1969) و [@PrintN](https://github.com/PrintN) بابت مشارکتهای مداومشان سپاسگزاریم.
|
||||
|
||||
---
|
||||
|
||||
**تغییرات کامل**: https://github.com/imfing/hextra/compare/v0.11.1...v0.12.0
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
title: "Hextra v0.12"
|
||||
date: 2026-02-20
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.12.0 は、ページコンテキストメニュー、画像ズーム、刷新されたタブ、その他多くの新機能に加え、包括的な WCAG 2.2 AA アクセシビリティ改善と多数のバグ修正を提供します。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## アップグレードガイド
|
||||
|
||||
ほとんどのサイトで破壊的変更はありません。[Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) を使って更新してください:
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
## ハイライト
|
||||
|
||||
- Markdown ソースのコピー・表示ができるページコンテキストメニュー
|
||||
- タブ名指定とアイコンをサポートする刷新されたタブショートコード
|
||||
- Markdown 画像のクリックズーム
|
||||
- GoatCounter アナリティクス対応
|
||||
- デスクトップでメインサイドバーを非表示にするオプション
|
||||
- GitInfo による最終更新者の表示
|
||||
- 前へ/次へナビゲーションの無効化オプション
|
||||
- ブログ記事の年別アーカイブページ
|
||||
- 用語集ショートコードとレイアウト
|
||||
- llms.txt からのページ/セクション除外
|
||||
- モバイルサイドバーの順序とラベルが `menu.main` に準拠
|
||||
- CSS 変数オーバーライドによる安定したコンテンツ幅
|
||||
- 包括的な WCAG 2.2 AA アクセシビリティ改善
|
||||
|
||||
## 新機能
|
||||
|
||||
### ページコンテキストメニュー
|
||||
|
||||
|
||||
|
||||
ページコンテキストメニューはドロップダウンボタンを提供し、ページの内容を Markdown としてコピーしたり、生の Markdown ソースを表示できます。ドキュメントを生成 AI ツールに取り込むユーザーが増える中、クリーンな Markdown への素早いアクセスはますます有用です。テンプレート変数（`{url}`、`{title}`、`{markdown_url}`）を使ったカスタムリンクにより、「AI に質問」ショートカットなどのインテグレーションをメニューに直接組み込めます。
|
||||
|
||||
「Markdown として表示」および `{markdown_url}` 機能を利用するには、サイト設定で Markdown 出力フォーマットを有効にしてください:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
page: [html, markdown]
|
||||
section: [html, rss, markdown]
|
||||
```
|
||||
|
||||
次にコンテキストメニューを設定します:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
links:
|
||||
- name: "Ask AI"
|
||||
url: "https://example.com?content={markdown_url}"
|
||||
icon: "sparkles"
|
||||
```
|
||||
|
||||
### タブの刷新とアイコン対応
|
||||
|
||||
[タブショートコード]({{% relref "docs/guide/shortcodes/tabs" %}})が刷新されました。各 `tab` ショートコードでタブ名を直接設定でき、オプションの `icon` パラメータでラベルの前にアイコンを表示できます。従来の構文も引き続きサポートされています。
|
||||
|
||||
```md
|
||||
{{</* tabs */>}}
|
||||
{{</* tab name="Photos" icon="photograph" */>}}写真ライブラリを管理・整理します。{{</* /tab */>}}
|
||||
{{</* tab name="Music" icon="music-note" */>}}お気に入りの曲を閲覧・再生します。{{</* /tab */>}}
|
||||
{{</* tab name="Videos" icon="film" */>}}動画コンテンツを視聴・ストリーミングします。{{</* /tab */>}}
|
||||
{{</* /tabs */>}}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 画像ズーム
|
||||
|
||||
[medium-zoom](https://github.com/francoischalifour/medium-zoom) を利用した新しい設定オプションで、Markdown 画像のクリックズームを有効にできます。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
```
|
||||
|
||||
### GoatCounter アナリティクス
|
||||
|
||||
既存の Google Analytics、Umami、Matomo に加え、[GoatCounter](https://www.goatcounter.com/) アナリティクスの組み込みサポートを追加しました。
|
||||
|
||||
### メインサイドバーの非表示
|
||||
|
||||
新しいフロントマターパラメータにより、デスクトップでメインサイドバーを非表示にしてコンテンツを全幅表示できます。
|
||||
|
||||
```yaml {filename="content/my-page.md"}
|
||||
---
|
||||
title: My Page
|
||||
sidebar:
|
||||
hide: true
|
||||
---
|
||||
```
|
||||
|
||||
### 最終更新者の表示
|
||||
|
||||
Hugo の GitInfo を使って、「最終更新日」と合わせて最終コミット者を表示します。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
displayUpdatedAuthor: true
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 前へ/次へナビゲーションの無効化
|
||||
|
||||
サイト全体で前へ/次へナビゲーションボタンを無効にできます:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
displayPagination: false
|
||||
```
|
||||
|
||||
### LLMs.txt 除外
|
||||
|
||||
フロントマターで `llms: false` を設定すると、個別のページやセクション全体を `llms.txt` 出力から除外できます。
|
||||
|
||||
```yaml {filename="content/private-page.md"}
|
||||
---
|
||||
title: "Private Page"
|
||||
llms: false
|
||||
---
|
||||
```
|
||||
|
||||
### アーカイブページ
|
||||
|
||||
新しい組み込み `archives` レイアウトは、ブログ記事を年ごとにグループ化した時系列タイムラインで表示し、各タイトルの後にタグをインラインで表示します。
|
||||
|
||||
```yaml {filename="content/archives/_index.md"}
|
||||
---
|
||||
title: Archives
|
||||
layout: archives
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 用語集
|
||||
|
||||
サイト全体の[用語集]({{% relref "docs/guide/shortcodes/term" %}})。専用のリストページとインライン定義用の `term` ショートコードを備えています。
|
||||
|
||||
## アクセシビリティ
|
||||
|
||||
包括的な WCAG 2.2 AA アクセシビリティ改善 (#924):
|
||||
|
||||
- すべてのページに本文へスキップリンクと ARIA ランドマークロール
|
||||
- すべてのインタラクティブウィジェット（テーマトグル、タブ、サイドバー、ファイルツリー、ドロップダウン、検索、メニュー）に ARIA 属性
|
||||
- タブとテーマトグルのキーボードナビゲーション（矢印キー、Enter、Escape）
|
||||
- `prefers-reduced-motion` サポートとグローバル `focus-visible` スタイル
|
||||
- 全 21 ロケールに完全翻訳された 15 個の新しい i18n アクセシビリティキー
|
||||
- ハードコードされた英語 `aria-label` 文字列をすべて i18n ルックアップに置き換え
|
||||
|
||||
## 利便性の向上
|
||||
|
||||
- テーブルの読みやすさ向上のためのスタイル改善
|
||||
- ヘッダーでの Markdown 属性サポート
|
||||
- 多言語セクションランディングページでのアクティブリンク検出の改善
|
||||
- カードショートコードで画像に `alt` パラメータをオプションでサポート
|
||||
- ページバンドル画像が OpenGraph メタデータでサポート
|
||||
- コンテンツ幅がデフォルトで安定し、カスタムレイアウト用の CSS 変数オーバーライドをサポート
|
||||
|
||||
## 修正
|
||||
|
||||
- render-link での `relref` ベースプレフィックスの二重付与を修正
|
||||
- ステップ内にネストされたタブの描画を修正
|
||||
- モバイルサイドバーの順序とラベルを `menu.main` に準拠
|
||||
- サイドバーでの `search.enable` の尊重
|
||||
- モバイルドロップダウンでの `toc` ページパラメータの尊重
|
||||
- FlexSearch のマッチハイライトと安全な DOM 操作の改善
|
||||
- カードのサブタイトル位置の修正
|
||||
- サブパスデプロイメントでの OG 画像パスの先頭スラッシュの処理
|
||||
- FlexSearch が期待より少ない結果ページを返す問題の修正
|
||||
- Umami アナリティクスのデフォルトファイルを `script.js` に変更
|
||||
- Hugo v0.156.0+ での RSS author ルックアップの修正 (`.Site.Params.Author`)
|
||||
|
||||
## ドキュメントと i18n
|
||||
|
||||
- イタリア語ローカリゼーションを追加
|
||||
- KaTeX ドキュメントへのリンクを追加
|
||||
- details ショートコードのドキュメントを angle bracket 構文に更新
|
||||
|
||||
## コントリビューター
|
||||
|
||||
このリリースは 11 名の新しいコントリビューターの貢献により実現しました:
|
||||
|
||||
- [@ghac101](https://github.com/ghac101) - Umami アナリティクスの修正、前へ/次へナビゲーションの無効化
|
||||
- [@pmarrapese](https://github.com/pmarrapese) - ヘッダーの Markdown 属性サポート
|
||||
- [@Bubbler-4](https://github.com/Bubbler-4) - details ショートコードのドキュメント
|
||||
- [@bloovis](https://github.com/bloovis) - FlexSearch の結果件数修正
|
||||
- [@AntoninPvr](https://github.com/AntoninPvr) - カードのサブタイトル位置修正
|
||||
- [@illia-v](https://github.com/illia-v) - モバイル TOC と検索トグルの修正
|
||||
- [@gallochri](https://github.com/gallochri) - イタリア語ローカリゼーション
|
||||
- [@MatheusFlausino](https://github.com/MatheusFlausino) - LLMs.txt 除外
|
||||
- [@daniseijo](https://github.com/daniseijo) - 最終更新者機能
|
||||
- [@confusedkernel](https://github.com/confusedkernel) - アーカイブページ
|
||||
- [@Fenyutanchan](https://github.com/Fenyutanchan) - Hugo v0.156.0 RSS author 互換性修正
|
||||
|
||||
さらに、継続的な貢献をいただいている [@KStocky](https://github.com/KStocky)、[@ldez](https://github.com/ldez)、[@kowyo](https://github.com/kowyo)、[@torbjornbp](https://github.com/torbjornbp)、[@yuri1969](https://github.com/yuri1969)、[@PrintN](https://github.com/PrintN) の各コントリビューターに感謝いたします。
|
||||
|
||||
---
|
||||
|
||||
**完全な変更履歴**: https://github.com/imfing/hextra/compare/v0.11.1...v0.12.0
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
title: "Hextra v0.12"
|
||||
date: 2026-02-20
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.12.0 delivers a rich set of new features including page context menus, image zoom, redesigned tabs, and more, plus comprehensive WCAG 2.2 AA accessibility improvements and numerous bug fixes.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Upgrade Guide
|
||||
|
||||
No breaking changes are expected for most sites. Update using [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/):
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
## Highlights
|
||||
|
||||
- Page context menu for copying/viewing Markdown source
|
||||
- Redesigned tabs shortcode with per-tab naming and icon support
|
||||
- Click-to-zoom for Markdown images
|
||||
- GoatCounter analytics support
|
||||
- Option to hide the main sidebar on desktop
|
||||
- Display last modified author via GitInfo
|
||||
- Option to disable prev/next navigation
|
||||
- Built-in archives page for chronological blog post listings
|
||||
- Term glossary shortcode and layout
|
||||
- Exclude pages/sections from llms.txt
|
||||
- Mobile sidebar ordering and labels aligned with `menu.main`
|
||||
- Stable content width with CSS variable override support
|
||||
- Comprehensive WCAG 2.2 AA accessibility improvements
|
||||
|
||||
## New Features
|
||||
|
||||
### Page Context Menu
|
||||
|
||||
|
||||
|
||||
The page context menu provides a dropdown button that lets you copy the page content as Markdown or view the raw Markdown source. As more users feed documentation into generative AI tools, having quick access to clean Markdown is increasingly useful. Custom links with template variables (`{url}`, `{title}`, `{markdown_url}`) let you wire up "Ask AI" shortcuts or other integrations directly in the menu.
|
||||
|
||||
To use the "View as Markdown" and `{markdown_url}` features, enable the Markdown output format in your site configuration:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
page: [html, markdown]
|
||||
section: [html, rss, markdown]
|
||||
```
|
||||
|
||||
Then configure the context menu:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
links:
|
||||
- name: "Ask AI"
|
||||
url: "https://example.com?content={markdown_url}"
|
||||
icon: "sparkles"
|
||||
```
|
||||
|
||||
### Tabs Revamp and Icon Support
|
||||
|
||||
The [tabs shortcode]({{% relref "docs/guide/shortcodes/tabs" %}}) has been redesigned. Tab names can now be set directly on each `tab` shortcode, and an optional `icon` parameter displays an icon before the tab label. The previous syntax is still supported.
|
||||
|
||||
```md
|
||||
{{</* tabs */>}}
|
||||
{{</* tab name="Photos" icon="photograph" */>}}Manage and organize your photo library.{{</* /tab */>}}
|
||||
{{</* tab name="Music" icon="music-note" */>}}Browse and play your favorite tracks.{{</* /tab */>}}
|
||||
{{</* tab name="Videos" icon="film" */>}}Watch and stream video content.{{</* /tab */>}}
|
||||
{{</* /tabs */>}}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Image Zoom
|
||||
|
||||
Enable click-to-zoom on Markdown images with a new configuration option, powered by [medium-zoom](https://github.com/francoischalifour/medium-zoom).
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
```
|
||||
|
||||
### GoatCounter Analytics
|
||||
|
||||
Built-in support for [GoatCounter](https://www.goatcounter.com/) analytics alongside existing Google Analytics, Umami, and Matomo integrations.
|
||||
|
||||
### Hide Main Sidebar
|
||||
|
||||
A new front matter parameter allows hiding the main sidebar on desktop to give content pages the full width.
|
||||
|
||||
```yaml {filename="content/my-page.md"}
|
||||
---
|
||||
title: My Page
|
||||
sidebar:
|
||||
hide: true
|
||||
---
|
||||
```
|
||||
|
||||
### Last Modified Author
|
||||
|
||||
Display the last commit author alongside the "last updated" date using Hugo's GitInfo.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
displayUpdatedAuthor: true
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Disable Prev/Next Navigation
|
||||
|
||||
Disable the previous/next navigation buttons site-wide:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
displayPagination: false
|
||||
```
|
||||
|
||||
### LLMs.txt Exclusion
|
||||
|
||||
Exclude individual pages or entire sections from `llms.txt` output by setting `llms: false` in front matter.
|
||||
|
||||
```yaml {filename="content/private-page.md"}
|
||||
---
|
||||
title: "Private Page"
|
||||
llms: false
|
||||
---
|
||||
```
|
||||
|
||||
### Archives Page
|
||||
|
||||
A new built-in `archives` layout displays blog posts in a chronological timeline grouped by year, with tags shown inline after each post title.
|
||||
|
||||
```yaml {filename="content/archives/_index.md"}
|
||||
---
|
||||
title: Archives
|
||||
layout: archives
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Glossary
|
||||
|
||||
A site-wide terminology [glossary]({{% relref "docs/guide/shortcodes/term" %}}) with a dedicated listing page and a `term` shortcode for inline definitions.
|
||||
|
||||
## Accessibility
|
||||
|
||||
Comprehensive WCAG 2.2 AA accessibility improvements (#924):
|
||||
|
||||
- Skip-to-content link and ARIA landmark roles on all pages
|
||||
- ARIA attributes on all interactive widgets (theme toggle, tabs, sidebar, filetree, dropdowns, search, menus)
|
||||
- Keyboard navigation for tabs and theme toggle (arrow keys, Enter, Escape)
|
||||
- `prefers-reduced-motion` support and global `focus-visible` styles
|
||||
- 15 new i18n accessibility keys with full translations across all 21 locales
|
||||
- Replaced all hardcoded English `aria-label` strings with i18n lookups
|
||||
|
||||
## Quality of Life
|
||||
|
||||
- Improved table readability styles
|
||||
- Markdown attribute support for headers
|
||||
- Better active link detection for multilingual section landing pages
|
||||
- Card shortcode supports optional `alt` parameter for images
|
||||
- Page bundle images supported in OpenGraph metadata
|
||||
- Content width now stays consistent by default, with CSS variable override support for custom layouts
|
||||
|
||||
## Fixes
|
||||
|
||||
- Prevent `relref` double base-prefix in render-link
|
||||
- Fix tabs rendering when nested inside steps
|
||||
- Align mobile sidebar ordering and labels with `menu.main`
|
||||
- Respect `search.enable` in the sidebar
|
||||
- Respect the `toc` page parameter in mobile dropdown
|
||||
- Enhance FlexSearch match highlighting and safe DOM manipulation
|
||||
- Fix card subtitle positioning
|
||||
- Handle leading slashes in OG image paths for subpath deployments
|
||||
- Fix FlexSearch returning fewer than expected result pages
|
||||
- Change default Umami analytics file to `script.js`
|
||||
- Fix RSS author lookup for Hugo v0.156.0+ (`.Site.Params.Author`)
|
||||
|
||||
## Documentation & i18n
|
||||
|
||||
- Add Italian localization
|
||||
- Link KaTeX documentation
|
||||
- Update details shortcode docs to angle bracket syntax
|
||||
|
||||
## Contributors
|
||||
|
||||
This release was made possible by contributions from 11 new contributors:
|
||||
|
||||
- [@ghac101](https://github.com/ghac101) - Umami analytics fix, disable prev/next navigation
|
||||
- [@pmarrapese](https://github.com/pmarrapese) - Markdown attribute support for headers
|
||||
- [@Bubbler-4](https://github.com/Bubbler-4) - Details shortcode documentation
|
||||
- [@bloovis](https://github.com/bloovis) - FlexSearch result count fix
|
||||
- [@AntoninPvr](https://github.com/AntoninPvr) - Card subtitle positioning fix
|
||||
- [@illia-v](https://github.com/illia-v) - Mobile TOC and search toggle fixes
|
||||
- [@gallochri](https://github.com/gallochri) - Italian localization
|
||||
- [@MatheusFlausino](https://github.com/MatheusFlausino) - LLMs.txt exclusion
|
||||
- [@daniseijo](https://github.com/daniseijo) - Last modified author feature
|
||||
- [@confusedkernel](https://github.com/confusedkernel) - Archives page
|
||||
- [@Fenyutanchan](https://github.com/Fenyutanchan) - Hugo v0.156.0 RSS author compatibility fix
|
||||
|
||||
Additional thanks to returning contributors [@KStocky](https://github.com/KStocky), [@ldez](https://github.com/ldez), [@kowyo](https://github.com/kowyo), [@torbjornbp](https://github.com/torbjornbp), [@yuri1969](https://github.com/yuri1969), and [@PrintN](https://github.com/PrintN) for their continued contributions.
|
||||
|
||||
---
|
||||
|
||||
**Full Changelog**: https://github.com/imfing/hextra/compare/v0.11.1...v0.12.0
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
title: "Hextra v0.12"
|
||||
date: 2026-02-20
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.12.0 带来了丰富的新功能，包括页面上下文菜单、图片缩放、全新设计的标签页等，同时提供全面的 WCAG 2.2 AA 无障碍改进和大量错误修复。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## 升级指南
|
||||
|
||||
对大多数站点而言没有破坏性变更。使用 [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) 更新：
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
## 亮点
|
||||
|
||||
- 页面上下文菜单，可复制/查看 Markdown 源码
|
||||
- 全新设计的标签页短代码，支持单独命名和图标
|
||||
- Markdown 图片点击缩放
|
||||
- GoatCounter 分析支持
|
||||
- 桌面端隐藏主侧边栏选项
|
||||
- 通过 GitInfo 显示最后修改作者
|
||||
- 禁用上一篇/下一篇导航选项
|
||||
- 内置归档页面，按时间顺序列出博客文章
|
||||
- 术语表短代码和布局
|
||||
- 从 llms.txt 中排除页面/章节
|
||||
- 移动端侧边栏排序和标签与 `menu.main` 对齐
|
||||
- 通过 CSS 变量覆盖支持稳定的内容宽度
|
||||
- 全面的 WCAG 2.2 AA 无障碍改进
|
||||
|
||||
## 新功能
|
||||
|
||||
### 页面上下文菜单
|
||||
|
||||
|
||||
|
||||
页面上下文菜单提供下拉按钮，可将页面内容复制为 Markdown 或查看原始 Markdown 源码。随着越来越多用户将文档输入生成式 AI 工具，快速获取干净的 Markdown 变得越来越有用。通过模板变量（`{url}`、`{title}`、`{markdown_url}`）添加自定义链接，可以在菜单中直接集成“询问 AI”快捷方式或其他功能。
|
||||
|
||||
要使用“以 Markdown 查看”和 `{markdown_url}` 功能，请在站点配置中启用 Markdown 输出格式：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
page: [html, markdown]
|
||||
section: [html, rss, markdown]
|
||||
```
|
||||
|
||||
然后配置页面上下文菜单：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
links:
|
||||
- name: "Ask AI"
|
||||
url: "https://example.com?content={markdown_url}"
|
||||
icon: "sparkles"
|
||||
```
|
||||
|
||||
### 标签页重设计与图标支持
|
||||
|
||||
[标签页短代码]({{% relref "docs/guide/shortcodes/tabs" %}})经过重新设计。现在可以直接在每个 `tab` 短代码上设置标签名称，可选的 `icon` 参数可在标签文字前显示图标。之前的语法仍然支持。
|
||||
|
||||
```md
|
||||
{{</* tabs */>}}
|
||||
{{</* tab name="Photos" icon="photograph" */>}}管理和整理您的照片库。{{</* /tab */>}}
|
||||
{{</* tab name="Music" icon="music-note" */>}}浏览和播放您喜爱的曲目。{{</* /tab */>}}
|
||||
{{</* tab name="Videos" icon="film" */>}}观看和串流视频内容。{{</* /tab */>}}
|
||||
{{</* /tabs */>}}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 图片缩放
|
||||
|
||||
通过新的配置选项，启用 Markdown 图片的点击缩放功能，基于 [medium-zoom](https://github.com/francoischalifour/medium-zoom) 实现。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
```
|
||||
|
||||
### GoatCounter 分析
|
||||
|
||||
在现有的 Google Analytics、Umami 和 Matomo 集成之外，新增 [GoatCounter](https://www.goatcounter.com/) 分析的内置支持。
|
||||
|
||||
### 隐藏主侧边栏
|
||||
|
||||
新的 Front Matter 参数允许在桌面端隐藏主侧边栏，使内容页面获得全宽显示。
|
||||
|
||||
```yaml {filename="content/my-page.md"}
|
||||
---
|
||||
title: My Page
|
||||
sidebar:
|
||||
hide: true
|
||||
---
|
||||
```
|
||||
|
||||
### 最后修改作者
|
||||
|
||||
使用 Hugo 的 GitInfo 功能，在"最后更新"日期旁显示最后提交的作者。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
displayUpdatedAuthor: true
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 禁用上一篇/下一篇导航
|
||||
|
||||
在站点范围内禁用上一篇/下一篇导航按钮：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
displayPagination: false
|
||||
```
|
||||
|
||||
### LLMs.txt 排除
|
||||
|
||||
通过在 Front Matter 中设置 `llms: false`，将单个页面或整个章节从 `llms.txt` 输出中排除。
|
||||
|
||||
```yaml {filename="content/private-page.md"}
|
||||
---
|
||||
title: "Private Page"
|
||||
llms: false
|
||||
---
|
||||
```
|
||||
|
||||
### 归档页面
|
||||
|
||||
新的内置 `archives` 布局按年份分组，以时间线形式展示博客文章，每篇文章标题后内联显示标签。
|
||||
|
||||
```yaml {filename="content/archives/_index.md"}
|
||||
---
|
||||
title: Archives
|
||||
layout: archives
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 术语表
|
||||
|
||||
站点级[术语表]({{% relref "docs/guide/shortcodes/term" %}})，提供专用列表页面和用于内联定义的 `term` 短代码。
|
||||
|
||||
## 无障碍
|
||||
|
||||
全面的 WCAG 2.2 AA 无障碍改进 (#924)：
|
||||
|
||||
- 所有页面添加跳转到内容链接和 ARIA 地标角色
|
||||
- 所有交互组件（主题切换、标签页、侧边栏、文件树、下拉菜单、搜索、菜单）添加 ARIA 属性
|
||||
- 标签页和主题切换的键盘导航（方向键、Enter、Escape）
|
||||
- 支持 `prefers-reduced-motion` 和全局 `focus-visible` 样式
|
||||
- 15 个新的 i18n 无障碍键，在全部 21 个语言环境中提供完整翻译
|
||||
- 将所有硬编码的英文 `aria-label` 字符串替换为 i18n 查找
|
||||
|
||||
## 使用体验优化
|
||||
|
||||
- 改进表格可读性样式
|
||||
- 标题支持 Markdown 属性
|
||||
- 多语言章节着陆页的活动链接检测改进
|
||||
- 卡片短代码支持可选的图片 `alt` 参数
|
||||
- OpenGraph 元数据支持页面资源包图片
|
||||
- 内容宽度默认保持一致，支持通过 CSS 变量覆盖自定义布局
|
||||
|
||||
## 修复
|
||||
|
||||
- 修复 render-link 中 `relref` 基础前缀重复问题
|
||||
- 修复嵌套在步骤中的标签页渲染
|
||||
- 移动端侧边栏排序和标签与 `menu.main` 对齐
|
||||
- 侧边栏中遵循 `search.enable` 设置
|
||||
- 移动端下拉菜单中遵循 `toc` 页面参数
|
||||
- 增强 FlexSearch 匹配高亮和安全的 DOM 操作
|
||||
- 修复卡片副标题定位
|
||||
- 处理子路径部署中 OG 图片路径的前导斜杠
|
||||
- 修复 FlexSearch 返回结果页数少于预期的问题
|
||||
- 将 Umami 分析的默认文件改为 `script.js`
|
||||
- 修复 Hugo v0.156.0+ 的 RSS 作者查找 (`.Site.Params.Author`)
|
||||
|
||||
## 文档与 i18n
|
||||
|
||||
- 添加意大利语本地化
|
||||
- 链接 KaTeX 文档
|
||||
- 将 details 短代码文档更新为尖括号语法
|
||||
|
||||
## 贡献者
|
||||
|
||||
此版本由 11 位新贡献者共同参与完成：
|
||||
|
||||
- [@ghac101](https://github.com/ghac101) - Umami 分析修复、禁用上一篇/下一篇导航
|
||||
- [@pmarrapese](https://github.com/pmarrapese) - 标题 Markdown 属性支持
|
||||
- [@Bubbler-4](https://github.com/Bubbler-4) - details 短代码文档
|
||||
- [@bloovis](https://github.com/bloovis) - FlexSearch 结果计数修复
|
||||
- [@AntoninPvr](https://github.com/AntoninPvr) - 卡片副标题定位修复
|
||||
- [@illia-v](https://github.com/illia-v) - 移动端目录和搜索切换修复
|
||||
- [@gallochri](https://github.com/gallochri) - 意大利语本地化
|
||||
- [@MatheusFlausino](https://github.com/MatheusFlausino) - LLMs.txt 排除
|
||||
- [@daniseijo](https://github.com/daniseijo) - 最后修改作者功能
|
||||
- [@confusedkernel](https://github.com/confusedkernel) - 归档页面
|
||||
- [@Fenyutanchan](https://github.com/Fenyutanchan) - Hugo v0.156.0 RSS 作者兼容性修复
|
||||
|
||||
同时感谢回归贡献者 [@KStocky](https://github.com/KStocky)、[@ldez](https://github.com/ldez)、[@kowyo](https://github.com/kowyo)、[@torbjornbp](https://github.com/torbjornbp)、[@yuri1969](https://github.com/yuri1969) 和 [@PrintN](https://github.com/PrintN) 的持续贡献。
|
||||
|
||||
---
|
||||
|
||||
**完整变更日志**: https://github.com/imfing/hextra/compare/v0.11.1...v0.12.0
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
linkTitle: "مستندات"
|
||||
title: معرفی
|
||||
---
|
||||
|
||||
👋 سلام! به مستندات Hextra خوش آمدید!
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Hextra چیست؟
|
||||
|
||||
Hextra یک پوسته مدرن، سریع و کامل برای [Hugo][hugo] است که با [Tailwind CSS][tailwind-css] ساخته شده است.
|
||||
این پوسته برای ساخت وبسایتهای زیبا برای مستندات، وبلاگها و وبسایتها طراحی شده و امکاناتی را به صورت پیشفرض ارائه میدهد که انعطاف لازم برای پاسخگویی به نیازهای مختلف را دارد.
|
||||
|
||||
## ویژگیها
|
||||
|
||||
- **طراحی زیبا** - با الهام از Nextra، Hextra از Tailwind CSS استفاده میکند تا طراحی مدرنی ارائه دهد که سایت شما را برجسته میکند.
|
||||
- **چیدمان واکنشگرا و حالت تاریک** - در تمام دستگاهها از موبایل و تبلت تا دسکتاپ عالی به نظر میرسد. حالت تاریک نیز پشتیبانی میشود تا شرایط نوری مختلف را پوشش دهد.
|
||||
- **سریع و سبکوزن** - با قدرت Hugo، یک مولد سایت استاتیک فوقالعاده سریع که در یک فایل باینری واحد قرار دارد، Hextra ردپای کوچکی دارد. برای استفاده از آن نیازی به JavaScript یا Node.js نیست.
|
||||
- **جستجوی تماممتن** - جستجوی تماممتن آفلاین داخلی با قدرت FlexSearch، بدون نیاز به پیکربندی اضافی.
|
||||
- **کامل و آماده استفاده** - عناصر Markdown، برجستهسازی سینتکس، فرمولهای ریاضی LaTeX، نمودارها و Shortcodes برای غنیتر کردن محتوای شما. فهرست مطالب، مسیرهای ناوبری، صفحهبندی، نوار کناری و موارد دیگر همگی به صورت خودکار تولید میشوند.
|
||||
- **چندزبانه و آماده برای سئو** - ساخت سایتهای چندزبانه با حالت چندزبانه Hugo آسان شده است. پشتیبانی پیشفرض برای تگهای سئو، Open Graph و Twitter Cards وجود دارد.
|
||||
- **پشتیبانی از دسترسپذیری** - اجزای تعاملی از نشانهگذاری معنایی، رفتار سازگار با صفحهکلید و بررسیهای خودکار دسترسپذیری استفاده میکنند تا رابط کاربری در گردشکارهای رایج فناوریهای کمکی قابل استفاده بماند.
|
||||
|
||||
## سوال یا بازخورد دارید؟
|
||||
|
||||
{{< callout emoji="❓" >}}
|
||||
Hextra هنوز در حال توسعه فعال است.
|
||||
سوال یا بازخوردی دارید؟ با خیال راحت [یک issue باز کنید](https://github.com/imfing/hextra/issues)!
|
||||
{{< /callout >}}
|
||||
|
||||
## بعدی
|
||||
|
||||
برای شروع، مستقیماً به بخش زیر بروید:
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="getting-started" title="شروع به کار" icon="document-text" subtitle="یاد بگیرید چگونه با استفاده از Hextra وبسایت بسازید" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
[hugo]: https://gohugo.io/
|
||||
[flex-search]: https://github.com/nextapps-de/flexsearch
|
||||
[tailwind-css]: https://tailwindcss.com/
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
linkTitle: "ドキュメント"
|
||||
title: はじめに
|
||||
---
|
||||
|
||||
👋 こんにちは！Hextra ドキュメントへようこそ！
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Hextra とは？
|
||||
|
||||
Hextraは、[Tailwind CSS][tailwind-css]を使用して構築された、モダンで高速かつ機能豊富な[Hugo][hugo]テーマです。ドキュメンテーション、ブログ、ウェブサイトのための美しいウェブサイトを構築するために設計されており、さまざまな要件に対応するための機能と柔軟性を提供します。
|
||||
|
||||
## 特徴
|
||||
|
||||
- **美しいデザイン** - Nextra にインスパイアされ、Tailwind CSS を活用したモダンなデザインで、サイトを際立たせます。
|
||||
- **レスポンシブレイアウトとダークモード** - モバイル、タブレット、デスクトップなど、すべてのデバイスで美しく表示されます。また、さまざまな照明条件に対応するため、ダークモードもサポートされています。
|
||||
- **高速で軽量** - 単一のバイナリファイルで提供される超高速な静的サイトジェネレータ Hugo を採用しており、Hextra はフットプリントを最小限に抑えています。JavaScript や Node.js は必要ありません。
|
||||
- **全文検索** - FlexSearch を利用したオフライン全文検索が組み込まれており、追加の設定は不要です。
|
||||
- **バッテリーインクルード** - コンテンツを強化するための Markdown、シンタックスハイライト、LaTeX 数式、ダイアグラム、ショートコード要素が利用可能です。目次、パンくずリスト、ページネーション、サイドバーナビゲーションなどはすべて自動生成されます。
|
||||
- **多言語対応とSEO準備完了** - Hugo の多言語モードを利用して、多言語サイトを簡単に構築できます。SEO タグ、Open Graph、Twitter Cards のサポートも標準で提供されています。
|
||||
- **アクセシビリティ対応** - インタラクティブなコンポーネントは、意味論的なマークアップ、キーボードで使いやすい挙動、自動アクセシビリティチェックを備えており、一般的な支援技術の利用環境でも使いやすさを保ちます。
|
||||
|
||||
## 質問やフィードバック
|
||||
|
||||
{{< callout emoji="❓" >}}
|
||||
Hextra は現在も活発に開発中です。
|
||||
質問やフィードバックがありましたら、[issue を開いて](https://github.com/imfing/hextra/issues)ください！
|
||||
{{< /callout >}}
|
||||
|
||||
## 次に
|
||||
|
||||
以下のセクションから始めましょう：
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="getting-started" title="はじめに" icon="document-text" subtitle="Hextra を使ってウェブサイトを作成する方法を学ぶ" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
[hugo]: https://gohugo.io/
|
||||
[flex-search]: https://github.com/nextapps-de/flexsearch
|
||||
[tailwind-css]: https://tailwindcss.com/
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
linkTitle: "Documentation"
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
👋 Hello! Welcome to the Hextra documentation!
|
||||
|
||||
<!--more-->
|
||||
|
||||
## What is Hextra?
|
||||
|
||||
Hextra is a modern, fast and batteries-included [Hugo][hugo] theme built with [Tailwind CSS][tailwind-css].
|
||||
Designed for building beautiful websites for documentation, blogs, and websites, it provides out-of-the-box features and flexibility to meet various requirements.
|
||||
|
||||
## Features
|
||||
|
||||
- **Beautiful Design** - Inspired by Nextra, Hextra utilizes Tailwind CSS to offer a modern design that makes your site look outstanding.
|
||||
- **Responsive Layout and Dark Mode** - It looks great on all devices, from mobile, tablet to desktop. Dark mode is also supported to accommodate various lighting conditions.
|
||||
- **Fast and Lightweight** - Powered by Hugo, a lightning-fast static-site generator housed in a single binary file, Hextra keeps its footprint minimal. No JavaScript or Node.js are needed to use it.
|
||||
- **Full-text Search** - Built-in offline full-text search powered by FlexSearch, no additional configuration required.
|
||||
- **Battery-included** - Markdown, syntax highlighting, LaTeX math formulae, diagrams and Shortcodes elements to enhance your content. Table of contents, breadcrumbs, pagination, sidebar navigation and more are all automatically generated.
|
||||
- **Multi-language and SEO Ready** - Multi-language sites made easy with Hugo's multilingual mode. Out-of-the-box support is included for SEO tags, Open Graph, and Twitter Cards.
|
||||
- **Accessibility Support** - Interactive components use semantic markup, keyboard-friendly behavior, and automated accessibility checks to keep the UI usable across common assistive workflows.
|
||||
|
||||
## Questions or Feedback?
|
||||
|
||||
{{< callout emoji="❓" >}}
|
||||
Hextra is still in active development.
|
||||
Have a question or feedback? Feel free to [open an issue](https://github.com/imfing/hextra/issues)!
|
||||
{{< /callout >}}
|
||||
|
||||
## Next
|
||||
|
||||
Dive right into the following section to get started:
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="getting-started" title="Getting Started" icon="document-text" subtitle="Learn how to create website using Hextra" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
[hugo]: https://gohugo.io/
|
||||
[flex-search]: https://github.com/nextapps-de/flexsearch
|
||||
[tailwind-css]: https://tailwindcss.com/
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
linkTitle: "文档"
|
||||
title: 简介
|
||||
---
|
||||
|
||||
👋 你好！欢迎来到 Hextra 文档中心！
|
||||
|
||||
<!--more-->
|
||||
|
||||
## 什么是 Hextra？
|
||||
|
||||
Hextra 是一个基于 [Tailwind CSS][tailwind-css] 构建的现代化、高性能且开箱即用的 [Hugo][hugo] 主题。专为打造文档、博客和网站而设计，它提供丰富的内置功能和灵活配置，满足多样化需求。
|
||||
|
||||
## 核心特性
|
||||
|
||||
- **精美设计** - 灵感源自 Nextra，采用 Tailwind CSS 实现现代美学，让您的站点脱颖而出。
|
||||
- **响应式布局与暗黑模式** - 完美适配移动设备、平板及桌面端，并支持根据环境光线自动切换的暗黑模式。
|
||||
- **极速轻量** - 依托 Hugo 静态网站生成器的单文件二进制架构，无需 JavaScript 或 Node.js 环境即可运行。
|
||||
- **全文搜索** - 内置基于 FlexSearch 的离线全文搜索功能，零配置开箱即用。
|
||||
- **功能完备** - 支持 Markdown 语法高亮、LaTeX 数学公式、图表和 Shortcodes 等丰富内容元素。自动生成目录导航、面包屑、分页及侧边栏等组件。
|
||||
- **多语言与 SEO 友好** - 通过 Hugo 多语言模式轻松构建国际化站点，原生集成 SEO 标签、Open Graph 和 Twitter Cards 支持。
|
||||
- **无障碍支持** - 交互组件使用语义化标记、友好的键盘交互以及自动化无障碍检查，以便在常见辅助技术工作流中保持良好的可用性。
|
||||
|
||||
## 问题或建议？
|
||||
|
||||
{{< callout emoji="❓" >}}
|
||||
Hextra 仍在积极开发中。
|
||||
如有疑问或反馈，欢迎[提交 Issue](https://github.com/imfing/hextra/issues)！
|
||||
{{< /callout >}}
|
||||
|
||||
## 下一步
|
||||
|
||||
立即开始探索：
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="getting-started" title="快速开始" icon="document-text" subtitle="学习如何使用 Hextra 创建网站" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
[hugo]: https://gohugo.io/
|
||||
[flex-search]: https://github.com/nextapps-de/flexsearch
|
||||
[tailwind-css]: https://tailwindcss.com/
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
linkTitle: پیشرفته
|
||||
title: مباحث پیشرفته
|
||||
prev: /docs/guide/shortcodes/tabs
|
||||
next: /docs/advanced/multi-language
|
||||
---
|
||||
|
||||
این بخش برخی از مباحث پیشرفته این پوسته را پوشش میدهد.
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="multi-language" title="چندزبانه" icon="translate" >}}
|
||||
{{< card link="customization" title="سفارشیسازی" icon="pencil" >}}
|
||||
{{< card link="comments" title="سیستم نظرات" icon="chat-alt" >}}
|
||||
{{< card link="additional-pages" title="صفحات اضافی" icon="library" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
linkTitle: 高度な設定
|
||||
title: 高度なトピック
|
||||
prev: /docs/guide/shortcodes/tabs
|
||||
next: /docs/advanced/multi-language
|
||||
---
|
||||
|
||||
このセクションでは、テーマの高度なトピックについて説明します。
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="multi-language" title="多言語対応" icon="translate" >}}
|
||||
{{< card link="customization" title="カスタマイズ" icon="pencil" >}}
|
||||
{{< card link="comments" title="コメントシステム" icon="chat-alt" >}}
|
||||
{{< card link="additional-pages" title="追加ページ" icon="library" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
linkTitle: Advanced
|
||||
title: Advanced Topics
|
||||
prev: /docs/guide/shortcodes/tabs
|
||||
next: /docs/advanced/multi-language
|
||||
---
|
||||
|
||||
This section covers some advanced topics of the theme.
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< cards >}}
|
||||
{{< 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="additional-pages" title="Additional Pages" icon="library" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
linkTitle: 高级
|
||||
title: 高级主题
|
||||
prev: /docs/guide/shortcodes/tabs
|
||||
next: /docs/advanced/multi-language
|
||||
---
|
||||
|
||||
本节涵盖该主题的一些高级内容。
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="multi-language" title="多语言支持" icon="translate" >}}
|
||||
{{< card link="customization" title="自定义配置" icon="pencil" >}}
|
||||
{{< card link="comments" title="评论系统" icon="chat-alt" >}}
|
||||
{{< card link="additional-pages" title="附加页面" icon="library" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: "صفحات اضافی"
|
||||
weight: 1
|
||||
prev: /docs/advanced
|
||||
aliases:
|
||||
- /docs/advanced/glossary/
|
||||
---
|
||||
|
||||
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: "موتورهایی که ورودی متنی را پردازش کرده و صفحات وب ایستا تولید میکنند"
|
||||
```
|
||||
|
||||
### صفحهٔ واژهنامه
|
||||
|
||||
برای رندر شدن صفحهٔ نمایهٔ واژهنامه (که شامل فهرست تمام اصطلاحات تعریفشده بههمراه توضیحات و مخففهای آنهاست)،
|
||||
باید برای هر زبان پشتیبانیشده یک فایل محتوای واژهنامهٔ مخصوص همان زبان تعریف شود.
|
||||
در نام فایل از پسوند کد زبان استفاده کنید؛ برای مثال: `content/glossary/_index.fa.md`.
|
||||
|
||||
```markdown {filename="content/glossary/_index.fa.md"}
|
||||
---
|
||||
title: واژهنامه
|
||||
layout: glossary
|
||||
---
|
||||
```
|
||||
|
||||
یک صفحهٔ نمونه از واژهنامه در [واژهنامه]({{% relref "/glossary" %}}) در دسترس است.
|
||||
|
||||
## آرشیو
|
||||
|
||||
میتوانید برای نوشتههای یک بخش، یک صفحه آرشیو زمانی (گروهبندیشده بر اساس سال) بسازید.
|
||||
|
||||
1. صفحه آرشیو را ایجاد کنید:
|
||||
```yaml {filename="content/archives/_index.md"}
|
||||
---
|
||||
title: Archives
|
||||
layout: archives
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
2. (اختیاری) آن را به منوی بالا اضافه کنید:
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: archives
|
||||
name: Archives
|
||||
pageRef: /archives
|
||||
```
|
||||
3. (اختیاری، چندزبانه) فایلهای آرشیو ترجمهشده با همان layout اضافه کنید، برای مثال:
|
||||
- `content/archives/_index.fa.md`
|
||||
- `content/archives/_index.ja.md`
|
||||
- `content/archives/_index.zh-cn.md`
|
||||
4. (اختیاری) بخش مورد استفاده برای آرشیو را تغییر دهید. مقدار پیشفرض `blog` است.
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
archives:
|
||||
section: blog
|
||||
```
|
||||
5. (اختیاری) قالب نمایش تاریخ آیتمهای آرشیو را تغییر دهید. مقدار پیشفرض `Jan 02` است.
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
archives:
|
||||
dateFormat: "Jan 02"
|
||||
```
|
||||
|
||||
پیام حالت خالی از کلید ترجمه `noResultsFound` استفاده میکند.
|
||||
|
||||
یک صفحهٔ نمونه از آرشیو در [آرشیو]({{% relref "/archives" %}}) در دسترس است.
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: "追加ページ"
|
||||
weight: 1
|
||||
prev: /docs/advanced
|
||||
aliases:
|
||||
- /docs/advanced/glossary/
|
||||
---
|
||||
|
||||
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: "テキスト入力を処理して静的なウェブページを生成するソフトウェアエンジン"
|
||||
```
|
||||
|
||||
### 用語ページ
|
||||
|
||||
定義済みの用語、その説明、および略語を一覧表示するグロッサリーのインデックスページをレンダリングするには、
|
||||
サポートされている各言語ごとに、言語固有のグロッサリー用コンテンツファイルを定義する必要があります。
|
||||
ファイル名には言語コードのサフィックスを使用してください。例: `content/glossary/_index.ja.md`。
|
||||
|
||||
```markdown {filename="content/glossary/_index.ja.md"}
|
||||
---
|
||||
title: 用語集
|
||||
layout: glossary
|
||||
---
|
||||
```
|
||||
|
||||
グロッサリーのサンプルページは [用語集]({{% relref "/glossary" %}}) で確認できます。
|
||||
|
||||
## アーカイブ
|
||||
|
||||
投稿を年ごとにまとめたアーカイブタイムラインページを作成できます。
|
||||
|
||||
1. アーカイブページを作成します：
|
||||
```yaml {filename="content/archives/_index.md"}
|
||||
---
|
||||
title: Archives
|
||||
layout: archives
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
2. （任意）トップメニューに追加します：
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: archives
|
||||
name: Archives
|
||||
pageRef: /archives
|
||||
```
|
||||
3. （任意・多言語）同じ layout を使った翻訳版アーカイブページを追加します。例：
|
||||
- `content/archives/_index.fa.md`
|
||||
- `content/archives/_index.ja.md`
|
||||
- `content/archives/_index.zh-cn.md`
|
||||
4. （任意）アーカイブ対象のセクションを変更します。デフォルトは `blog` です。
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
archives:
|
||||
section: blog
|
||||
```
|
||||
5. （任意）アーカイブ項目の日付表示形式を変更します。デフォルトは `Jan 02` です。
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
archives:
|
||||
dateFormat: "Jan 02"
|
||||
```
|
||||
|
||||
空状態メッセージは i18n キー `noResultsFound` を使用します。
|
||||
|
||||
アーカイブのサンプルページは [アーカイブ]({{% relref "/archives" %}}) で確認できます。
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: "Additional Pages"
|
||||
weight: 1
|
||||
prev: /docs/advanced
|
||||
aliases:
|
||||
- /docs/advanced/glossary/
|
||||
---
|
||||
|
||||
Hextra includes additional pages that you can enable explicitly: glossary and archives.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Glossary
|
||||
|
||||
{{< 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
|
||||
|
||||
To render the glossary index page (listing all defined terms along with their descriptions and abbreviations),
|
||||
a language-specific glossary content file must be defined for each supported language. Use the language code suffix
|
||||
in the filename, for example `content/glossary/_index.en.md`.
|
||||
|
||||
```markdown {filename="content/glossary/_index.en.md"}
|
||||
---
|
||||
title: Glossary
|
||||
layout: glossary
|
||||
---
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
1. Create the archive page:
|
||||
```yaml {filename="content/archives/_index.md"}
|
||||
---
|
||||
title: Archives
|
||||
layout: archives
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
2. (Optional) Add it to the top menu:
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: archives
|
||||
name: Archives
|
||||
pageRef: /archives
|
||||
```
|
||||
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`.
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
archives:
|
||||
section: blog
|
||||
```
|
||||
5. (Optional) Change the archive item date format. The default is `Jan 02`.
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
archives:
|
||||
dateFormat: "Jan 02"
|
||||
```
|
||||
|
||||
The empty-state message uses the `noResultsFound` i18n key.
|
||||
|
||||
An example archive page is available at [Archives]({{% relref "/archives" %}}).
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: "附加页面"
|
||||
weight: 1
|
||||
prev: /docs/advanced
|
||||
aliases:
|
||||
- /docs/advanced/glossary/
|
||||
---
|
||||
|
||||
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: "将文本输入处理为静态网页的生成引擎"
|
||||
```
|
||||
|
||||
### 术语页面
|
||||
|
||||
要渲染词汇表索引页面（列出所有已定义的术语及其说明和缩写），
|
||||
必须为每种受支持的语言定义一个对应的语言专用词汇表内容文件。
|
||||
请在文件名中使用语言代码后缀，例如：`content/glossary/_index.zh-cn.md`。
|
||||
|
||||
```markdown {filename="content/glossary/_index.zh-cn.md"}
|
||||
---
|
||||
title: 术语表
|
||||
layout: glossary
|
||||
---
|
||||
```
|
||||
|
||||
示例词汇表页面可在 [术语表]({{% relref "/glossary" %}}) 查看。
|
||||
|
||||
## 归档页
|
||||
|
||||
你可以为某个内容分区的文章创建按年份分组的归档时间线页面。
|
||||
|
||||
1. 创建归档页面：
|
||||
```yaml {filename="content/archives/_index.md"}
|
||||
---
|
||||
title: Archives
|
||||
layout: archives
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
2. （可选）将其添加到顶部菜单：
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: archives
|
||||
name: Archives
|
||||
pageRef: /archives
|
||||
```
|
||||
3. （可选，多语言）添加使用相同 layout 的多语言归档首页，例如：
|
||||
- `content/archives/_index.fa.md`
|
||||
- `content/archives/_index.ja.md`
|
||||
- `content/archives/_index.zh-cn.md`
|
||||
4. （可选）修改归档来源分区。默认值为 `blog`。
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
archives:
|
||||
section: blog
|
||||
```
|
||||
5. （可选）修改归档条目的日期显示格式。默认值是 `Jan 02`。
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
archives:
|
||||
dateFormat: "Jan 02"
|
||||
```
|
||||
|
||||
空状态文案使用 i18n 键 `noResultsFound`。
|
||||
|
||||
示例归档页面可在 [归档]({{% relref "/archives" %}}) 查看。
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: سیستم نظرات
|
||||
linkTitle: نظرات
|
||||
---
|
||||
|
||||
Hextra از افزودن سیستم نظرات به سایت شما پشتیبانی میکند.
|
||||
در حال حاضر [giscus](https://giscus.app/) پشتیبانی میشود.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## giscus
|
||||
|
||||
[giscus](https://giscus.app/) یک سیستم نظرات است که توسط [GitHub Discussions](https://docs.github.com/en/discussions) قدرت میگیرد. این سیستم رایگان و متنباز است.
|
||||
|
||||
برای فعال کردن giscus، باید موارد زیر را به فایل پیکربندی سایت اضافه کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
comments:
|
||||
enable: false
|
||||
type: giscus
|
||||
|
||||
giscus:
|
||||
repo: <repository>
|
||||
repoId: <repository ID>
|
||||
category: <category>
|
||||
categoryId: <category ID>
|
||||
```
|
||||
|
||||
تنظیمات giscus را میتوان از وبسایت [giscus.app](https://giscus.app/) ساخت. جزئیات بیشتر نیز در آنجا موجود است.
|
||||
|
||||
میتوان نظرات را برای یک صفحه خاص در front matter صفحه فعال یا غیرفعال کرد:
|
||||
|
||||
```yaml {filename="content/docs/about.md"}
|
||||
---
|
||||
title: درباره
|
||||
comments: true
|
||||
---
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: コメントシステム
|
||||
linkTitle: コメント
|
||||
---
|
||||
|
||||
Hextra はサイトにコメントシステムを追加する機能をサポートしています。
|
||||
現在 [giscus](https://giscus.app/) が利用可能です。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## giscus
|
||||
|
||||
[giscus](https://giscus.app/) は [GitHub Discussions](https://docs.github.com/ja/discussions) を利用したコメントシステムです。無料でオープンソースです。
|
||||
|
||||
giscus を有効にするには、サイト設定ファイルに以下を追加してください:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
comments:
|
||||
enable: false
|
||||
type: giscus
|
||||
|
||||
giscus:
|
||||
repo: <リポジトリ>
|
||||
repoId: <リポジトリID>
|
||||
category: <カテゴリ>
|
||||
categoryId: <カテゴリID>
|
||||
```
|
||||
|
||||
giscus の設定は [giscus.app](https://giscus.app/) ウェブサイトから構築できます。詳細もそちらで確認できます。
|
||||
|
||||
特定のページでコメントを有効/無効にするには、ページのフロントマターで設定します:
|
||||
|
||||
```yaml {filename="content/docs/about.md"}
|
||||
---
|
||||
title: このサイトについて
|
||||
comments: true
|
||||
---
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Comments System
|
||||
linkTitle: Comments
|
||||
---
|
||||
|
||||
Hextra supports adding comments system to your site.
|
||||
Currently [giscus](https://giscus.app/) is supported.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## giscus
|
||||
|
||||
[giscus](https://giscus.app/) is a comments system powered by [GitHub Discussions](https://docs.github.com/en/discussions). It is free and open source.
|
||||
|
||||
To enable giscus, you need to add the following to the site configuration file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
comments:
|
||||
enable: false
|
||||
type: giscus
|
||||
|
||||
giscus:
|
||||
repo: <repository>
|
||||
repoId: <repository ID>
|
||||
category: <category>
|
||||
categoryId: <category ID>
|
||||
```
|
||||
|
||||
The giscus configurations can be constructed from the [giscus.app](https://giscus.app/) website. More details can also be found there.
|
||||
|
||||
Comments can be enabled or disabled for a specific page in the page front matter:
|
||||
|
||||
```yaml {filename="content/docs/about.md"}
|
||||
---
|
||||
title: About
|
||||
comments: true
|
||||
---
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: 评论系统
|
||||
linkTitle: 评论
|
||||
---
|
||||
|
||||
Hextra 支持为您的网站添加评论系统。
|
||||
目前支持 [giscus](https://giscus.app/)。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## giscus
|
||||
|
||||
[giscus](https://giscus.app/) 是一个由 [GitHub Discussions](https://docs.github.com/en/discussions) 驱动的评论系统。它是免费且开源的。
|
||||
|
||||
要启用 giscus，您需要在网站配置文件中添加以下内容：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
comments:
|
||||
enable: false
|
||||
type: giscus
|
||||
|
||||
giscus:
|
||||
repo: <仓库>
|
||||
repoId: <仓库 ID>
|
||||
category: <分类>
|
||||
categoryId: <分类 ID>
|
||||
```
|
||||
|
||||
giscus 的配置可以从 [giscus.app](https://giscus.app/) 网站生成。更多详情也可以在那里找到。
|
||||
|
||||
可以在页面的 front matter 中为特定页面启用或禁用评论：
|
||||
|
||||
```yaml {filename="content/docs/about.md"}
|
||||
---
|
||||
title: 关于
|
||||
comments: true
|
||||
---
|
||||
```
|
||||
@@ -0,0 +1,251 @@
|
||||
---
|
||||
title: سفارشیسازی Hextra
|
||||
linkTitle: سفارشیسازی
|
||||
---
|
||||
|
||||
Hextra برخی گزینههای پیشفرض سفارشیسازی را در فایل پیکربندی `hugo.yaml` ارائه میدهد تا تم را پیکربندی کنید.
|
||||
این صفحه گزینههای موجود و نحوه سفارشیسازی بیشتر تم را توضیح میدهد.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## CSS سفارشی
|
||||
|
||||
برای افزودن CSS سفارشی، باید یک فایل `assets/css/custom.css` در سایت خود ایجاد کنیم. Hextra به طور خودکار این فایل را بارگذاری میکند.
|
||||
|
||||
### خانواده فونت
|
||||
|
||||
خانواده فونت محتوا را میتوان با استفاده از موارد زیر سفارشی کرد:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.content {
|
||||
font-family: "Times New Roman", Times, serif;
|
||||
}
|
||||
```
|
||||
|
||||
### عنصر کد درون خطی
|
||||
|
||||
رنگ متن مخلوط شده با `متن دیگر` را میتوان با موارد زیر سفارشی کرد:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.content code:not(.code-block code) {
|
||||
color: #c97c2e;
|
||||
}
|
||||
```
|
||||
|
||||
### رنگ اصلی
|
||||
|
||||
رنگ اصلی تم را میتوان با تنظیم متغیرهای `--primary-hue`، `--primary-saturation` و `--primary-lightness` سفارشی کرد:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
--primary-hue: 100deg;
|
||||
--primary-saturation: 90%;
|
||||
--primary-lightness: 50%;
|
||||
}
|
||||
```
|
||||
|
||||
### متغیرهای چیدمان کامپوننت
|
||||
|
||||
Hextra متغیرهای CSS را برای سفارشیسازی عرض صفحات، نوار ناوبری و پاورقی ارائه میدهد:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
/* عرض صفحه - همچنین از طریق params.page.width در hugo.yaml قابل پیکربندی است */
|
||||
--hextra-max-page-width: 80rem; /* پیشفرض: 80rem (نرمال)، 90rem (عریض)، 100% (کامل) */
|
||||
|
||||
/* عرض نوار ناوبری - همچنین از طریق params.navbar.width در hugo.yaml قابل پیکربندی است */
|
||||
--hextra-max-navbar-width: 90rem; /* عرض مستقل نوار ناوبری */
|
||||
|
||||
/* عرض پاورقی - همچنین از طریق params.footer.width در hugo.yaml قابل پیکربندی است */
|
||||
--hextra-max-footer-width: 80rem; /* عرض مستقل پاورقی */
|
||||
}
|
||||
```
|
||||
|
||||
### متغیرهای تم Tailwind
|
||||
|
||||
با شروع از Hextra v0.10.0 که بر پایه Tailwind CSS v4 ساخته شده است، میتوانید تم را با بازنویسی متغیرهای CSS در بلوک `@layer theme` سفارشی کنید.
|
||||
|
||||
این به شما امکان میدهد ظاهر کلی را بدون نیاز به تغییر هر کلاس به صورت جداگانه سفارشی کنید.
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
@layer theme {
|
||||
:root {
|
||||
--hx-default-mono-font-family: "JetBrains Mono", monospace;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
برای جزئیات بیشتر، [مستندات متغیرهای تم Tailwind](https://tailwindcss.com/docs/theme#default-theme-variable-reference) را بررسی کنید.
|
||||
|
||||
### سفارشیسازی بیشتر تم
|
||||
|
||||
تم را میتوان با بازنویسی استایلهای پیشفرض از طریق کلاسهای CSS در معرض، بیشتر سفارشی کرد. مثالی برای سفارشیسازی عنصر پاورقی:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.hextra-footer {
|
||||
/* استایلها روی عنصر پاورقی اعمال میشوند */
|
||||
}
|
||||
|
||||
.hextra-footer:is(html[class~="dark"] *) {
|
||||
/* استایلها روی عنصر پاورقی در حالت تاریک اعمال میشوند */
|
||||
}
|
||||
```
|
||||
|
||||
از کلاسهای زیر میتوان برای سفارشیسازی بخشهای مختلف تم استفاده کرد.
|
||||
|
||||
#### عمومی
|
||||
|
||||
- `hextra-scrollbar` - عنصر نوار پیمایش
|
||||
- `content` - ظرف محتوای صفحه
|
||||
|
||||
#### شورتکدها
|
||||
|
||||
##### نشان
|
||||
|
||||
- `hextra-badge` - عنصر نشان
|
||||
|
||||
##### کارت
|
||||
|
||||
- `hextra-card` - عنصر کارت
|
||||
- `hextra-card-image` - عنصر تصویر کارت
|
||||
- `hextra-card-icon` - عنصر آیکون کارت
|
||||
- `hextra-card-subtitle` - عنصر زیرنویس کارت
|
||||
|
||||
##### کارتها
|
||||
|
||||
- `hextra-cards` - ظرف شبکهای کارتها
|
||||
|
||||
##### نوتبوک Jupyter
|
||||
|
||||
- `hextra-jupyter-code-cell` - ظرف سلول کد Jupyter
|
||||
- `hextra-jupyter-code-cell-outputs-container` - ظرف خروجیهای سلول کد Jupyter
|
||||
- `hextra-jupyter-code-cell-outputs` - عنصر div خروجی سلول کد Jupyter
|
||||
|
||||
##### PDF
|
||||
|
||||
- `hextra-pdf` - عنصر ظرف PDF
|
||||
|
||||
##### مراحل
|
||||
|
||||
- `hextra-steps` - ظرف مراحل
|
||||
|
||||
##### تبها
|
||||
|
||||
- `hextra-tabs-panel` - ظرف پنل تبها
|
||||
- `hextra-tabs-toggle` - دکمه تغییر تبها
|
||||
|
||||
##### درخت فایل
|
||||
|
||||
- `hextra-filetree` - ظرف درخت فایل
|
||||
|
||||
##### پوشه
|
||||
|
||||
- `hextra-filetree-folder` - ظرف پوشه درخت فایل
|
||||
|
||||
#### نوار ناوبری
|
||||
|
||||
- `hextra-nav-container` - ظرف نوار ناوبری
|
||||
- `hextra-nav-container-blur` - عنصر ظرف نوار ناوبری در حالت محو
|
||||
- `hextra-hamburger-menu` - دکمه منوی همبرگری
|
||||
|
||||
#### پاورقی
|
||||
|
||||
- `hextra-footer` - عنصر پاورقی
|
||||
- `hextra-custom-footer` - ظرف بخش پاورقی سفارشی
|
||||
|
||||
#### جستجو
|
||||
|
||||
- `hextra-search-wrapper` - ظرف wrapper جستجو
|
||||
- `hextra-search-input` - عنصر ورودی جستجو
|
||||
- `hextra-search-results` - ظرف لیست نتایج جستجو
|
||||
|
||||
کلاسهای تو در تو اختیاری مورد استفاده در رابط کاربری جستجو:
|
||||
|
||||
- `hextra-search-title` - عنصر عنوان نتیجه
|
||||
- `hextra-search-active` - لنکر نتیجه فعال
|
||||
- `hextra-search-no-result` - عنصر حالت خالی
|
||||
- `hextra-search-prefix` - برچسب مسیر/پیشوند برای نتایج گروهبندی شده
|
||||
- `hextra-search-excerpt` - متن خلاصه نتیجه
|
||||
- `hextra-search-match` - span پرس و جوی هایلایت شده
|
||||
|
||||
#### فهرست مطالب
|
||||
|
||||
- `hextra-toc` - ظرف فهرست مطالب
|
||||
|
||||
#### نوار کناری
|
||||
|
||||
- `hextra-sidebar-container` - ظرف نوار کناری
|
||||
- `hextra-sidebar-active-item` - آیتم فعال در نوار کناری
|
||||
|
||||
#### تغییردهنده زبان
|
||||
|
||||
- `hextra-language-switcher` - دکمه تغییردهنده زبان
|
||||
- `hextra-language-options` - ظرف گزینههای زبان
|
||||
|
||||
#### تغییردهنده تم
|
||||
|
||||
- `hextra-theme-toggle` - دکمه تغییر تم
|
||||
|
||||
#### دکمه کپی کد
|
||||
|
||||
- `hextra-code-copy-btn-container` - ظرف دکمه کپی کد
|
||||
- `hextra-code-copy-btn` - دکمه کپی کد
|
||||
- `hextra-copy-icon` - عنصر آیکون کپی
|
||||
- `hextra-success-icon` - عنصر آیکون موفقیت
|
||||
|
||||
#### بلوک کد
|
||||
|
||||
- `hextra-code-block` - ظرف بلوک کد
|
||||
- `hextra-code-filename` - عنصر نام فایل برای بلوکهای کد
|
||||
|
||||
#### کارت ویژگی
|
||||
|
||||
- `hextra-feature-card` - عنصر لینک کارت ویژگی
|
||||
|
||||
#### شبکه ویژگی
|
||||
|
||||
- `hextra-feature-grid` - ظرف شبکه ویژگی
|
||||
|
||||
#### هایلایت سینتکس
|
||||
|
||||
لیست تمهای هایلایت سینتکس موجود در [گالری استایلهای Chroma](https://xyproto.github.io/splash/docs/all.html) قابل مشاهده است. برگه استایل را میتوان با دستور زیر تولید کرد:
|
||||
|
||||
```shell
|
||||
hugo gen chromastyles --style=github
|
||||
```
|
||||
|
||||
برای بازنویسی تم پیشفرض هایلایت سینتکس، میتوانیم استایلهای تولید شده را به فایل CSS سفارشی اضافه کنیم.
|
||||
|
||||
## اسکریپتهای سفارشی
|
||||
|
||||
میتوانید اسکریپتهای سفارشی را به انتهای head برای هر صفحه با افزودن فایل زیر اضافه کنید:
|
||||
|
||||
```
|
||||
layouts/_partials/custom/head-end.html
|
||||
```
|
||||
|
||||
## بخش اضافی سفارشی در پاورقی
|
||||
|
||||
میتوانید بخش اضافی در پاورقی با ایجاد یک فایل `layouts/_partials/custom/footer.html` در سایت خود اضافه کنید.
|
||||
|
||||
```html {filename="layouts/_partials/custom/footer.html"}
|
||||
<!-- عنصر پاورقی شما اینجا -->
|
||||
```
|
||||
|
||||
بخش اضافه شده قبل از بخش کپیرایت در پاورقی اضافه میشود.
|
||||
میتوانید از [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) و [سینتکس قالب Hugo](https://gohugo.io/templates/) برای افزودن محتوای خود استفاده کنید.
|
||||
|
||||
متغیرهای Hugo موجود در بخش پاورقی عبارتند از: `.switchesVisible` و `.displayCopyright`.
|
||||
|
||||
## چیدمانهای سفارشی
|
||||
|
||||
چیدمانهای تم را میتوان با ایجاد یک فایل با همان نام در دایرکتوری `layouts` سایت خود بازنویسی کرد.
|
||||
به عنوان مثال، برای بازنویسی چیدمان `single.html` برای مستندات، یک فایل `layouts/docs/single.html` در سایت خود ایجاد کنید.
|
||||
|
||||
برای اطلاعات بیشتر، به [مستندات قالبهای Hugo][hugo-template-docs] مراجعه کنید.
|
||||
|
||||
## سفارشیسازی بیشتر
|
||||
|
||||
آیا آنچه را که به دنبالش بودید پیدا نکردید؟ با خیال راحت [یک بحث باز کنید](https://github.com/imfing/hextra/discussions) یا به تم کمک کنید!
|
||||
|
||||
[hugo-template-docs]: https://gohugo.io/templates/
|
||||
@@ -0,0 +1,251 @@
|
||||
---
|
||||
title: Hextraのカスタマイズ
|
||||
linkTitle: カスタマイズ
|
||||
---
|
||||
|
||||
Hextraは、`hugo.yaml`設定ファイル内でテーマを設定するためのデフォルトのカスタマイズオプションを提供しています。
|
||||
このページでは、利用可能なオプションとテーマをさらにカスタマイズする方法について説明します。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## カスタムCSS
|
||||
|
||||
カスタムCSSを追加するには、サイト内に`assets/css/custom.css`ファイルを作成します。Hextraはこのファイルを自動的に読み込みます。
|
||||
|
||||
### フォントファミリー
|
||||
|
||||
コンテンツのフォントファミリーは以下のようにカスタマイズできます:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.content {
|
||||
font-family: "Times New Roman", Times, serif;
|
||||
}
|
||||
```
|
||||
|
||||
### インラインコード要素
|
||||
|
||||
`他のテキスト`と混在するテキストの色は以下のようにカスタマイズできます:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.content code:not(.code-block code) {
|
||||
color: #c97c2e;
|
||||
}
|
||||
```
|
||||
|
||||
### プライマリカラー
|
||||
|
||||
テーマのプライマリカラーは、`--primary-hue`、`--primary-saturation`、`--primary-lightness`変数を設定することでカスタマイズできます:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
--primary-hue: 100deg;
|
||||
--primary-saturation: 90%;
|
||||
--primary-lightness: 50%;
|
||||
}
|
||||
```
|
||||
|
||||
### コンポーネントレイアウト変数
|
||||
|
||||
Hextraは、ページ、ナビゲーションバー、フッターの幅をカスタマイズするためのCSS変数を提供しています:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
/* ページ幅 - hugo.yamlのparams.page.widthでも設定可能 */
|
||||
--hextra-max-page-width: 80rem; /* デフォルト: 80rem (標準), 90rem (ワイド), 100% (フル) */
|
||||
|
||||
/* ナビゲーションバー幅 - hugo.yamlのparams.navbar.widthでも設定可能 */
|
||||
--hextra-max-navbar-width: 90rem; /* 独立したナビゲーションバー幅 */
|
||||
|
||||
/* フッター幅 - hugo.yamlのparams.footer.widthでも設定可能 */
|
||||
--hextra-max-footer-width: 80rem; /* 独立したフッター幅 */
|
||||
}
|
||||
```
|
||||
|
||||
### Tailwindテーマ変数
|
||||
|
||||
Tailwind CSS v4をベースにしたHextra v0.10.0以降では、`@layer theme`ブロック内でCSS変数をオーバーライドすることでテーマをカスタマイズできます。
|
||||
|
||||
これにより、個々のクラスを変更することなく、グローバルな外観をカスタマイズできます。
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
@layer theme {
|
||||
:root {
|
||||
--hx-default-mono-font-family: "JetBrains Mono", monospace;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
詳細については、[Tailwindテーマ変数のドキュメント](https://tailwindcss.com/docs/theme#default-theme-variable-reference)を参照してください。
|
||||
|
||||
### さらなるテーマカスタマイズ
|
||||
|
||||
テーマは、公開されているCSSクラスをオーバーライドすることでさらにカスタマイズできます。フッター要素をカスタマイズする例:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.hextra-footer {
|
||||
/* フッター要素に適用されるスタイル */
|
||||
}
|
||||
|
||||
.hextra-footer:is(html[class~="dark"] *) {
|
||||
/* ダークモードでのフッター要素に適用されるスタイル */
|
||||
}
|
||||
```
|
||||
|
||||
以下のクラスを使用して、テーマのさまざまな部分をカスタマイズできます。
|
||||
|
||||
#### 一般
|
||||
|
||||
- `hextra-scrollbar` - スクロールバー要素
|
||||
- `content` - ページコンテンツコンテナ
|
||||
|
||||
#### ショートコード
|
||||
|
||||
##### バッジ
|
||||
|
||||
- `hextra-badge` - バッジ要素
|
||||
|
||||
##### カード
|
||||
|
||||
- `hextra-card` - カード要素
|
||||
- `hextra-card-image` - カード画像要素
|
||||
- `hextra-card-icon` - カードアイコン要素
|
||||
- `hextra-card-subtitle` - カードサブタイトル要素
|
||||
|
||||
##### カードグリッド
|
||||
|
||||
- `hextra-cards` - カードグリッドコンテナ
|
||||
|
||||
##### Jupyter Notebook
|
||||
|
||||
- `hextra-jupyter-code-cell` - Jupyterコードセルコンテナ
|
||||
- `hextra-jupyter-code-cell-outputs-container` - Jupyterコードセル出力コンテナ
|
||||
- `hextra-jupyter-code-cell-outputs` - Jupyterコードセル出力div要素
|
||||
|
||||
##### PDF
|
||||
|
||||
- `hextra-pdf` - PDFコンテナ要素
|
||||
|
||||
##### ステップ
|
||||
|
||||
- `hextra-steps` - ステップコンテナ
|
||||
|
||||
##### タブ
|
||||
|
||||
- `hextra-tabs-panel` - タブパネルコンテナ
|
||||
- `hextra-tabs-toggle` - タブトグルボタン
|
||||
|
||||
##### ファイルツリー
|
||||
|
||||
- `hextra-filetree` - ファイルツリーコンテナ
|
||||
|
||||
##### フォルダ
|
||||
|
||||
- `hextra-filetree-folder` - ファイルツリーフォルダコンテナ
|
||||
|
||||
#### ナビゲーションバー
|
||||
|
||||
- `hextra-nav-container` - ナビゲーションバーコンテナ
|
||||
- `hextra-nav-container-blur` - ブラー効果付きナビゲーションバーコンテナ
|
||||
- `hextra-hamburger-menu` - ハンバーガーメニューボタン
|
||||
|
||||
#### フッター
|
||||
|
||||
- `hextra-footer` - フッター要素
|
||||
- `hextra-custom-footer` - カスタムフッターセクションコンテナ
|
||||
|
||||
#### 検索
|
||||
|
||||
- `hextra-search-wrapper` - 検索ラッパーコンテナ
|
||||
- `hextra-search-input` - 検索入力要素
|
||||
- `hextra-search-results` - 検索結果リストコンテナ
|
||||
|
||||
検索UI内で使用されるオプションのネストされたクラス:
|
||||
|
||||
- `hextra-search-title` - 結果タイトル要素
|
||||
- `hextra-search-active` - アクティブな結果アンカー
|
||||
- `hextra-search-no-result` - 空の状態要素
|
||||
- `hextra-search-prefix` - グループ化された結果のパンくずリスト/プレフィックスラベル
|
||||
- `hextra-search-excerpt` - 結果スニペットテキスト
|
||||
- `hextra-search-match` - ハイライトされたクエリスパン
|
||||
|
||||
#### 目次
|
||||
|
||||
- `hextra-toc` - 目次コンテナ
|
||||
|
||||
#### サイドバー
|
||||
|
||||
- `hextra-sidebar-container` - サイドバーコンテナ
|
||||
- `hextra-sidebar-active-item` - サイドバーのアクティブアイテム
|
||||
|
||||
#### 言語スイッチャー
|
||||
|
||||
- `hextra-language-switcher` - 言語スイッチャーボタン
|
||||
- `hextra-language-options` - 言語オプションコンテナ
|
||||
|
||||
#### テーマトグル
|
||||
|
||||
- `hextra-theme-toggle` - テーマトグルボタン
|
||||
|
||||
#### コードコピーボタン
|
||||
|
||||
- `hextra-code-copy-btn-container` - コードコピーボタンコンテナ
|
||||
- `hextra-code-copy-btn` - コードコピーボタン
|
||||
- `hextra-copy-icon` - コピーアイコン要素
|
||||
- `hextra-success-icon` - 成功アイコン要素
|
||||
|
||||
#### コードブロック
|
||||
|
||||
- `hextra-code-block` - コードブロックコンテナ
|
||||
- `hextra-code-filename` - コードブロックのファイル名要素
|
||||
|
||||
#### フィーチャーカード
|
||||
|
||||
- `hextra-feature-card` - フィーチャーカードリンク要素
|
||||
|
||||
#### フィーチャーグリッド
|
||||
|
||||
- `hextra-feature-grid` - フィーチャーグリッドコンテナ
|
||||
|
||||
### シンタックスハイライト
|
||||
|
||||
利用可能なシンタックスハイライトテーマの一覧は、[Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html)で確認できます。スタイルシートは以下のコマンドで生成できます:
|
||||
|
||||
```shell
|
||||
hugo gen chromastyles --style=github
|
||||
```
|
||||
|
||||
デフォルトのシンタックスハイライトテーマをオーバーライドするには、生成されたスタイルをカスタムCSSファイルに追加します。
|
||||
|
||||
## カスタムスクリプト
|
||||
|
||||
すべてのページのheadの終わりにカスタムスクリプトを追加するには、以下のファイルを作成します:
|
||||
|
||||
```
|
||||
layouts/_partials/custom/head-end.html
|
||||
```
|
||||
|
||||
## フッターへのカスタムセクション追加
|
||||
|
||||
フッターに追加セクションを追加するには、サイト内に`layouts/_partials/custom/footer.html`ファイルを作成します。
|
||||
|
||||
```html {filename="layouts/_partials/custom/footer.html"}
|
||||
<!-- ここにフッター要素を追加 -->
|
||||
```
|
||||
|
||||
追加されたセクションは、フッターの著作権セクションの前に追加されます。
|
||||
[HTML](https://developer.mozilla.org/ja/docs/Web/HTML)と[Hugoテンプレート構文](https://gohugo.io/templates/)を使用して独自のコンテンツを追加できます。
|
||||
|
||||
フッターセクションで利用可能なHugo変数: `.switchesVisible`と`.displayCopyright`。
|
||||
|
||||
## カスタムレイアウト
|
||||
|
||||
テーマのレイアウトは、サイトの`layouts`ディレクトリに同じ名前のファイルを作成することでオーバーライドできます。
|
||||
例えば、ドキュメントの`single.html`レイアウトをオーバーライドするには、サイト内に`layouts/docs/single.html`ファイルを作成します。
|
||||
|
||||
詳細については、[Hugoテンプレート][hugo-template-docs]を参照してください。
|
||||
|
||||
## さらなるカスタマイズ
|
||||
|
||||
探しているものが見つかりませんでしたか？[ディスカッションを開く](https://github.com/imfing/hextra/discussions)か、テーマへの貢献をお願いします！
|
||||
|
||||
[hugo-template-docs]: https://gohugo.io/templates/
|
||||
@@ -0,0 +1,251 @@
|
||||
---
|
||||
title: Customizing Hextra
|
||||
linkTitle: Customization
|
||||
---
|
||||
|
||||
Hextra offers some default customization options in the `hugo.yaml` config file to configure the theme.
|
||||
This page describes the available options and how to customize the theme further.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Custom CSS
|
||||
|
||||
To add custom CSS, we need to create a file `assets/css/custom.css` in our site. Hextra will automatically load this file.
|
||||
|
||||
### Font Family
|
||||
|
||||
The font family of the content can be customized using:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.content {
|
||||
font-family: "Times New Roman", Times, serif;
|
||||
}
|
||||
```
|
||||
|
||||
### Inline Code Element
|
||||
|
||||
The color of text mixed with `other text` can customized with:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.content code:not(.code-block code) {
|
||||
color: #c97c2e;
|
||||
}
|
||||
```
|
||||
|
||||
### Primary Color
|
||||
|
||||
The primary color of the theme can be customized by setting the `--primary-hue`, `--primary-saturation` and `--primary-lightness` variables:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
--primary-hue: 100deg;
|
||||
--primary-saturation: 90%;
|
||||
--primary-lightness: 50%;
|
||||
}
|
||||
```
|
||||
|
||||
### Component Layout Variables
|
||||
|
||||
Hextra provides CSS variables to customize the width of pages, navbar, and footer:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
/* Page width - also configurable via hugo.yaml params.page.width */
|
||||
--hextra-max-page-width: 80rem; /* default: 80rem (normal), 90rem (wide), 100% (full) */
|
||||
|
||||
/* Navbar width - also configurable via hugo.yaml params.navbar.width */
|
||||
--hextra-max-navbar-width: 90rem; /* independent navbar width */
|
||||
|
||||
/* Footer width - also configurable via hugo.yaml params.footer.width */
|
||||
--hextra-max-footer-width: 80rem; /* independent footer width */
|
||||
}
|
||||
```
|
||||
|
||||
### Tailwind Theme Variables
|
||||
|
||||
Starting with Hextra v0.10.0, which is built on Tailwind CSS v4, you can customize the theme by overriding CSS variables inside the `@layer theme` block.
|
||||
|
||||
This lets you customize the global look and feel without having to modify every individual class.
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
@layer theme {
|
||||
:root {
|
||||
--hx-default-mono-font-family: "JetBrains Mono", monospace;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Check out [Tailwind Theme Variables documentation](https://tailwindcss.com/docs/theme#default-theme-variable-reference) for details.
|
||||
|
||||
### Further Theme Customization
|
||||
|
||||
The theme can be further customized by overriding the default styles via the exposed css classes. An example for customizing the footer element:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.hextra-footer {
|
||||
/* Styles will be applied to the footer element */
|
||||
}
|
||||
|
||||
.hextra-footer:is(html[class~="dark"] *) {
|
||||
/* Styles will be applied to the footer element in dark mode */
|
||||
}
|
||||
```
|
||||
|
||||
The following classes can be used to customize various parts of the theme.
|
||||
|
||||
#### General
|
||||
|
||||
- `hextra-scrollbar` - The scrollbar element
|
||||
- `content` - Page content container
|
||||
|
||||
#### Shortcodes
|
||||
|
||||
##### Badge
|
||||
|
||||
- `hextra-badge` - The badge element
|
||||
|
||||
##### Card
|
||||
|
||||
- `hextra-card` - The card element
|
||||
- `hextra-card-image` - The card image element
|
||||
- `hextra-card-icon` - The card icon element
|
||||
- `hextra-card-subtitle` - The card subtitle element
|
||||
|
||||
##### Cards
|
||||
|
||||
- `hextra-cards` - The cards grid container
|
||||
|
||||
##### Jupyter Notebook
|
||||
|
||||
- `hextra-jupyter-code-cell` - The Jupyter code cell container
|
||||
- `hextra-jupyter-code-cell-outputs-container` - The Jupyter code cell outputs container
|
||||
- `hextra-jupyter-code-cell-outputs` - The Jupyter code cell output div element
|
||||
|
||||
##### PDF
|
||||
|
||||
- `hextra-pdf` - The PDF container element
|
||||
|
||||
##### Steps
|
||||
|
||||
- `hextra-steps` - The steps container
|
||||
|
||||
##### Tabs
|
||||
|
||||
- `hextra-tabs-panel` - The tabs panel container
|
||||
- `hextra-tabs-toggle` - The tabs toggle button
|
||||
|
||||
##### Filetree
|
||||
|
||||
- `hextra-filetree` - The filetree container
|
||||
|
||||
##### Folder
|
||||
|
||||
- `hextra-filetree-folder` - The filetree folder container
|
||||
|
||||
#### Navbar
|
||||
|
||||
- `hextra-nav-container` - The navbar container
|
||||
- `hextra-nav-container-blur` - The navbar container in blur element
|
||||
- `hextra-hamburger-menu` - The hamburger menu button
|
||||
|
||||
#### Footer
|
||||
|
||||
- `hextra-footer` - The footer element
|
||||
- `hextra-custom-footer` - The custom footer section container
|
||||
|
||||
#### Search
|
||||
|
||||
- `hextra-search-wrapper` - The search wrapper container
|
||||
- `hextra-search-input` - The search input element
|
||||
- `hextra-search-results` - The search results list container
|
||||
|
||||
Optional nested classes used within the search UI:
|
||||
|
||||
- `hextra-search-title` - The result title element
|
||||
- `hextra-search-active` - The active result anchor
|
||||
- `hextra-search-no-result` - The empty state element
|
||||
- `hextra-search-prefix` - The breadcrumb/prefix label for grouped results
|
||||
- `hextra-search-excerpt` - The result snippet text
|
||||
- `hextra-search-match` - The highlighted query span
|
||||
|
||||
#### Table of Contents
|
||||
|
||||
- `hextra-toc` - The table of contents container
|
||||
|
||||
#### Sidebar
|
||||
|
||||
- `hextra-sidebar-container` - The sidebar container
|
||||
- `hextra-sidebar-active-item` - The active item in the sidebar
|
||||
|
||||
#### Language Switcher
|
||||
|
||||
- `hextra-language-switcher` - The language switcher button
|
||||
- `hextra-language-options` - The language options container
|
||||
|
||||
#### Theme Toggle
|
||||
|
||||
- `hextra-theme-toggle` - The theme toggle button
|
||||
|
||||
#### Code Copy Button
|
||||
|
||||
- `hextra-code-copy-btn-container` - The code copy button container
|
||||
- `hextra-code-copy-btn` - The code copy button
|
||||
- `hextra-copy-icon` - The copy icon element
|
||||
- `hextra-success-icon` - The success icon element
|
||||
|
||||
#### Code Block
|
||||
|
||||
- `hextra-code-block` - The code block container
|
||||
- `hextra-code-filename` - The filename element for code blocks
|
||||
|
||||
#### Feature Card
|
||||
|
||||
- `hextra-feature-card` - The feature card link element
|
||||
|
||||
#### Feature Grid
|
||||
|
||||
- `hextra-feature-grid` - The feature grid container
|
||||
|
||||
### Syntax Highlighting
|
||||
|
||||
List of available syntax highlighting themes are available at [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html). The stylesheet can be generated using the command:
|
||||
|
||||
```shell
|
||||
hugo gen chromastyles --style=github
|
||||
```
|
||||
|
||||
To override the default syntax highlighting theme, we can add the generated styles to the custom CSS file.
|
||||
|
||||
## Custom Scripts
|
||||
|
||||
You may add custom scripts to the end of the head for every page by adding the following file:
|
||||
|
||||
```
|
||||
layouts/_partials/custom/head-end.html
|
||||
```
|
||||
|
||||
## Custom Extra Section in Footer
|
||||
|
||||
You can add extra section in the footer by creating a file `layouts/_partials/custom/footer.html` in your site.
|
||||
|
||||
```html {filename="layouts/_partials/custom/footer.html"}
|
||||
<!-- Your footer element here -->
|
||||
```
|
||||
|
||||
The added section will be added before the copyright section in the footer.
|
||||
You can use [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) and [Hugo template syntax](https://gohugo.io/templates/) to add your own content.
|
||||
|
||||
Hugo variables available in the footer section are: `.switchesVisible` and `.displayCopyright`.
|
||||
|
||||
## Custom Layouts
|
||||
|
||||
The layouts of the theme can be overridden by creating a file with the same name in the `layouts` directory of your site.
|
||||
For example, to override the `single.html` layout for docs, create a file `layouts/docs/single.html` in your site.
|
||||
|
||||
For further information, refer to the [Hugo Templates][hugo-template-docs].
|
||||
|
||||
## Further Customization
|
||||
|
||||
Didn't find what you were looking for? Feel free to [open a discussion](https://github.com/imfing/hextra/discussions) or make a contribution to the theme!
|
||||
|
||||
[hugo-template-docs]: https://gohugo.io/templates/
|
||||
@@ -0,0 +1,251 @@
|
||||
---
|
||||
title: 自定义 Hextra
|
||||
linkTitle: 自定义
|
||||
---
|
||||
|
||||
Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项来配置主题。
|
||||
本页描述了可用选项以及如何进一步自定义主题。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## 自定义 CSS
|
||||
|
||||
要添加自定义 CSS，我们需要在站点中创建 `assets/css/custom.css` 文件。Hextra 会自动加载此文件。
|
||||
|
||||
### 字体家族
|
||||
|
||||
可以使用以下方式自定义内容的字体家族：
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.content {
|
||||
font-family: "Times New Roman", Times, serif;
|
||||
}
|
||||
```
|
||||
|
||||
### 行内代码元素
|
||||
|
||||
与 `其他文本` 混合的代码文本颜色可以通过以下方式自定义：
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.content code:not(.code-block code) {
|
||||
color: #c97c2e;
|
||||
}
|
||||
```
|
||||
|
||||
### 主色调
|
||||
|
||||
可以通过设置 `--primary-hue`、`--primary-saturation` 和 `--primary-lightness` 变量来自定义主题的主色调：
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
--primary-hue: 100deg;
|
||||
--primary-saturation: 90%;
|
||||
--primary-lightness: 50%;
|
||||
}
|
||||
```
|
||||
|
||||
### 组件布局变量
|
||||
|
||||
Hextra 提供了 CSS 变量来自定义页面、导航栏和页脚的宽度：
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
/* 页面宽度 - 也可以通过 hugo.yaml 中的 params.page.width 配置 */
|
||||
--hextra-max-page-width: 80rem; /* 默认值：80rem（普通），90rem（宽版），100%（全宽） */
|
||||
|
||||
/* 导航栏宽度 - 也可以通过 hugo.yaml 中的 params.navbar.width 配置 */
|
||||
--hextra-max-navbar-width: 90rem; /* 独立的导航栏宽度 */
|
||||
|
||||
/* 页脚宽度 - 也可以通过 hugo.yaml 中的 params.footer.width 配置 */
|
||||
--hextra-max-footer-width: 80rem; /* 独立的页脚宽度 */
|
||||
}
|
||||
```
|
||||
|
||||
### Tailwind 主题变量
|
||||
|
||||
从基于 Tailwind CSS v4 的 Hextra v0.10.0 开始，您可以通过在 `@layer theme` 块中覆盖 CSS 变量来自定义主题。
|
||||
|
||||
这样可以在不修改每个单独类的情况下自定义全局外观。
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
@layer theme {
|
||||
:root {
|
||||
--hx-default-mono-font-family: "JetBrains Mono", monospace;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
详情请参阅 [Tailwind 主题变量文档](https://tailwindcss.com/docs/theme#default-theme-variable-reference)。
|
||||
|
||||
### 进一步主题自定义
|
||||
|
||||
可以通过覆盖暴露的 CSS 类来自定义主题的默认样式。以下是一个自定义页脚元素的示例：
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
.hextra-footer {
|
||||
/* 样式将应用于页脚元素 */
|
||||
}
|
||||
|
||||
.hextra-footer:is(html[class~="dark"] *) {
|
||||
/* 样式将应用于暗黑模式下的页脚元素 */
|
||||
}
|
||||
```
|
||||
|
||||
以下类可用于自定义主题的各个部分。
|
||||
|
||||
#### 通用
|
||||
|
||||
- `hextra-scrollbar` - 滚动条元素
|
||||
- `content` - 页面内容容器
|
||||
|
||||
#### 短代码
|
||||
|
||||
##### 徽章
|
||||
|
||||
- `hextra-badge` - 徽章元素
|
||||
|
||||
##### 卡片
|
||||
|
||||
- `hextra-card` - 卡片元素
|
||||
- `hextra-card-image` - 卡片图片元素
|
||||
- `hextra-card-icon` - 卡片图标元素
|
||||
- `hextra-card-subtitle` - 卡片副标题元素
|
||||
|
||||
##### 卡片组
|
||||
|
||||
- `hextra-cards` - 卡片网格容器
|
||||
|
||||
##### Jupyter 笔记本
|
||||
|
||||
- `hextra-jupyter-code-cell` - Jupyter 代码单元格容器
|
||||
- `hextra-jupyter-code-cell-outputs-container` - Jupyter 代码单元格输出容器
|
||||
- `hextra-jupyter-code-cell-outputs` - Jupyter 代码单元格输出 div 元素
|
||||
|
||||
##### PDF
|
||||
|
||||
- `hextra-pdf` - PDF 容器元素
|
||||
|
||||
##### 步骤
|
||||
|
||||
- `hextra-steps` - 步骤容器
|
||||
|
||||
##### 标签页
|
||||
|
||||
- `hextra-tabs-panel` - 标签页面板容器
|
||||
- `hextra-tabs-toggle` - 标签页切换按钮
|
||||
|
||||
##### 文件树
|
||||
|
||||
- `hextra-filetree` - 文件树容器
|
||||
|
||||
##### 文件夹
|
||||
|
||||
- `hextra-filetree-folder` - 文件树文件夹容器
|
||||
|
||||
#### 导航栏
|
||||
|
||||
- `hextra-nav-container` - 导航栏容器
|
||||
- `hextra-nav-container-blur` - 导航栏模糊效果容器
|
||||
- `hextra-hamburger-menu` - 汉堡菜单按钮
|
||||
|
||||
#### 页脚
|
||||
|
||||
- `hextra-footer` - 页脚元素
|
||||
- `hextra-custom-footer` - 自定义页脚部分容器
|
||||
|
||||
#### 搜索
|
||||
|
||||
- `hextra-search-wrapper` - 搜索包装容器
|
||||
- `hextra-search-input` - 搜索输入元素
|
||||
- `hextra-search-results` - 搜索结果列表容器
|
||||
|
||||
搜索 UI 中使用的可选嵌套类：
|
||||
|
||||
- `hextra-search-title` - 结果标题元素
|
||||
- `hextra-search-active` - 活动结果锚点
|
||||
- `hextra-search-no-result` - 空状态元素
|
||||
- `hextra-search-prefix` - 分组结果的面包屑/前缀标签
|
||||
- `hextra-search-excerpt` - 结果片段文本
|
||||
- `hextra-search-match` - 高亮查询范围
|
||||
|
||||
#### 目录
|
||||
|
||||
- `hextra-toc` - 目录容器
|
||||
|
||||
#### 侧边栏
|
||||
|
||||
- `hextra-sidebar-container` - 侧边栏容器
|
||||
- `hextra-sidebar-active-item` - 侧边栏中的活动项
|
||||
|
||||
#### 语言切换器
|
||||
|
||||
- `hextra-language-switcher` - 语言切换按钮
|
||||
- `hextra-language-options` - 语言选项容器
|
||||
|
||||
#### 主题切换
|
||||
|
||||
- `hextra-theme-toggle` - 主题切换按钮
|
||||
|
||||
#### 代码复制按钮
|
||||
|
||||
- `hextra-code-copy-btn-container` - 代码复制按钮容器
|
||||
- `hextra-code-copy-btn` - 代码复制按钮
|
||||
- `hextra-copy-icon` - 复制图标元素
|
||||
- `hextra-success-icon` - 成功图标元素
|
||||
|
||||
#### 代码块
|
||||
|
||||
- `hextra-code-block` - 代码块容器
|
||||
- `hextra-code-filename` - 代码块的文件名元素
|
||||
|
||||
#### 功能卡片
|
||||
|
||||
- `hextra-feature-card` - 功能卡片链接元素
|
||||
|
||||
#### 功能网格
|
||||
|
||||
- `hextra-feature-grid` - 功能网格容器
|
||||
|
||||
### 语法高亮
|
||||
|
||||
可用的语法高亮主题列表可在 [Chroma 样式库](https://xyproto.github.io/splash/docs/all.html) 中找到。可以使用以下命令生成样式表：
|
||||
|
||||
```shell
|
||||
hugo gen chromastyles --style=github
|
||||
```
|
||||
|
||||
要覆盖默认的语法高亮主题，可以将生成的样式添加到自定义 CSS 文件中。
|
||||
|
||||
## 自定义脚本
|
||||
|
||||
您可以通过添加以下文件在每个页面的 head 末尾添加自定义脚本：
|
||||
|
||||
```
|
||||
layouts/_partials/custom/head-end.html
|
||||
```
|
||||
|
||||
## 自定义页脚额外部分
|
||||
|
||||
您可以通过在站点中创建 `layouts/_partials/custom/footer.html` 文件来添加页脚的额外部分。
|
||||
|
||||
```html {filename="layouts/_partials/custom/footer.html"}
|
||||
<!-- 您的页脚元素放在这里 -->
|
||||
```
|
||||
|
||||
添加的部分将出现在页脚的版权部分之前。
|
||||
您可以使用 [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) 和 [Hugo 模板语法](https://gohugo.io/templates/) 添加自己的内容。
|
||||
|
||||
页脚部分可用的 Hugo 变量有：`.switchesVisible` 和 `.displayCopyright`。
|
||||
|
||||
## 自定义布局
|
||||
|
||||
可以通过在站点的 `layouts` 目录中创建同名文件来覆盖主题的布局。
|
||||
例如，要覆盖文档的 `single.html` 布局，可以在站点中创建 `layouts/docs/single.html` 文件。
|
||||
|
||||
更多信息，请参阅 [Hugo 模板文档][hugo-template-docs]。
|
||||
|
||||
## 进一步自定义
|
||||
|
||||
没有找到您需要的内容？欢迎 [发起讨论](https://github.com/imfing/hextra/discussions) 或为主题做出贡献！
|
||||
|
||||
[hugo-template-docs]: https://gohugo.io/templates/
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "چند زبانه"
|
||||
weight: 1
|
||||
prev: /docs/advanced
|
||||
---
|
||||
|
||||
Hextra از ایجاد سایت با چندین زبان با استفاده از [حالت چندزبانه](https://gohugo.io/content-management/multilingual/) هوگو پشتیبانی میکند.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## فعالسازی چندزبانه
|
||||
|
||||
برای چندزبانه کردن سایت، باید به هوگو زبانهای پشتیبانی شده را اطلاع دهیم. باید به فایل پیکربندی سایت اضافه کنیم:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
defaultContentLanguage: en
|
||||
languages:
|
||||
en:
|
||||
label: English
|
||||
weight: 1
|
||||
fr:
|
||||
label: Français
|
||||
weight: 2
|
||||
ja:
|
||||
label: 日本語
|
||||
weight: 3
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> پیکربندیهای قدیمی Hugo ممکن است از `languageName`، `languageCode` و `languageDirection` استفاده کنند.
|
||||
> از Hugo v0.158.0 به بعد، بهترتیب از `label`، `locale` و `direction` استفاده کنید.
|
||||
> مستندات [تنظیمات زبانهای Hugo](https://gohugo.io/configuration/languages/#language-settings) را ببینید.
|
||||
|
||||
## مدیریت ترجمهها بر اساس نام فایل
|
||||
|
||||
هوگو از مدیریت ترجمهها بر اساس نام فایل پشتیبانی میکند. به عنوان مثال، اگر فایلی به نام `content/docs/_index.md` به زبان انگلیسی داریم، میتوانیم فایل `content/docs/_index.fr.md` را برای ترجمه فرانسوی ایجاد کنیم.
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="_index.fr.md" >}}
|
||||
{{< filetree/file name="_index.ja.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
توجه: هوگو از [ترجمه بر اساس دایرکتوری محتوا](https://gohugo.io/content-management/multilingual/#translation-by-content-directory) نیز پشتیبانی میکند.
|
||||
|
||||
## ترجمه آیتمهای منو
|
||||
|
||||
برای ترجمه آیتمهای منو در نوار ناوبری، باید فیلد `identifier` را تنظیم کنیم:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: documentation
|
||||
name: Documentation
|
||||
pageRef: /docs
|
||||
weight: 1
|
||||
- identifier: blog
|
||||
name: Blog
|
||||
pageRef: /blog
|
||||
weight: 2
|
||||
```
|
||||
|
||||
و آنها را در فایل i18n مربوطه ترجمه کنیم:
|
||||
|
||||
```yaml {filename="i18n/fr.yaml"}
|
||||
documentation: Documentation
|
||||
blog: Blog
|
||||
```
|
||||
|
||||
## ترجمه رشتهها
|
||||
|
||||
برای ترجمه رشتهها در سایر قسمتها، باید ترجمه را به فایل i18n مربوطه اضافه کنیم:
|
||||
|
||||
```yaml {filename="i18n/fr.yaml"}
|
||||
readMore: Lire la suite
|
||||
```
|
||||
|
||||
لیستی از رشتههای استفاده شده در قالب را میتوان در فایل `i18n/en.yaml` یافت.
|
||||
|
||||
## مطالعه بیشتر
|
||||
|
||||
- [حالت چندزبانه هوگو](https://gohugo.io/content-management/multilingual/)
|
||||
- [چندزبانه هوگو بخش 1: ترجمه محتوا](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
|
||||
- [چندزبانه هوگو بخش 2: بومیسازی رشتهها](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-2-i18n-string-localization/)
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "多言語対応"
|
||||
weight: 1
|
||||
prev: /docs/advanced
|
||||
---
|
||||
|
||||
Hextra は Hugo の [多言語モード](https://gohugo.io/content-management/multilingual/) を使用して、複数言語のサイトを作成することをサポートしています。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## 多言語対応を有効にする
|
||||
|
||||
サイトを多言語対応にするには、Hugo にサポートする言語を伝える必要があります。サイト設定ファイルに以下を追加します:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
defaultContentLanguage: en
|
||||
languages:
|
||||
en:
|
||||
label: English
|
||||
weight: 1
|
||||
fr:
|
||||
label: Français
|
||||
weight: 2
|
||||
ja:
|
||||
label: 日本語
|
||||
weight: 3
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> 古い Hugo 設定では、`languageName`、`languageCode`、`languageDirection` が使われている場合があります。
|
||||
> Hugo v0.158.0 以降は、それぞれ `label`、`locale`、`direction` を使用してください。
|
||||
> Hugo の [言語設定ドキュメント](https://gohugo.io/configuration/languages/#language-settings)を参照してください。
|
||||
|
||||
## ファイル名による翻訳管理
|
||||
|
||||
Hugo はファイル名による翻訳管理をサポートしています。例えば、英語のファイル `content/docs/_index.md` がある場合、フランス語の翻訳用に `content/docs/_index.fr.md` というファイルを作成できます。
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="_index.fr.md" >}}
|
||||
{{< filetree/file name="_index.ja.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
注: Hugo は [コンテンツディレクトリによる翻訳](https://gohugo.io/content-management/multilingual/#translation-by-content-directory) もサポートしています。
|
||||
|
||||
## メニュー項目の翻訳
|
||||
|
||||
ナビゲーションバーのメニュー項目を翻訳するには、`identifier` フィールドを設定する必要があります:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: documentation
|
||||
name: Documentation
|
||||
pageRef: /docs
|
||||
weight: 1
|
||||
- identifier: blog
|
||||
name: Blog
|
||||
pageRef: /blog
|
||||
weight: 2
|
||||
```
|
||||
|
||||
そして、対応する i18n ファイルで翻訳します:
|
||||
|
||||
```yaml {filename="i18n/fr.yaml"}
|
||||
documentation: Documentation
|
||||
blog: Blog
|
||||
```
|
||||
|
||||
## 文字列の翻訳
|
||||
|
||||
他の場所の文字列を翻訳するには、対応する i18n ファイルに翻訳を追加する必要があります:
|
||||
|
||||
```yaml {filename="i18n/fr.yaml"}
|
||||
readMore: Lire la suite
|
||||
```
|
||||
|
||||
テーマで使用される文字列の一覧は `i18n/en.yaml` ファイルで確認できます。
|
||||
|
||||
## さらに詳しく
|
||||
|
||||
- [Hugo 多言語モード](https://gohugo.io/content-management/multilingual/)
|
||||
- [Hugo 多言語対応 パート1: コンテンツ翻訳](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
|
||||
- [Hugo 多言語対応 パート2: 文字列のローカライズ](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-2-i18n-string-localization/)
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "Multi-language"
|
||||
weight: 1
|
||||
prev: /docs/advanced/additional-pages
|
||||
---
|
||||
|
||||
Hextra supports creating site with multiple languages using Hugo's [multilingual mode](https://gohugo.io/content-management/multilingual/).
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Enable Multi-language
|
||||
|
||||
To make our site multi-language, we need to tell Hugo the supported languages. We need to add to the site configuration file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
defaultContentLanguage: en
|
||||
languages:
|
||||
en:
|
||||
label: English
|
||||
weight: 1
|
||||
fr:
|
||||
label: Français
|
||||
weight: 2
|
||||
ja:
|
||||
label: 日本語
|
||||
weight: 3
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Older Hugo configurations may use `languageName`, `languageCode`, and `languageDirection`.
|
||||
> Starting with Hugo v0.158.0, use `label`, `locale`, and `direction` respectively.
|
||||
> See Hugo's [language settings documentation](https://gohugo.io/configuration/languages/#language-settings).
|
||||
|
||||
## Manage Translations by Filename
|
||||
|
||||
Hugo supports managing translations by filename. For example, if we have a file `content/docs/_index.md` in English, we can create a file `content/docs/_index.fr.md` for French translation.
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="_index.fr.md" >}}
|
||||
{{< filetree/file name="_index.ja.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
Note: Hugo also supports [Translation by content directory](https://gohugo.io/content-management/multilingual/#translation-by-content-directory).
|
||||
|
||||
## Translate Menu Items
|
||||
|
||||
To translate menu items in the navigation bar, we need to set the `identifier` field:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: documentation
|
||||
name: Documentation
|
||||
pageRef: /docs
|
||||
weight: 1
|
||||
- identifier: blog
|
||||
name: Blog
|
||||
pageRef: /blog
|
||||
weight: 2
|
||||
```
|
||||
|
||||
and translate them in the corresponding i18n file:
|
||||
|
||||
```yaml {filename="i18n/fr.yaml"}
|
||||
documentation: Documentation
|
||||
blog: Blog
|
||||
```
|
||||
|
||||
## Translate Strings
|
||||
|
||||
To translate strings on the other places, we need to add the translation to the corresponding i18n file:
|
||||
|
||||
```yaml {filename="i18n/fr.yaml"}
|
||||
readMore: Lire la suite
|
||||
```
|
||||
|
||||
A list of strings used in the theme can be found in the `i18n/en.yaml` file.
|
||||
|
||||
## Read More
|
||||
|
||||
- [Hugo Multilingual Mode](https://gohugo.io/content-management/multilingual/)
|
||||
- [Hugo Multilingual Part 1: Content translation](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
|
||||
- [Hugo Multilingual Part 2: Strings localization](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-2-i18n-string-localization/)
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "多语言支持"
|
||||
weight: 1
|
||||
prev: /docs/advanced
|
||||
---
|
||||
|
||||
Hextra 支持使用 Hugo 的[多语言模式](https://gohugo.io/content-management/multilingual/)创建多语言网站。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## 启用多语言功能
|
||||
|
||||
要使网站支持多语言，我们需要在站点配置文件中指定支持的语言：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
defaultContentLanguage: en
|
||||
languages:
|
||||
en:
|
||||
label: English
|
||||
weight: 1
|
||||
fr:
|
||||
label: Français
|
||||
weight: 2
|
||||
ja:
|
||||
label: 日本語
|
||||
weight: 3
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> 旧版 Hugo 配置可能使用 `languageName`、`languageCode` 和 `languageDirection`。
|
||||
> 从 Hugo v0.158.0 开始，请分别使用 `label`、`locale` 和 `direction`。
|
||||
> 请参阅 Hugo 的[语言设置文档](https://gohugo.io/configuration/languages/#language-settings)。
|
||||
|
||||
## 通过文件名管理翻译
|
||||
|
||||
Hugo 支持通过文件名管理翻译。例如，如果我们有一个英文文件 `content/docs/_index.md`，可以创建 `content/docs/_index.fr.md` 作为法语翻译。
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="_index.fr.md" >}}
|
||||
{{< filetree/file name="_index.ja.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
注意：Hugo 还支持[通过内容目录翻译](https://gohugo.io/content-management/multilingual/#translation-by-content-directory)。
|
||||
|
||||
## 翻译菜单项
|
||||
|
||||
要翻译导航栏中的菜单项，需要设置 `identifier` 字段：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: documentation
|
||||
name: Documentation
|
||||
pageRef: /docs
|
||||
weight: 1
|
||||
- identifier: blog
|
||||
name: Blog
|
||||
pageRef: /blog
|
||||
weight: 2
|
||||
```
|
||||
|
||||
并在对应的 i18n 文件中进行翻译：
|
||||
|
||||
```yaml {filename="i18n/fr.yaml"}
|
||||
documentation: Documentation
|
||||
blog: Blog
|
||||
```
|
||||
|
||||
## 翻译字符串
|
||||
|
||||
要翻译其他位置的字符串，需要将翻译添加到对应的 i18n 文件中：
|
||||
|
||||
```yaml {filename="i18n/fr.yaml"}
|
||||
readMore: Lire la suite
|
||||
```
|
||||
|
||||
主题中使用的字符串列表可以在 `i18n/en.yaml` 文件中找到。
|
||||
|
||||
## 延伸阅读
|
||||
|
||||
- [Hugo 多语言模式](https://gohugo.io/content-management/multilingual/)
|
||||
- [Hugo 多语言第一部分：内容翻译](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
|
||||
- [Hugo 多语言第二部分：字符串本地化](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-2-i18n-string-localization/)
|
||||
@@ -0,0 +1,204 @@
|
||||
---
|
||||
title: شروع به کار
|
||||
weight: 1
|
||||
tags:
|
||||
- مستندات
|
||||
- راهنما
|
||||
next: /docs/guide
|
||||
prev: /docs
|
||||
---
|
||||
|
||||
## شروع سریع با قالب
|
||||
|
||||
{{< icon "github" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)
|
||||
|
||||
میتوانید با استفاده از مخزن قالب فوق به سرعت شروع به کار کنید.
|
||||
|
||||
<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500" alt="صفحه مخزن GitHub که دکمه Use this template را نشان میدهد">
|
||||
|
||||
ما یک [گردش کار GitHub Actions](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) ارائه کردهایم که میتواند به صورت خودکار سایت شما را ساخته و در GitHub Pages مستقر کند و به صورت رایگان میزبانی کند.
|
||||
برای گزینههای بیشتر، [استقرار سایت](../guide/deploy-site) را بررسی کنید.
|
||||
|
||||
[🌐 نسخه نمایشی ↗](https://imfing.github.io/hextra-starter-template/)
|
||||
|
||||
## شروع به عنوان پروژه جدید
|
||||
|
||||
دو روش اصلی برای افزودن تم Hextra به پروژه Hugo شما وجود دارد:
|
||||
|
||||
1. **ماژولهای Hugo (توصیه شده)**: سادهترین و توصیهشدهترین روش. [ماژولهای Hugo](https://gohugo.io/hugo-modules/) به شما امکان میدهند تم را مستقیماً از منبع آنلاین آن دریافت کنید. تم به صورت خودکار دانلود شده و توسط Hugo مدیریت میشود.
|
||||
|
||||
2. **زیرماژول Git**: به عنوان جایگزین، Hextra را به عنوان یک [زیرماژول Git](https://git-scm.com/book/en/v2/Git-Tools-Submodules) اضافه کنید. تم توسط Git دانلود شده و در پوشه `themes` پروژه شما ذخیره میشود.
|
||||
|
||||
### راهاندازی Hextra به عنوان ماژول Hugo
|
||||
|
||||
#### پیشنیازها
|
||||
|
||||
قبل از شروع، باید نرمافزارهای زیر را نصب کرده باشید:
|
||||
|
||||
- [Hugo (نسخه extended)](https://gohugo.io/installation/)
|
||||
- [Git](https://git-scm.com/)
|
||||
- [Go](https://go.dev/)
|
||||
|
||||
#### مراحل
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### راهاندازی یک سایت جدید Hugo
|
||||
|
||||
```shell
|
||||
hugo new site my-site --format=yaml
|
||||
```
|
||||
|
||||
### پیکربندی تم Hextra از طریق ماژول
|
||||
|
||||
```shell
|
||||
# راهاندازی ماژول Hugo
|
||||
cd my-site
|
||||
hugo mod init github.com/username/my-site
|
||||
|
||||
# افزودن تم Hextra
|
||||
hugo mod get github.com/imfing/hextra
|
||||
```
|
||||
|
||||
فایل `hugo.yaml` را برای استفاده از تم Hextra با افزودن موارد زیر پیکربندی کنید:
|
||||
|
||||
```yaml
|
||||
module:
|
||||
imports:
|
||||
- path: github.com/imfing/hextra
|
||||
```
|
||||
|
||||
### ایجاد اولین صفحات محتوای شما
|
||||
|
||||
صفحه محتوای جدید برای صفحه اصلی و صفحه مستندات ایجاد کنید:
|
||||
|
||||
```shell
|
||||
hugo new content/_index.md
|
||||
hugo new content/docs/_index.md
|
||||
```
|
||||
|
||||
### پیشنمایش سایت به صورت محلی
|
||||
|
||||
```shell
|
||||
hugo server --buildDrafts --disableFastRender
|
||||
```
|
||||
|
||||
تبریک میگوییم، پیشنمایش سایت جدید شما در `http://localhost:1313/` در دسترس است.
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
|
||||
{{% details title="چگونه تم را بهروزرسانی کنیم؟" %}}
|
||||
|
||||
برای بهروزرسانی تمام ماژولهای Hugo در پروژه خود به آخرین نسخهها، دستور زیر را اجرا کنید:
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
برای بهروزرسانی Hextra به [آخرین نسخه منتشر شده](https://github.com/imfing/hextra/releases)، دستور زیر را اجرا کنید:
|
||||
|
||||
```shell
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
برای جزئیات بیشتر، [ماژولهای Hugo](https://gohugo.io/hugo-modules/use-modules/#update-all-modules) را ببینید.
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
### راهاندازی Hextra به عنوان زیرماژول Git
|
||||
|
||||
#### پیشنیازها
|
||||
|
||||
قبل از شروع، باید نرمافزارهای زیر را نصب کرده باشید:
|
||||
|
||||
- [Hugo (نسخه extended)](https://gohugo.io/installation/)
|
||||
- [Git](https://git-scm.com/)
|
||||
|
||||
#### مراحل
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### راهاندازی یک سایت جدید Hugo
|
||||
|
||||
```shell
|
||||
hugo new site my-site --format=yaml
|
||||
```
|
||||
|
||||
### افزودن تم Hextra به عنوان زیرماژول Git
|
||||
|
||||
به دایرکتوری سایت بروید و یک مخزن Git جدید راهاندازی کنید:
|
||||
|
||||
```shell
|
||||
cd my-site
|
||||
git init
|
||||
```
|
||||
|
||||
سپس، تم Hextra را به عنوان زیرماژول Git اضافه کنید:
|
||||
|
||||
```shell
|
||||
git submodule add https://github.com/imfing/hextra.git themes/hextra
|
||||
```
|
||||
|
||||
فایل `hugo.yaml` را برای استفاده از تم Hextra با افزودن موارد زیر پیکربندی کنید:
|
||||
|
||||
```yaml
|
||||
theme: hextra
|
||||
```
|
||||
|
||||
### ایجاد اولین صفحات محتوای شما
|
||||
|
||||
صفحه محتوای جدید برای صفحه اصلی و صفحه مستندات ایجاد کنید:
|
||||
|
||||
```shell
|
||||
hugo new content/_index.md
|
||||
hugo new content/docs/_index.md
|
||||
```
|
||||
|
||||
### پیشنمایش سایت به صورت محلی
|
||||
|
||||
```shell
|
||||
hugo server --buildDrafts --disableFastRender
|
||||
```
|
||||
|
||||
پیشنمایش سایت جدید شما در `http://localhost:1313/` در دسترس است.
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
|
||||
هنگام استفاده از [CI/CD](https://en.wikipedia.org/wiki/CI/CD) برای استقرار سایت Hugo، ضروری است که قبل از اجرای دستور `hugo`، دستور زیر اجرا شود.
|
||||
|
||||
```shell
|
||||
git submodule update --init
|
||||
```
|
||||
|
||||
عدم اجرای این دستور منجر به پر نشدن پوشه تم با فایلهای تم Hextra شده و باعث شکست ساخت میشود.
|
||||
|
||||
|
||||
{{% details title="چگونه تم را بهروزرسانی کنیم؟" %}}
|
||||
|
||||
برای بهروزرسانی تمام زیرماژولهای مخزن شما به آخرین کامیتها، دستور زیر را اجرا کنید:
|
||||
|
||||
```shell
|
||||
git submodule update --remote
|
||||
```
|
||||
|
||||
برای بهروزرسانی Hextra به آخرین کامیت، دستور زیر را اجرا کنید:
|
||||
|
||||
```shell
|
||||
git submodule update --remote themes/hextra
|
||||
```
|
||||
|
||||
برای جزئیات بیشتر، [زیرماژولهای Git](https://git-scm.com/book/en/v2/Git-Tools-Submodules) را ببینید.
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
## بعدی
|
||||
|
||||
برای شروع افزودن محتوای بیشتر، بخشهای زیر را بررسی کنید:
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="../guide/organize-files" title="سازماندهی فایلها" icon="document-duplicate" >}}
|
||||
{{< card link="../guide/configuration" title="پیکربندی" icon="adjustments" >}}
|
||||
{{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,204 @@
|
||||
---
|
||||
title: はじめに
|
||||
weight: 1
|
||||
tags:
|
||||
- Docs
|
||||
- Guide
|
||||
next: /docs/guide
|
||||
prev: /docs
|
||||
---
|
||||
|
||||
## テンプレートから始める
|
||||
|
||||
{{< icon "github" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)
|
||||
|
||||
上記のテンプレートリポジトリを使用して、すぐに始めることができます。
|
||||
|
||||
<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500" alt="Use this template ボタンが表示された GitHub リポジトリページ">
|
||||
|
||||
[GitHub Actions ワークフロー](https://docs.github.com/ja/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)を提供しており、サイトを自動的にビルドして GitHub Pages にデプロイし、無料でホストすることができます。
|
||||
その他のオプションについては、[サイトのデプロイ](../guide/deploy-site)を確認してください。
|
||||
|
||||
[🌐 デモ ↗](https://imfing.github.io/hextra-starter-template/)
|
||||
|
||||
## 新規プロジェクトとして始める
|
||||
|
||||
Hugo プロジェクトに Hextra テーマを追加する主な方法は2つあります:
|
||||
|
||||
1. **Hugo モジュール (推奨)**: 最も簡単で推奨される方法です。[Hugo モジュール](https://gohugo.io/hugo-modules/)を使用すると、テーマをオンラインソースから直接取り込むことができます。テーマは自動的にダウンロードされ、Hugo によって管理されます。
|
||||
|
||||
2. **Git サブモジュール**: または、Hextra を [Git サブモジュール](https://git-scm.com/book/ja/v2/Git-%E3%83%84%E3%83%BC%E3%83%AB-%E3%82%B5%E3%83%96%E3%83%A2%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB)として追加します。テーマは Git によってダウンロードされ、プロジェクトの `themes` フォルダに保存されます。
|
||||
|
||||
### Hugo モジュールとして Hextra をセットアップ
|
||||
|
||||
#### 前提条件
|
||||
|
||||
開始する前に、以下のソフトウェアがインストールされている必要があります:
|
||||
|
||||
- [Hugo (拡張版)](https://gohugo.io/installation/)
|
||||
- [Git](https://git-scm.com/)
|
||||
- [Go](https://go.dev/)
|
||||
|
||||
#### 手順
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### 新しい Hugo サイトを初期化
|
||||
|
||||
```shell
|
||||
hugo new site my-site --format=yaml
|
||||
```
|
||||
|
||||
### モジュール経由で Hextra テーマを設定
|
||||
|
||||
```shell
|
||||
# Hugo モジュールを初期化
|
||||
cd my-site
|
||||
hugo mod init github.com/username/my-site
|
||||
|
||||
# Hextra テーマを追加
|
||||
hugo mod get github.com/imfing/hextra
|
||||
```
|
||||
|
||||
`hugo.yaml` を設定して Hextra テーマを使用するようにします:
|
||||
|
||||
```yaml
|
||||
module:
|
||||
imports:
|
||||
- path: github.com/imfing/hextra
|
||||
```
|
||||
|
||||
### 最初のコンテンツページを作成
|
||||
|
||||
ホームページとドキュメントページの新しいコンテンツページを作成します:
|
||||
|
||||
```shell
|
||||
hugo new content/_index.md
|
||||
hugo new content/docs/_index.md
|
||||
```
|
||||
|
||||
### ローカルでサイトをプレビュー
|
||||
|
||||
```shell
|
||||
hugo server --buildDrafts --disableFastRender
|
||||
```
|
||||
|
||||
これで、新しいサイトのプレビューが `http://localhost:1313/` で利用可能になります。
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
|
||||
{{% details title="テーマを更新するには？" %}}
|
||||
|
||||
プロジェクト内のすべての Hugo モジュールを最新バージョンに更新するには、次のコマンドを実行します:
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
Hextra を[最新リリースバージョン](https://github.com/imfing/hextra/releases)に更新するには、次のコマンドを実行します:
|
||||
|
||||
```shell
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
詳細については、[Hugo モジュール](https://gohugo.io/hugo-modules/use-modules/#update-all-modules)を参照してください。
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
### Git サブモジュールとして Hextra をセットアップ
|
||||
|
||||
#### 前提条件
|
||||
|
||||
開始する前に、以下のソフトウェアがインストールされている必要があります:
|
||||
|
||||
- [Hugo (拡張版)](https://gohugo.io/installation/)
|
||||
- [Git](https://git-scm.com/)
|
||||
|
||||
#### 手順
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### 新しい Hugo サイトを初期化
|
||||
|
||||
```shell
|
||||
hugo new site my-site --format=yaml
|
||||
```
|
||||
|
||||
### Git サブモジュールとして Hextra テーマを追加
|
||||
|
||||
サイトディレクトリに移動して新しい Git リポジトリを初期化します:
|
||||
|
||||
```shell
|
||||
cd my-site
|
||||
git init
|
||||
```
|
||||
|
||||
次に、Hextra テーマを Git サブモジュールとして追加します:
|
||||
|
||||
```shell
|
||||
git submodule add https://github.com/imfing/hextra.git themes/hextra
|
||||
```
|
||||
|
||||
`hugo.yaml` を設定して Hextra テーマを使用するようにします:
|
||||
|
||||
```yaml
|
||||
theme: hextra
|
||||
```
|
||||
|
||||
### 最初のコンテンツページを作成
|
||||
|
||||
ホームページとドキュメントページの新しいコンテンツページを作成します:
|
||||
|
||||
```shell
|
||||
hugo new content/_index.md
|
||||
hugo new content/docs/_index.md
|
||||
```
|
||||
|
||||
### ローカルでサイトをプレビュー
|
||||
|
||||
```shell
|
||||
hugo server --buildDrafts --disableFastRender
|
||||
```
|
||||
|
||||
新しいサイトのプレビューが `http://localhost:1313/` で利用可能になります。
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
|
||||
Hugo ウェブサイトのデプロイに [CI/CD](https://ja.wikipedia.org/wiki/CI/CD) を使用する場合、`hugo` コマンドを実行する前に以下のコマンドを実行することが重要です。
|
||||
|
||||
```shell
|
||||
git submodule update --init
|
||||
```
|
||||
|
||||
このコマンドを実行しないと、テーマフォルダに Hextra テーマファイルが配置されず、ビルドが失敗します。
|
||||
|
||||
|
||||
{{% details title="テーマを更新するには？" %}}
|
||||
|
||||
リポジトリ内のすべてのサブモジュールを最新のコミットに更新するには、次のコマンドを実行します:
|
||||
|
||||
```shell
|
||||
git submodule update --remote
|
||||
```
|
||||
|
||||
Hextra を最新のコミットに更新するには、次のコマンドを実行します:
|
||||
|
||||
```shell
|
||||
git submodule update --remote themes/hextra
|
||||
```
|
||||
|
||||
詳細については、[Git サブモジュール](https://git-scm.com/book/ja/v2/Git-%E3%83%84%E3%83%BC%E3%83%AB-%E3%82%B5%E3%83%96%E3%83%A2%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB)を参照してください。
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
## 次に
|
||||
|
||||
以下のセクションを探索して、さらにコンテンツを追加しましょう:
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="../guide/organize-files" title="ファイルの整理" icon="document-duplicate" >}}
|
||||
{{< card link="../guide/configuration" title="設定" icon="adjustments" >}}
|
||||
{{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,211 @@
|
||||
---
|
||||
title: Getting Started
|
||||
weight: 1
|
||||
tags:
|
||||
- Docs
|
||||
- Guide
|
||||
next: /docs/guide
|
||||
prev: /docs
|
||||
---
|
||||
|
||||
## Quick Start from Template
|
||||
|
||||
{{< icon "github" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)
|
||||
|
||||
You could quickly get started by using the above template repository.
|
||||
|
||||
<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500" alt="GitHub repository page showing the Use this template button">
|
||||
|
||||
We have provided a [GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) which can help automatically build and deploy your site to GitHub Pages, and host it for free.
|
||||
For more options, check out [Deploy Site](../guide/deploy-site).
|
||||
|
||||
[🌐 Demo ↗](https://imfing.github.io/hextra-starter-template/)
|
||||
|
||||
## Start as New Project
|
||||
|
||||
There are two main ways to add the Hextra theme to your Hugo project:
|
||||
|
||||
1. **Hugo Modules (Recommended)**: The simplest and recommended method. [Hugo modules](https://gohugo.io/hugo-modules/) let you pull in the theme directly from its online source. Theme is downloaded automatically and managed by Hugo.
|
||||
|
||||
2. **Git Submodule**: Alternatively, add Hextra as a [Git Submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). The theme is downloaded by Git and stored in your project's `themes` folder.
|
||||
|
||||
### Setup Hextra as Hugo module
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
Before starting, you need to have the following software installed:
|
||||
|
||||
- [Hugo (extended version)](https://gohugo.io/installation/)
|
||||
- [Git](https://git-scm.com/)
|
||||
- [Go](https://go.dev/)
|
||||
|
||||
#### Steps
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### Initialize a new Hugo site
|
||||
|
||||
```shell
|
||||
hugo new site my-site --format=yaml
|
||||
```
|
||||
|
||||
### Configure Hextra theme via module
|
||||
|
||||
```shell
|
||||
# initialize hugo module
|
||||
cd my-site
|
||||
hugo mod init github.com/username/my-site
|
||||
|
||||
# add Hextra theme
|
||||
hugo mod get github.com/imfing/hextra
|
||||
```
|
||||
|
||||
Configure `hugo.yaml` to use Hextra theme by adding the following:
|
||||
|
||||
```yaml
|
||||
module:
|
||||
imports:
|
||||
- path: github.com/imfing/hextra
|
||||
```
|
||||
|
||||
### Create your first content pages
|
||||
|
||||
Create new content page for the home page and the documentation page:
|
||||
|
||||
```shell
|
||||
hugo new content/_index.md
|
||||
hugo new content/docs/_index.md
|
||||
```
|
||||
|
||||
### Preview the site locally
|
||||
|
||||
```shell
|
||||
hugo server --buildDrafts --disableFastRender
|
||||
```
|
||||
|
||||
Voila, your new site preview is available at `http://localhost:1313/`.
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
|
||||
{{% details title="How to update theme?" %}}
|
||||
|
||||
To update all Hugo modules in your project to their latest versions, run the following command:
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
To update Hextra to the [latest released version](https://github.com/imfing/hextra/releases), run the following command:
|
||||
|
||||
```shell
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
If you want to try the most recent changes before the next release, update the module to the development branch directly (⚠️ may contain unstable/breaking changes):
|
||||
|
||||
```shell
|
||||
hugo mod get -u github.com/imfing/hextra@main
|
||||
```
|
||||
|
||||
See [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/#update-all-modules) for more details.
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
|
||||
### Setup Hextra as Git submodule
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
Before starting, you need to have the following software installed:
|
||||
|
||||
- [Hugo (extended version)](https://gohugo.io/installation/)
|
||||
- [Git](https://git-scm.com/)
|
||||
|
||||
#### Steps
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### Initialize a new Hugo site
|
||||
|
||||
```shell
|
||||
hugo new site my-site --format=yaml
|
||||
```
|
||||
|
||||
### Add Hextra theme as a Git submodule
|
||||
|
||||
Switch to the site directory and initialize a new Git repository:
|
||||
|
||||
```shell
|
||||
cd my-site
|
||||
git init
|
||||
```
|
||||
|
||||
Then, add Hextra theme as a Git submodule:
|
||||
|
||||
```shell
|
||||
git submodule add https://github.com/imfing/hextra.git themes/hextra
|
||||
```
|
||||
|
||||
Configure `hugo.yaml` to use Hextra theme by adding the following:
|
||||
|
||||
```yaml
|
||||
theme: hextra
|
||||
```
|
||||
|
||||
### Create your first content pages
|
||||
|
||||
Create new content page for the home page and the documentation page:
|
||||
|
||||
```shell
|
||||
hugo new content/_index.md
|
||||
hugo new content/docs/_index.md
|
||||
```
|
||||
|
||||
### Preview the site locally
|
||||
|
||||
```shell
|
||||
hugo server --buildDrafts --disableFastRender
|
||||
```
|
||||
|
||||
Your new site preview is available at `http://localhost:1313/`.
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
|
||||
When using [CI/CD](https://en.wikipedia.org/wiki/CI/CD) for Hugo website deployment, it's essential to ensure that the following command is executed before running the `hugo` command.
|
||||
|
||||
```shell
|
||||
git submodule update --init
|
||||
```
|
||||
|
||||
Failure to run this command results in the theme folder not being populated with Hextra theme files, leading to a build failure.
|
||||
|
||||
|
||||
{{% details title="How to update theme?" %}}
|
||||
|
||||
To update all submodules in your repository to their latest commits, run the following command:
|
||||
|
||||
```shell
|
||||
git submodule update --remote
|
||||
```
|
||||
|
||||
To update Hextra to the latest commit, run the following command:
|
||||
|
||||
```shell
|
||||
git submodule update --remote themes/hextra
|
||||
```
|
||||
|
||||
See [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for more details.
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
## Next
|
||||
|
||||
Explore the following sections to start adding more contents:
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="../guide/organize-files" title="Organize Files" icon="document-duplicate" >}}
|
||||
{{< card link="../guide/configuration" title="Configuration" icon="adjustments" >}}
|
||||
{{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,204 @@
|
||||
---
|
||||
title: 快速开始
|
||||
weight: 1
|
||||
tags:
|
||||
- 文档
|
||||
- 指南
|
||||
next: /docs/guide
|
||||
prev: /docs
|
||||
---
|
||||
|
||||
## 从模板快速启动
|
||||
|
||||
{{< icon "github" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)
|
||||
|
||||
您可以通过使用上述模板仓库快速开始。
|
||||
|
||||
<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500" alt="显示“Use this template”按钮的 GitHub 仓库页面">
|
||||
|
||||
我们提供了一个[GitHub Actions工作流](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)，可以帮助自动构建并将您的站点部署到GitHub Pages，并免费托管。
|
||||
更多选项，请查看[部署站点](../guide/deploy-site)。
|
||||
|
||||
[🌐 演示 ↗](https://imfing.github.io/hextra-starter-template/)
|
||||
|
||||
## 作为新项目启动
|
||||
|
||||
有两种主要方式将Hextra主题添加到您的Hugo项目中：
|
||||
|
||||
1. **Hugo模块（推荐）**：最简单且推荐的方法。[Hugo模块](https://gohugo.io/hugo-modules/)允许您直接从在线源拉取主题。主题会自动下载并由Hugo管理。
|
||||
|
||||
2. **Git子模块**：或者，将Hextra添加为[Git子模块](https://git-scm.com/book/en/v2/Git-Tools-Submodules)。主题由Git下载并存储在项目的`themes`文件夹中。
|
||||
|
||||
### 将Hextra设置为Hugo模块
|
||||
|
||||
#### 先决条件
|
||||
|
||||
在开始之前，您需要安装以下软件：
|
||||
|
||||
- [Hugo（扩展版）](https://gohugo.io/installation/)
|
||||
- [Git](https://git-scm.com/)
|
||||
- [Go](https://go.dev/)
|
||||
|
||||
#### 步骤
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### 初始化一个新的Hugo站点
|
||||
|
||||
```shell
|
||||
hugo new site my-site --format=yaml
|
||||
```
|
||||
|
||||
### 通过模块配置Hextra主题
|
||||
|
||||
```shell
|
||||
# 初始化Hugo模块
|
||||
cd my-site
|
||||
hugo mod init github.com/username/my-site
|
||||
|
||||
# 添加Hextra主题
|
||||
hugo mod get github.com/imfing/hextra
|
||||
```
|
||||
|
||||
配置`hugo.yaml`以使用Hextra主题，添加以下内容：
|
||||
|
||||
```yaml
|
||||
module:
|
||||
imports:
|
||||
- path: github.com/imfing/hextra
|
||||
```
|
||||
|
||||
### 创建您的内容页面
|
||||
|
||||
为主页和文档页面创建新内容：
|
||||
|
||||
```shell
|
||||
hugo new content/_index.md
|
||||
hugo new content/docs/_index.md
|
||||
```
|
||||
|
||||
### 本地预览站点
|
||||
|
||||
```shell
|
||||
hugo server --buildDrafts --disableFastRender
|
||||
```
|
||||
|
||||
恭喜，您的新站点预览可在`http://localhost:1313/`查看。
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
|
||||
{{% details title="如何更新主题？" %}}
|
||||
|
||||
要更新项目中的所有Hugo模块到最新版本，运行以下命令：
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
要将Hextra更新到[最新发布版本](https://github.com/imfing/hextra/releases)，运行以下命令：
|
||||
|
||||
```shell
|
||||
hugo mod get -u github.com/imfing/hextra
|
||||
```
|
||||
|
||||
更多详情请参阅[Hugo模块](https://gohugo.io/hugo-modules/use-modules/#update-all-modules)。
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
### 将Hextra设置为Git子模块
|
||||
|
||||
#### 先决条件
|
||||
|
||||
在开始之前，您需要安装以下软件：
|
||||
|
||||
- [Hugo（扩展版）](https://gohugo.io/installation/)
|
||||
- [Git](https://git-scm.com/)
|
||||
|
||||
#### 步骤
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### 初始化一个新的Hugo站点
|
||||
|
||||
```shell
|
||||
hugo new site my-site --format=yaml
|
||||
```
|
||||
|
||||
### 将Hextra主题添加为Git子模块
|
||||
|
||||
切换到站点目录并初始化一个新的Git仓库：
|
||||
|
||||
```shell
|
||||
cd my-site
|
||||
git init
|
||||
```
|
||||
|
||||
然后，将Hextra主题添加为Git子模块：
|
||||
|
||||
```shell
|
||||
git submodule add https://github.com/imfing/hextra.git themes/hextra
|
||||
```
|
||||
|
||||
配置`hugo.yaml`以使用Hextra主题，添加以下内容：
|
||||
|
||||
```yaml
|
||||
theme: hextra
|
||||
```
|
||||
|
||||
### 创建您的内容页面
|
||||
|
||||
为主页和文档页面创建新内容：
|
||||
|
||||
```shell
|
||||
hugo new content/_index.md
|
||||
hugo new content/docs/_index.md
|
||||
```
|
||||
|
||||
### 本地预览站点
|
||||
|
||||
```shell
|
||||
hugo server --buildDrafts --disableFastRender
|
||||
```
|
||||
|
||||
您的新站点预览可在`http://localhost:1313/`查看。
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
|
||||
当使用[CI/CD](https://en.wikipedia.org/wiki/CI/CD)部署Hugo网站时，确保在运行`hugo`命令之前执行以下命令至关重要。
|
||||
|
||||
```shell
|
||||
git submodule update --init
|
||||
```
|
||||
|
||||
如果不运行此命令，主题文件夹将不会被填充Hextra主题文件，导致构建失败。
|
||||
|
||||
|
||||
{{% details title="如何更新主题？" %}}
|
||||
|
||||
要更新仓库中的所有子模块到最新提交，运行以下命令：
|
||||
|
||||
```shell
|
||||
git submodule update --remote
|
||||
```
|
||||
|
||||
要将Hextra更新到最新提交，运行以下命令：
|
||||
|
||||
```shell
|
||||
git submodule update --remote themes/hextra
|
||||
```
|
||||
|
||||
更多详情请参阅[Git子模块](https://git-scm.com/book/en/v2/Git-Tools-Submodules)。
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
## 下一步
|
||||
|
||||
探索以下部分以开始添加更多内容：
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="../guide/organize-files" title="组织文件" icon="document-duplicate" >}}
|
||||
{{< card link="../guide/configuration" title="配置" icon="adjustments" >}}
|
||||
{{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: راهنما
|
||||
weight: 2
|
||||
prev: /docs/getting-started
|
||||
next: /docs/guide/organize-files
|
||||
sidebar:
|
||||
open: true
|
||||
---
|
||||
|
||||
برای یادگیری نحوه استفاده از Hextra، بخشهای زیر را بررسی کنید:
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="organize-files" title="سازماندهی فایلها" icon="document-duplicate" >}}
|
||||
{{< card link="configuration" title="پیکربندی" icon="adjustments" >}}
|
||||
{{< card link="markdown" title="Markdown" icon="markdown" >}}
|
||||
{{< card link="syntax-highlighting" title="رنگآمیزی نحوه" icon="sparkles" >}}
|
||||
{{< card link="latex" title="LaTeX" icon="variable" >}}
|
||||
{{< card link="diagrams" title="نمودارها" icon="chart-square-bar" >}}
|
||||
{{< card link="shortcodes" title="کدهای کوتاه" icon="template" >}}
|
||||
{{< card link="deploy-site" title="استقرار سایت" icon="server" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: ガイド
|
||||
weight: 2
|
||||
prev: /docs/getting-started
|
||||
next: /docs/guide/organize-files
|
||||
sidebar:
|
||||
open: true
|
||||
---
|
||||
|
||||
Hextra の使い方を学ぶには、以下のセクションを参照してください:
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="organize-files" title="ファイルの整理" icon="document-duplicate" >}}
|
||||
{{< card link="configuration" title="設定" icon="adjustments" >}}
|
||||
{{< card link="markdown" title="Markdown" icon="markdown" >}}
|
||||
{{< card link="syntax-highlighting" title="シンタックスハイライト" icon="sparkles" >}}
|
||||
{{< card link="latex" title="LaTeX" icon="variable" >}}
|
||||
{{< card link="diagrams" title="ダイアグラム" icon="chart-square-bar" >}}
|
||||
{{< card link="shortcodes" title="ショートコード" icon="template" >}}
|
||||
{{< card link="deploy-site" title="サイトのデプロイ" icon="server" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Guide
|
||||
weight: 2
|
||||
prev: /docs/getting-started
|
||||
next: /docs/guide/organize-files
|
||||
sidebar:
|
||||
open: true
|
||||
---
|
||||
|
||||
Explore the following sections to learn how to use Hextra:
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="organize-files" title="Organize Files" icon="document-duplicate" >}}
|
||||
{{< card link="configuration" title="Configuration" icon="adjustments" >}}
|
||||
{{< card link="markdown" title="Markdown" icon="markdown" >}}
|
||||
{{< card link="syntax-highlighting" title="Syntax Highlighting" icon="sparkles" >}}
|
||||
{{< card link="latex" title="LaTeX" icon="variable" >}}
|
||||
{{< card link="diagrams" title="Diagrams" icon="chart-square-bar" >}}
|
||||
{{< card link="shortcodes" title="Shortcodes" icon="template" >}}
|
||||
{{< card link="deploy-site" title="Deploy Site" icon="server" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: 指南
|
||||
weight: 2
|
||||
prev: /docs/getting-started
|
||||
next: /docs/guide/organize-files
|
||||
sidebar:
|
||||
open: true
|
||||
---
|
||||
|
||||
通过以下章节了解如何使用 Hextra：
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="organize-files" title="文件组织" icon="document-duplicate" >}}
|
||||
{{< card link="configuration" title="配置" icon="adjustments" >}}
|
||||
{{< card link="markdown" title="Markdown" icon="markdown" >}}
|
||||
{{< card link="syntax-highlighting" title="语法高亮" icon="sparkles" >}}
|
||||
{{< card link="latex" title="LaTeX" icon="variable" >}}
|
||||
{{< card link="diagrams" title="图表" icon="chart-square-bar" >}}
|
||||
{{< card link="shortcodes" title="短代码" icon="template" >}}
|
||||
{{< card link="deploy-site" title="部署站点" icon="server" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,629 @@
|
||||
---
|
||||
title: پیکربندی
|
||||
weight: 2
|
||||
tags:
|
||||
- پیکربندی
|
||||
---
|
||||
|
||||
Hugo تنظیمات خود را از فایل `hugo.yaml` در ریشه سایت شما میخواند.
|
||||
فایل پیکربندی جایی است که میتوانید تمام جنبههای سایت خود را تنظیم کنید.
|
||||
برای آشنایی جامع با تنظیمات موجود و بهترین روشها، فایل پیکربندی این سایت [`docs/hugo.yaml`](https://github.com/imfing/hextra/blob/main/docs/hugo.yaml) را در GitHub بررسی کنید.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## ناوبری
|
||||
|
||||
### منو
|
||||
|
||||
منوی بالای صفحه در بخش `menu.main` در فایل پیکربندی تعریف میشود:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- name: مستندات
|
||||
pageRef: /docs
|
||||
weight: 1
|
||||
- name: وبلاگ
|
||||
pageRef: /blog
|
||||
weight: 2
|
||||
- name: درباره
|
||||
pageRef: /about
|
||||
weight: 3
|
||||
- name: جستجو
|
||||
weight: 4
|
||||
params:
|
||||
type: search
|
||||
- name: GitHub
|
||||
weight: 5
|
||||
url: "https://github.com/imfing/hextra"
|
||||
params:
|
||||
icon: github
|
||||
```
|
||||
|
||||
انواع مختلفی از آیتمهای منو وجود دارد:
|
||||
|
||||
1. لینک به یک صفحه در سایت با `pageRef`
|
||||
```yaml
|
||||
- name: مستندات
|
||||
pageRef: /docs
|
||||
```
|
||||
2. لینک به یک URL خارجی با `url`
|
||||
```yaml
|
||||
- name: GitHub
|
||||
url: "https://github.com"
|
||||
```
|
||||
3. نوار جستجو با `type: search`
|
||||
```yaml
|
||||
- name: جستجو
|
||||
params:
|
||||
type: search
|
||||
```
|
||||
4. آیکون
|
||||
```yaml
|
||||
- name: GitHub
|
||||
params:
|
||||
icon: github
|
||||
```
|
||||
5. تبديل السمة
|
||||
```yaml
|
||||
- name: Theme Toggle
|
||||
params:
|
||||
type: theme-toggle
|
||||
label: true # optional, default is false
|
||||
```
|
||||
6. مُبدِّل اللغة
|
||||
```yaml
|
||||
- name: مُبدِّل اللغة
|
||||
params:
|
||||
type: language-switch
|
||||
label: true # optional, default is false
|
||||
icon: "globe-alt" # optional, default is "translate"
|
||||
```
|
||||
|
||||
این آیتمهای منو را میتوان با تنظیم پارامتر `weight` مرتب کرد.
|
||||
|
||||
### منوهای تو در تو
|
||||
|
||||
با تعریف آیتمهای منوی فرزند میتوانید منوهای کشویی ایجاد کنید. منوهای فرزند با کلیک روی آیتم منوی والد نمایش داده میشوند.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: sdk
|
||||
name: SDK
|
||||
- identifier: python
|
||||
name: Python ↗
|
||||
url: https://python.org
|
||||
parent: sdk
|
||||
- identifier: go
|
||||
name: Go
|
||||
url: https://go.dev
|
||||
parent: sdk
|
||||
```
|
||||
|
||||
آیتمهای منوی فرزند باید پارامتر `parent` را با مقدار `identifier` والد مشخص کنند.
|
||||
|
||||
### لوگو و عنوان
|
||||
|
||||
برای تغییر لوگوی پیشفرض، فایل `hugo.yaml` را ویرایش کرده و مسیر فایل لوگوی خود را در دایرکتوری `static` اضافه کنید.
|
||||
همچنین میتوانید لینکی که کاربران با کلیک روی لوگو به آن هدایت میشوند را تغییر دهید و عرض و ارتفاع لوگو را بر حسب پیکسل تنظیم کنید.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
navbar:
|
||||
displayTitle: true
|
||||
displayLogo: true
|
||||
logo:
|
||||
path: images/logo.svg
|
||||
dark: images/logo-dark.svg
|
||||
link: /
|
||||
width: 40
|
||||
height: 20
|
||||
```
|
||||
|
||||
### صفحهبندی
|
||||
|
||||
برای غیرفعال کردن ناوبری قبلی/بعدی در پایین صفحات مستندات یا مقالات وبلاگ:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
displayPagination: false # برای صفحات مستندات
|
||||
blog:
|
||||
article:
|
||||
displayPagination: false # برای مقالات وبلاگ
|
||||
```
|
||||
|
||||
## نوار کناری
|
||||
|
||||
### نوار کناری اصلی
|
||||
|
||||
برای نوار کناری اصلی، به طور خودکار از ساختار دایرکتوری محتوا ایجاد میشود.
|
||||
برای جزئیات بیشتر به صفحه [سازماندهی فایلها](/docs/guide/organize-files) مراجعه کنید.
|
||||
|
||||
برای حذف یک صفحه از نوار کناری چپ، پارامتر `sidebar.exclude` را در front matter صفحه تنظیم کنید:
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: پیکربندی
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
```
|
||||
|
||||
### لینکهای اضافی
|
||||
|
||||
لینکهای اضافی نوار کناری در بخش `menu.sidebar` در فایل پیکربندی تعریف میشوند:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
sidebar:
|
||||
- name: بیشتر
|
||||
params:
|
||||
type: separator
|
||||
weight: 1
|
||||
- name: "درباره"
|
||||
pageRef: "/about"
|
||||
weight: 2
|
||||
- name: "مستندات Hugo ↗"
|
||||
url: "https://gohugo.io/documentation/"
|
||||
weight: 3
|
||||
```
|
||||
|
||||
## نوار کناری راست
|
||||
|
||||
### فهرست مطالب
|
||||
|
||||
فهرست مطالب به طور خودکار از عناوین موجود در فایل محتوا ایجاد میشود. میتوانید آن را با تنظیم `toc: false` در front matter صفحه غیرفعال کنید.
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: پیکربندی
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
|
||||
### لینک ویرایش صفحه
|
||||
|
||||
برای پیکربندی لینک ویرایش صفحه، میتوانیم پارامتر `params.editURL.base` را در فایل پیکربندی تنظیم کنیم:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
editURL:
|
||||
enable: true
|
||||
base: "https://github.com/your-username/your-repo/edit/main"
|
||||
```
|
||||
|
||||
لینکهای ویرایش به طور خودکار برای هر صفحه بر اساس URL ارائه شده به عنوان دایرکتوری ریشه ایجاد میشوند.
|
||||
اگر میخواهید لینک ویرایش را برای یک صفحه خاص تنظیم کنید، میتوانید پارامتر `editURL` را در front matter صفحه تنظیم کنید:
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: پیکربندی
|
||||
editURL: "https://example.com/edit/this/page"
|
||||
---
|
||||
```
|
||||
|
||||
## پاورقی
|
||||
|
||||
### کپی رایت
|
||||
|
||||
برای تغییر متن کپی رایت نمایش داده شده در پاورقی سایت، باید یک فایل به نام `i18n/en.yaml` ایجاد کنید.
|
||||
در این فایل، متن جدید کپی رایت را به صورت زیر مشخص کنید:
|
||||
|
||||
```yaml {filename="i18n/en.yaml"}
|
||||
copyright: "© 2024 متن دلخواه شما"
|
||||
```
|
||||
|
||||
برای مرجع، یک فایل نمونه [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) در مخزن GitHub موجود است. همچنین میتوانید از قالب Markdown در متن کپی رایت استفاده کنید.
|
||||
|
||||
## سایر موارد
|
||||
|
||||
### فاوآیکون
|
||||
|
||||
برای سفارشی کردن [فاوآیکون](https://fa.wikipedia.org/wiki/فاوآیکون) سایت، فایلهای آیکون را در پوشه `static` قرار دهید تا [فاوآیکونهای پیشفرض قالب](https://github.com/imfing/hextra/tree/main/static) را جایگزین کنید:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="static" >}}
|
||||
{{< filetree/file name="android-chrome-192x192.png" >}}
|
||||
{{< filetree/file name="android-chrome-512x512.png" >}}
|
||||
{{< filetree/file name="apple-touch-icon.png" >}}
|
||||
{{< filetree/file name="favicon-16x16.png" >}}
|
||||
{{< filetree/file name="favicon-32x32.png" >}}
|
||||
{{< filetree/file name="favicon-dark.svg" >}}
|
||||
{{< filetree/file name="favicon.ico" >}}
|
||||
{{< filetree/file name="favicon.svg" >}}
|
||||
{{< filetree/file name="site.webmanifest" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
#### تنظیمات پایه
|
||||
|
||||
حداقل، فایل `favicon.svg` را در پوشه `static` قرار دهید. این فایل به عنوان فاوآیکون پیشفرض سایت استفاده میشود.
|
||||
|
||||
میتوانید یک فاوآیکون SVG تطبیقی ایجاد کنید که به ترجیحات تم سیستم پاسخ دهد با استفاده از media queryهای CSS درون خود SVG، با پیروی از روش توضیح داده شده در [ساخت یک فاوآیکون تطبیقی](https://web.dev/articles/building/an-adaptive-favicon).
|
||||
|
||||
#### پشتیبانی از حالت تاریک
|
||||
|
||||
برای پشتیبانی بهتر از حالت تاریک، فایل `favicon-dark.svg` را در کنار `favicon.svg` در پوشه `static` قرار دهید. وقتی هر دو فایل موجود باشند، Hextra به طور خودکار:
|
||||
|
||||
- از `favicon.svg` برای حالت روشن یا زمانی که ترجیح تمی مشخص نشده استفاده میکند
|
||||
- به `favicon-dark.svg` تغییر میکند وقتی سیستم کاربر در حالت تاریک تنظیم شده است
|
||||
- تنظیمات `prefers-color-scheme` سیستم را برای تغییر خودکار رعایت میکند
|
||||
|
||||
تغییر فاوآیکون حالت تاریک در تمام مرورگرهای مدرن، از جمله Firefox، کار میکند و تجربهای یکپارچه که با تم سایت شما مطابقت دارد ارائه میدهد.
|
||||
|
||||
#### فرمتهای اضافی
|
||||
|
||||
در حالی که `favicon.ico` عمدتاً برای مرورگرهای قدیمی است، مرورگرهای مدرن از فاوآیکونهای SVG پشتیبانی میکنند که به دلیل مقیاسپذیری و حجم کم فایل ترجیح داده میشوند.
|
||||
در صورت نیاز از ابزارهایی مانند [favicon.io](https://favicon.io/) یا [favycon](https://github.com/ruisaraiva19/favycon) برای تولید فرمتهای اضافی فاوآیکون استفاده کنید.
|
||||
|
||||
### پیکربندی تم
|
||||
|
||||
از تنظیم `theme` برای پیکربندی حالت پیشفرض تم و دکمه تغییر تم استفاده کنید، که به بازدیدکنندگان امکان تغییر بین حالت روشن یا تاریک را میدهد.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
theme:
|
||||
# light | dark | system
|
||||
default: system
|
||||
displayToggle: true
|
||||
```
|
||||
|
||||
گزینههای `theme.default`:
|
||||
|
||||
- `light` - همیشه از حالت روشن استفاده کنید
|
||||
- `dark` - همیشه از حالت تاریک استفاده کنید
|
||||
- `system` - همگام با تنظیمات سیستم عامل (پیشفرض)
|
||||
|
||||
پارامتر `theme.displayToggle` به شما امکان میدهد دکمهای برای تغییر تم نمایش دهید.
|
||||
وقتی روی `true` تنظیم شود، بازدیدکنندگان میتوانند بین حالت روشن یا تاریک تغییر دهند و تنظیم پیشفرض را لغو کنند.
|
||||
|
||||
### آخرین تغییر صفحه
|
||||
|
||||
تاریخ آخرین تغییر صفحه را میتوان با فعال کردن پرچم `params.displayUpdatedDate` نمایش داد. برای استفاده از تاریخ commit Git به عنوان منبع، پرچم `enableGitInfo` را نیز فعال کنید.
|
||||
|
||||
برای سفارشی کردن فرمت تاریخ، پارامتر `params.dateFormat` را تنظیم کنید. چیدمان آن با [`time.Format`](https://gohugo.io/functions/time/format/) Hugo مطابقت دارد.
|
||||
|
||||
علاوه بر این، میتوانید با فعال کردن پرچم `params.displayUpdatedAuthor` نویسنده آخرین تغییر را نمایش دهید. این نیاز به تنظیم `enableGitInfo: true` دارد.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
# تجزیه commit Git
|
||||
enableGitInfo: true
|
||||
|
||||
params:
|
||||
# نمایش تاریخ آخرین تغییر
|
||||
displayUpdatedDate: true
|
||||
dateFormat: "January 2, 2006"
|
||||
# نمایش نویسنده آخرین تغییر
|
||||
displayUpdatedAuthor: true
|
||||
```
|
||||
|
||||
### برچسبها
|
||||
|
||||
برای نمایش برچسبهای صفحه، پرچمهای زیر را در فایل پیکربندی تنظیم کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
blog:
|
||||
list:
|
||||
displayTags: true
|
||||
toc:
|
||||
displayTags: true
|
||||
```
|
||||
|
||||
Hugo بهصورت پیشفرض برای `tags` و `categories` صفحههای taxonomy میسازد. اگر سایت شما از صفحههای taxonomy استفاده نمیکند و میخواهید پوشههای تولیدشده `public/tags/` و `public/categories/` حذف شوند، نوع صفحههای `taxonomy` و `term` را غیرفعال کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
disableKinds:
|
||||
- taxonomy
|
||||
- term
|
||||
```
|
||||
|
||||
فقط زمانی این نوعها را غیرفعال کنید که به صفحههای آرشیو برچسب یا دستهبندی وابسته نیستید.
|
||||
|
||||
### بزرگنمایی تصویر
|
||||
|
||||
بزرگنمایی تصویر به طور پیشفرض غیرفعال است. وقتی فعال شود، کلیک روی تصویر Markdown یک نمای بزرگنمایی شده باز میکند.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
```
|
||||
|
||||
برای غیرفعال کردن بزرگنمایی در یک صفحه خاص، این را به front matter صفحه اضافه کنید:
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
imageZoom: false
|
||||
---
|
||||
```
|
||||
|
||||
اگر میخواهید asset Medium Zoom را پین کنید یا از assetهای محلی بارگذاری کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
base: "https://cdn.jsdelivr.net/npm/medium-zoom@1.1.0/dist"
|
||||
# js: "js/medium-zoom.min.js" # اختیاری، نسبت به base یا assetهای محلی
|
||||
```
|
||||
|
||||
### اسکریپتهای محلی و آینهشده
|
||||
|
||||
Hextra میتواند وابستگیهای اختیاری فرانتاند را از منابع مختلف بارگیری کند:
|
||||
|
||||
- تنظیمات پیشفرض قالب (CDN)
|
||||
- URLهای آینه داخلی از طریق `base`
|
||||
- assetهای محلی Hugo از طریق `js` / `css`
|
||||
|
||||
برای assetهای محلی، فایلهای vendor را در پوشه `assets/` سایت خود قرار دهید و مقادیر پیکربندی را به همان مسیرهای asset اشاره دهید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
js: "js/vendor/medium-zoom.min.js"
|
||||
|
||||
mermaid:
|
||||
js: "js/vendor/mermaid.min.js"
|
||||
|
||||
asciinema:
|
||||
js: "js/vendor/asciinema-player.min.js"
|
||||
css: "css/vendor/asciinema-player.css"
|
||||
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
css: "css/vendor/katex.min.css"
|
||||
assets:
|
||||
- "fonts/KaTeX_Main-Regular.woff2"
|
||||
- "fonts/KaTeX_Math-Italic.woff2"
|
||||
|
||||
search:
|
||||
type: flexsearch
|
||||
flexsearch:
|
||||
js: "js/vendor/flexsearch.bundle.min.js"
|
||||
```
|
||||
|
||||
`imageZoom.enable: true` فقط به این دلیل لازم است که بزرگنمایی تصویر بهصورت پیشفرض غیرفعال است.
|
||||
برای KaTeX، مطمئن شوید همه فایلهای فونتی که فایل CSS انتخابی شما به آنها ارجاع میدهد منتشر میشوند، نه فقط دو موردی که در این مثال آمدهاند.
|
||||
|
||||
برای استفاده از یک آینه داخلی، `base` را تنظیم کنید (و در صورت تفاوت نام فایل، در صورت نیاز `js` / `css` را نیز مشخص کنید):
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
base: "https://mirror.example.com/medium-zoom/dist"
|
||||
|
||||
mermaid:
|
||||
base: "https://mirror.example.com/mermaid/dist"
|
||||
|
||||
asciinema:
|
||||
base: "https://mirror.example.com/asciinema-player/dist/bundle"
|
||||
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
base: "https://mirror.example.com/katex/dist"
|
||||
|
||||
search:
|
||||
flexsearch:
|
||||
base: "https://mirror.example.com/flexsearch/dist"
|
||||
# js: "flexsearch.bundle.min.js"
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> برای سفارشیسازی منبع بارگذاری MathJax، قالب `layouts/_partials/scripts/mathjax.html` را در پروژه خود بازنویسی کنید.
|
||||
|
||||
### عرض صفحه
|
||||
|
||||
عرض پوستهٔ صفحه را میتوان با پارامتر `params.page.width` تنظیم کرد:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
# full (100%), wide (90rem), normal (1280px)
|
||||
width: wide
|
||||
```
|
||||
|
||||
گزینههای `params.page.width`: `full`، `wide`، و `normal`.
|
||||
|
||||
عرض محتوای اصلی به صورت پیشفرض روی `72rem` ثابت است.
|
||||
|
||||
برای سفارشیسازی عرض محتوا، متغیر CSS را در فایل استایل سفارشی خود بازنویسی کنید:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
--hextra-max-content-width: 100%;
|
||||
}
|
||||
```
|
||||
|
||||
به طور مشابه، عرض نوار ناوبری و پاورقی را میتوان با پارامترهای `params.navbar.width` و `params.footer.width` سفارشی کرد.
|
||||
|
||||
### منوی زمینه صفحه
|
||||
|
||||
منوی زمینه صفحه یک دکمه کشویی ارائه میدهد که به کاربران امکان میدهد محتوای صفحه را به صورت Markdown کپی کنند یا منبع Markdown خام را مشاهده کنند. این ویژگی برای سایتهای مستندات که خوانندگان ممکن است بخواهند محتوا را در قالب Markdown به اشتراک بگذارند یا به آن ارجاع دهند، مفید است.
|
||||
|
||||
#### فعالسازی منوی زمینه
|
||||
|
||||
برای فعالسازی سراسری منوی زمینه، موارد زیر را به فایل پیکربندی خود اضافه کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
```
|
||||
|
||||
همچنین باید فرمت خروجی `markdown` را برای صفحات فعال کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
page: [html, markdown]
|
||||
section: [html, rss, markdown]
|
||||
```
|
||||
|
||||
#### کنترل هر صفحه
|
||||
|
||||
برای فعال یا غیرفعال کردن منوی زمینه برای یک صفحه خاص، از پارامتر `contextMenu` در front matter استفاده کنید:
|
||||
|
||||
```yaml {filename="content/docs/example.md"}
|
||||
---
|
||||
title: صفحه نمونه
|
||||
contextMenu: false
|
||||
---
|
||||
```
|
||||
|
||||
#### لینکهای سفارشی
|
||||
|
||||
میتوانید لینکهای سفارشی به منوی کشویی زمینه اضافه کنید. این برای یکپارچهسازی با سرویسهای خارجی مفید است. لینکها از جایگزینهای زیر پشتیبانی میکنند:
|
||||
|
||||
- `{url}` - آدرس صفحه (URL-encoded)
|
||||
- `{title}` - عنوان صفحه (URL-encoded)
|
||||
- `{markdown_url}` - آدرس محتوای Markdown خام (URL-encoded)
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
links:
|
||||
- name: باز کردن در ChatGPT
|
||||
icon: chatgpt
|
||||
url: "https://chatgpt.com/?hints=search&q=I%27m+looking+at+this+documentation%3A+{url}%0AHelp+me+understand+how+to+use+it."
|
||||
```
|
||||
|
||||
هر لینک میتواند شامل موارد زیر باشد:
|
||||
- `name` - متن نمایشی لینک
|
||||
- `icon` - نام آیکون اختیاری (به [آیکونها]({{% relref "docs/guide/shortcodes/icon" %}}) مراجعه کنید)
|
||||
- `url` - آدرس با جایگزینهای اختیاری
|
||||
|
||||
### نمایه FlexSearch
|
||||
|
||||
جستجوی تمام متن با قدرت [FlexSearch](https://github.com/nextapps-de/flexsearch) به طور پیشفرض فعال است.
|
||||
برای سفارشی کردن نمایه جستجو، پارامتر `params.search.flexsearch.index` را در فایل پیکربندی تنظیم کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
# جستجو
|
||||
search:
|
||||
enable: true
|
||||
type: flexsearch
|
||||
|
||||
flexsearch:
|
||||
# نمایه صفحه بر اساس: content | summary | heading | title
|
||||
index: content
|
||||
```
|
||||
|
||||
همچنین میتوانید محل بارگیری runtime مربوط به FlexSearch را کنترل کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
search:
|
||||
flexsearch:
|
||||
version: "0.8.143" # نسخه پیشفرض CDN
|
||||
# base: "https://mirror.example.com/flexsearch/dist" # آدرس پایهٔ remote اختیاری
|
||||
# js: "js/vendor/flexsearch.bundle.min.js" # مسیر asset محلی یا فایل سفارشی زیر base راه دور
|
||||
```
|
||||
|
||||
گزینههای `flexsearch.index`:
|
||||
|
||||
- `content` - محتوای کامل صفحه (پیشفرض)
|
||||
- `summary` - خلاصه صفحه، برای جزئیات بیشتر به [خلاصههای محتوای Hugo](https://gohugo.io/content-management/summaries/) مراجعه کنید
|
||||
- `heading` - عناوین سطح 1 و سطح 2
|
||||
- `title` - فقط عنوان صفحه را شامل شود
|
||||
|
||||
برای سفارشی کردن tokenize جستجو، پارامتر `params.search.flexsearch.tokenize` را در فایل پیکربندی تنظیم کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
search:
|
||||
# ...
|
||||
flexsearch:
|
||||
# full | forward | reverse | strict
|
||||
tokenize: forward
|
||||
```
|
||||
|
||||
گزینههای [`flexsearch.tokenize`](https://github.com/nextapps-de/flexsearch/#tokenizer-prefix-search):
|
||||
|
||||
- `strict` - نمایهگذاری کل کلمات
|
||||
- `forward` - نمایهگذاری تدریجی کلمات در جهت جلو
|
||||
- `reverse` - نمایهگذاری تدریجی کلمات در هر دو جهت
|
||||
- `full` - نمایهگذاری هر ترکیب ممکن
|
||||
|
||||
برای حذف یک صفحه از نمایه جستجوی FlexSearch، `excludeSearch: true` را در front matter صفحه تنظیم کنید:
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: پیکربندی
|
||||
excludeSearch: true
|
||||
---
|
||||
```
|
||||
|
||||
### Google Analytics
|
||||
|
||||
برای فعال کردن [Google Analytics](https://marketingplatform.google.com/about/analytics/)، پرچم `services.googleAnalytics.ID` را در `hugo.yaml` تنظیم کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
services:
|
||||
googleAnalytics:
|
||||
ID: G-MEASUREMENT_ID
|
||||
```
|
||||
|
||||
### نمایه Google Search
|
||||
|
||||
برای [مسدود کردن Google Search](https://developers.google.com/search/docs/crawling-indexing/block-indexing) از نمایهگذاری یک صفحه، `noindex` را در front matter صفحه روی true تنظیم کنید:
|
||||
|
||||
```yaml
|
||||
title: پیکربندی (نسخه آرشیو)
|
||||
params:
|
||||
noindex: true
|
||||
```
|
||||
|
||||
برای حذف یک دایرکتوری کامل، از کلید [`cascade`](https://gohugo.io/configuration/cascade/) در فایل `_index.md` والد استفاده کنید.
|
||||
|
||||
> [!NOTE]
|
||||
> برای مسدود کردن خزندههای جستجو، میتوانید یک [قالب `robots.txt`](https://gohugo.io/templates/robots/) ایجاد کنید.
|
||||
> با این حال، دستورالعملهای `robots.txt` لزوماً صفحه را از نتایج جستجوی Google خارج نمیکنند.
|
||||
|
||||
### پشتیبانی از LLMS.txt
|
||||
|
||||
برای فعال کردن فرمت خروجی [llms.txt](https://llmstxt.org/) برای سایت شما، که یک طرح متنی ساختاریافته برای [مدلهای زبانی بزرگ](https://fa.wikipedia.org/wiki/مدل_زبانی_بزرگ) و عاملهای هوش مصنوعی ارائه میدهد، فرمت خروجی `llms` را به `hugo.yaml` سایت خود اضافه کنید:
|
||||
|
||||
```diff {filename="hugo.yaml"}
|
||||
outputs:
|
||||
- home: [html]
|
||||
+ home: [html, llms]
|
||||
page: [html]
|
||||
section: [html, rss]
|
||||
```
|
||||
|
||||
این کار یک فایل `llms.txt` در ریشه سایت شما ایجاد میکند که شامل:
|
||||
|
||||
- عنوان و توضیحات سایت
|
||||
- لیست سلسله مراتبی تمام بخشها و صفحات
|
||||
- خلاصه صفحات و تاریخ انتشار
|
||||
- لینکهای مستقیم به تمام محتوا
|
||||
|
||||
میتوانید صفحات یا بخشهای خاصی را با تنظیم `llms: false` در frontmatter آنها حذف کنید:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "یادداشتهای داخلی"
|
||||
llms: false
|
||||
---
|
||||
```
|
||||
|
||||
فایل llms.txt به طور خودکار از ساختار محتوای شما ایجاد میشود و سایت شما را برای ابزارهای هوش مصنوعی و مدلهای زبانی برای زمینه و مرجع قابل دسترستر میکند.
|
||||
|
||||
### Open Graph
|
||||
|
||||
برای افزودن متادیتای [Open Graph](https://ogp.me/) به یک صفحه، مقادیر را در پارامترهای frontmatter اضافه کنید.
|
||||
|
||||
از آنجا که یک صفحه میتواند چندین تگ `image` و `video` داشته باشد، مقادیر آنها را در یک آرایه قرار دهید.
|
||||
سایر ویژگیهای Open Graph میتوانند فقط یک مقدار داشته باشند.
|
||||
به عنوان مثال، این صفحه یک تگ `og:image` (که تصویری برای پیشنمایش در اشتراکگذاریهای اجتماعی پیکربندی میکند) و یک تگ `og:audio` دارد.
|
||||
|
||||
```yaml {filename
|
||||
@@ -0,0 +1,635 @@
|
||||
---
|
||||
title: 設定
|
||||
weight: 2
|
||||
tags:
|
||||
- 設定
|
||||
---
|
||||
|
||||
Hugo はサイトのルートにある `hugo.yaml` から設定を読み込みます。
|
||||
この設定ファイルであなたのサイトのあらゆる側面を設定できます。
|
||||
利用可能な設定項目とベストプラクティスを網羅的に理解するには、GitHub 上のこのサイトの設定ファイル [`docs/hugo.yaml`](https://github.com/imfing/hextra/blob/main/docs/hugo.yaml) を参照してください。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## ナビゲーション
|
||||
|
||||
### メニュー
|
||||
|
||||
右上のメニューは設定ファイルの `menu.main` セクションで定義されます：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- name: ドキュメント
|
||||
pageRef: /docs
|
||||
weight: 1
|
||||
- name: ブログ
|
||||
pageRef: /blog
|
||||
weight: 2
|
||||
- name: このサイトについて
|
||||
pageRef: /about
|
||||
weight: 3
|
||||
- name: 検索
|
||||
weight: 4
|
||||
params:
|
||||
type: search
|
||||
- name: GitHub
|
||||
weight: 5
|
||||
url: "https://github.com/imfing/hextra"
|
||||
params:
|
||||
icon: github
|
||||
```
|
||||
|
||||
メニュー項目にはいくつかの種類があります：
|
||||
|
||||
1. `pageRef` でサイト内のページにリンク
|
||||
```yaml
|
||||
- name: ドキュメント
|
||||
pageRef: /docs
|
||||
```
|
||||
2. `url` で外部URLにリンク
|
||||
```yaml
|
||||
- name: GitHub
|
||||
url: "https://github.com"
|
||||
```
|
||||
3. `type: search` で検索バー
|
||||
```yaml
|
||||
- name: 検索
|
||||
params:
|
||||
type: search
|
||||
```
|
||||
4. アイコン
|
||||
```yaml
|
||||
- name: GitHub
|
||||
params:
|
||||
icon: github
|
||||
```
|
||||
5. テーマ切り替え
|
||||
```yaml
|
||||
- name: Theme Toggle
|
||||
params:
|
||||
type: theme-toggle
|
||||
label: true # optional, default is false
|
||||
```
|
||||
6. 言語スイッチャー
|
||||
```yaml
|
||||
- name: 言語スイッチャー
|
||||
params:
|
||||
type: language-switch
|
||||
label: true # optional, default is false
|
||||
icon: "globe-alt" # optional, default is "translate"
|
||||
```
|
||||
|
||||
これらのメニュー項目は `weight` パラメータを設定することで並べ替えられます。
|
||||
|
||||
### ネストされたメニュー
|
||||
|
||||
子メニュー項目を定義することでドロップダウンメニューを作成できます。親メニュー項目をクリックすると子メニューが表示されます。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: sdk
|
||||
name: SDK
|
||||
- identifier: python
|
||||
name: Python ↗
|
||||
url: https://python.org
|
||||
parent: sdk
|
||||
- identifier: go
|
||||
name: Go
|
||||
url: https://go.dev
|
||||
parent: sdk
|
||||
```
|
||||
|
||||
子メニュー項目は親の `identifier` 値を `parent` パラメータで指定する必要があります。
|
||||
|
||||
### ロゴとタイトル
|
||||
|
||||
デフォルトのロゴを変更するには、`hugo.yaml` を編集し、`static` ディレクトリ下のロゴファイルへのパスを追加します。
|
||||
オプションで、ロゴをクリックした際のリンク先や、ロゴの幅と高さ（ピクセル単位）を設定できます。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
navbar:
|
||||
displayTitle: true
|
||||
displayLogo: true
|
||||
logo:
|
||||
path: images/logo.svg
|
||||
dark: images/logo-dark.svg
|
||||
link: /
|
||||
width: 40
|
||||
height: 20
|
||||
```
|
||||
|
||||
### ページネーション
|
||||
|
||||
ドキュメントページやブログ記事の下部にある前へ/次へナビゲーションを無効にするには：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
displayPagination: false # ドキュメントページ用
|
||||
blog:
|
||||
article:
|
||||
displayPagination: false # ブログ記事用
|
||||
```
|
||||
|
||||
## サイドバー
|
||||
|
||||
### メインサイドバー
|
||||
|
||||
メインサイドバーはコンテンツディレクトリの構造から自動生成されます。
|
||||
詳細は [ファイルの整理](/docs/guide/organize-files) ページを参照してください。
|
||||
|
||||
単一ページを左サイドバーから除外するには、ページのフロントマターで `sidebar.exclude` パラメータを設定します：
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: 設定
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
```
|
||||
|
||||
### 追加リンク
|
||||
|
||||
サイドバーの追加リンクは設定ファイルの `menu.sidebar` セクションで定義されます：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
sidebar:
|
||||
- name: その他
|
||||
params:
|
||||
type: separator
|
||||
weight: 1
|
||||
- name: "このサイトについて"
|
||||
pageRef: "/about"
|
||||
weight: 2
|
||||
- name: "Hugo ドキュメント ↗"
|
||||
url: "https://gohugo.io/documentation/"
|
||||
weight: 3
|
||||
```
|
||||
|
||||
## 右サイドバー
|
||||
|
||||
### 目次
|
||||
|
||||
目次はコンテンツファイルの見出しから自動生成されます。ページのフロントマターで `toc: false` を設定することで無効化できます。
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: 設定
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
|
||||
### ページ編集リンク
|
||||
|
||||
ページ編集リンクを設定するには、設定ファイルで `params.editURL.base` パラメータを設定します：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
editURL:
|
||||
enable: true
|
||||
base: "https://github.com/your-username/your-repo/edit/main"
|
||||
```
|
||||
|
||||
編集リンクは提供されたURLをルートディレクトリとして各ページに対して自動生成されます。
|
||||
特定のページに対して編集リンクを設定したい場合は、ページのフロントマターで `editURL` パラメータを設定できます：
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: 設定
|
||||
editURL: "https://example.com/edit/this/page"
|
||||
---
|
||||
```
|
||||
|
||||
## フッター
|
||||
|
||||
### 著作権表示
|
||||
|
||||
ウェブサイトのフッターに表示される著作権テキストを変更するには、`i18n/en.yaml` という名前のファイルを作成する必要があります。
|
||||
このファイルで、以下のように新しい著作権テキストを指定します：
|
||||
|
||||
```yaml {filename="i18n/en.yaml"}
|
||||
copyright: "© 2024 ここにあなたのテキスト"
|
||||
```
|
||||
|
||||
参考までに、GitHub リポジトリに [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) ファイルの例があります。また、著作権テキストには Markdown 形式を使用することもできます。
|
||||
|
||||
## その他
|
||||
|
||||
### ファビコン
|
||||
|
||||
サイトの [ファビコン](https://ja.wikipedia.org/wiki/Favicon) をカスタマイズするには、[テーマのデフォルトファビコン](https://github.com/imfing/hextra/tree/main/static) を上書きするために `static` フォルダの下にアイコンファイルを配置します：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="static" >}}
|
||||
{{< filetree/file name="android-chrome-192x192.png" >}}
|
||||
{{< filetree/file name="android-chrome-512x512.png" >}}
|
||||
{{< filetree/file name="apple-touch-icon.png" >}}
|
||||
{{< filetree/file name="favicon-16x16.png" >}}
|
||||
{{< filetree/file name="favicon-32x32.png" >}}
|
||||
{{< filetree/file name="favicon-dark.svg" >}}
|
||||
{{< filetree/file name="favicon.ico" >}}
|
||||
{{< filetree/file name="favicon.svg" >}}
|
||||
{{< filetree/file name="site.webmanifest" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
#### 基本設定
|
||||
|
||||
最低限、`static` フォルダに `favicon.svg` を含めてください。これがサイトのデフォルトファビコンとして使用されます。
|
||||
|
||||
SVG 内で CSS メディアクエリを使用することで、システムのテーマ設定に応答する適応型 SVG ファビコンを作成できます。このアプローチは [適応型ファビコンの構築](https://web.dev/articles/building/an-adaptive-favicon) で説明されています。
|
||||
|
||||
#### ダークモード対応
|
||||
|
||||
強化されたダークモードサポートのために、`favicon.svg` と一緒に `favicon-dark.svg` を `static` フォルダに追加してください。両方のファイルが存在する場合、Hextra は自動的に：
|
||||
|
||||
- ライトモードまたはテーマ設定が検出されない場合に `favicon.svg` を使用
|
||||
- ユーザーのシステムがダークモードに設定されている場合に `favicon-dark.svg` に切り替え
|
||||
- 自動切り替えのためにシステムの `prefers-color-scheme` 設定を尊重
|
||||
|
||||
ダークモードファビコンの切り替えは Firefox を含むすべての最新ブラウザで動作し、サイトのテーマにマッチしたシームレスな体験を提供します。
|
||||
|
||||
#### 追加フォーマット
|
||||
|
||||
`favicon.ico` は一般的に古いブラウザ向けですが、最新のブラウザはスケーラビリティとファイルサイズの小ささが好まれる SVG ファビコンをサポートしています。
|
||||
必要に応じて [favicon.io](https://favicon.io/) や [favycon](https://github.com/ruisaraiva19/favycon) などのツールを使用して追加のファビコンフォーマットを生成できます。
|
||||
|
||||
### テーマ設定
|
||||
|
||||
`theme` 設定を使用してデフォルトのテーマモードとトグルボタンを設定し、訪問者がライトモードとダークモードを切り替えられるようにします。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
theme:
|
||||
# light | dark | system
|
||||
default: system
|
||||
displayToggle: true
|
||||
```
|
||||
|
||||
`theme.default` のオプション：
|
||||
|
||||
- `light` - 常にライトモードを使用
|
||||
- `dark` - 常にダークモードを使用
|
||||
- `system` - オペレーティングシステムの設定と同期（デフォルト）
|
||||
|
||||
`theme.displayToggle` パラメータはテーマを変更するためのトグルボタンを表示します。
|
||||
`true` に設定すると、訪問者はデフォルト設定を上書きしてライトモードとダークモードを切り替えられます。
|
||||
|
||||
### ページ最終更新日
|
||||
|
||||
ページの最終更新日を表示するには、`params.displayUpdatedDate` フラグを有効にします。Git コミット日付をソースとして使用するには、`enableGitInfo` フラグも有効にします。
|
||||
|
||||
日付形式をカスタマイズするには、`params.dateFormat` パラメータを設定します。そのレイアウトは Hugo の [`time.Format`](https://gohugo.io/functions/time/format/) に準拠します。
|
||||
|
||||
さらに、`params.displayUpdatedAuthor` フラグを有効にすると、最終更新の作者を表示できます。これには `enableGitInfo: true` の設定が必要です。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
# Git コミットを解析
|
||||
enableGitInfo: true
|
||||
|
||||
params:
|
||||
# 最終更新日を表示
|
||||
displayUpdatedDate: true
|
||||
dateFormat: "2006年1月2日"
|
||||
# 最終更新の作者を表示
|
||||
displayUpdatedAuthor: true
|
||||
```
|
||||
|
||||
### タグ
|
||||
|
||||
ページタグを表示するには、設定ファイルで以下のフラグを設定します：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
blog:
|
||||
list:
|
||||
displayTags: true
|
||||
toc:
|
||||
displayTags: true
|
||||
```
|
||||
|
||||
Hugo はデフォルトで `tags` と `categories` のタクソノミーページを作成します。サイトでタクソノミーページを使わず、生成される `public/tags/` と `public/categories/` ディレクトリを省略したい場合は、`taxonomy` と `term` のページ種別を無効にします：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
disableKinds:
|
||||
- taxonomy
|
||||
- term
|
||||
```
|
||||
|
||||
タグまたはカテゴリのアーカイブページに依存していない場合にのみ、これらの種別を無効にしてください。
|
||||
|
||||
### 画像ズーム
|
||||
|
||||
画像ズームはデフォルトで無効です。有効にすると、Markdown 画像をクリックするとズームビューが開きます。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
```
|
||||
|
||||
特定のページでズームを無効にするには、ページのフロントマターに以下を追加します：
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
imageZoom: false
|
||||
---
|
||||
```
|
||||
|
||||
Medium Zoom アセットを固定するか、ローカルアセットから読み込む場合：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
base: "https://cdn.jsdelivr.net/npm/medium-zoom@1.1.0/dist"
|
||||
# js: "js/medium-zoom.min.js" # オプション、base またはローカルアセットからの相対パス
|
||||
```
|
||||
|
||||
### ローカルおよびミラー済みスクリプトアセット
|
||||
|
||||
Hextra はオプションのフロントエンド依存ファイルを複数のソースから読み込めます:
|
||||
|
||||
- テーマのデフォルト設定（CDN）
|
||||
- `base` を使った社内ミラー URL
|
||||
- `js` / `css` を使った Hugo のローカルアセット
|
||||
|
||||
ローカルアセットを使う場合は、vendor ファイルをサイトの `assets/` ディレクトリに配置し、そのアセットパスを設定値に指定します:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
js: "js/vendor/medium-zoom.min.js"
|
||||
|
||||
mermaid:
|
||||
js: "js/vendor/mermaid.min.js"
|
||||
|
||||
asciinema:
|
||||
js: "js/vendor/asciinema-player.min.js"
|
||||
css: "css/vendor/asciinema-player.css"
|
||||
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
css: "css/vendor/katex.min.css"
|
||||
assets:
|
||||
- "fonts/KaTeX_Main-Regular.woff2"
|
||||
- "fonts/KaTeX_Math-Italic.woff2"
|
||||
|
||||
search:
|
||||
type: flexsearch
|
||||
flexsearch:
|
||||
js: "js/vendor/flexsearch.bundle.min.js"
|
||||
```
|
||||
|
||||
`imageZoom.enable: true` が必要なのは、画像ズームがデフォルトで無効になっているためです。
|
||||
KaTeX については、この例の 2 つだけでなく、選択した CSS が参照するすべてのフォントファイルを公開してください。
|
||||
|
||||
社内ミラーを使う場合は `base` を設定し、ファイル名が異なる場合のみ `js` / `css` を追加してください:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
base: "https://mirror.example.com/medium-zoom/dist"
|
||||
|
||||
mermaid:
|
||||
base: "https://mirror.example.com/mermaid/dist"
|
||||
|
||||
asciinema:
|
||||
base: "https://mirror.example.com/asciinema-player/dist/bundle"
|
||||
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
base: "https://mirror.example.com/katex/dist"
|
||||
|
||||
search:
|
||||
flexsearch:
|
||||
base: "https://mirror.example.com/flexsearch/dist"
|
||||
# js: "flexsearch.bundle.min.js"
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> MathJax の読み込み元をカスタマイズするには、プロジェクト内で `layouts/_partials/scripts/mathjax.html` を上書きしてください。
|
||||
|
||||
### ページ幅
|
||||
|
||||
レイアウト全体の幅は `params.page.width` で設定できます：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
# full (100%), wide (90rem), normal (1280px)
|
||||
width: wide
|
||||
```
|
||||
|
||||
`params.page.width` の選択肢は `full`、`wide`、`normal` です。
|
||||
|
||||
本文コンテンツ幅はデフォルトで `72rem` に固定されています。
|
||||
|
||||
コンテンツ幅を変更したい場合は、カスタムスタイルシートで CSS 変数を上書きしてください：
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
--hextra-max-content-width: 100%;
|
||||
}
|
||||
```
|
||||
|
||||
同様に、ナビゲーションバーとフッターの幅は `params.navbar.width` と `params.footer.width` パラメータでカスタマイズできます。
|
||||
|
||||
### ページコンテキストメニュー
|
||||
|
||||
ページコンテキストメニューは、ページの内容を Markdown としてコピーしたり、生の Markdown ソースを表示したりできるドロップダウンボタンを提供します。この機能は、読者が Markdown 形式でコンテンツを共有または参照したいドキュメントサイトに便利です。
|
||||
|
||||
#### コンテキストメニューの有効化
|
||||
|
||||
コンテキストメニューをグローバルに有効にするには、設定ファイルに以下を追加します：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
```
|
||||
|
||||
また、ページの `markdown` 出力形式を有効にする必要があります：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
page: [html, markdown]
|
||||
section: [html, rss, markdown]
|
||||
```
|
||||
|
||||
#### ページごとの制御
|
||||
|
||||
特定のページでコンテキストメニューを有効または無効にするには、フロントマターで `contextMenu` パラメータを使用します：
|
||||
|
||||
```yaml {filename="content/docs/example.md"}
|
||||
---
|
||||
title: サンプルページ
|
||||
contextMenu: false
|
||||
---
|
||||
```
|
||||
|
||||
#### カスタムリンク
|
||||
|
||||
コンテキストメニューのドロップダウンにカスタムリンクを追加できます。これは外部サービスとの統合に便利です。リンクは以下のプレースホルダーをサポートしています：
|
||||
|
||||
- `{url}` - ページの URL（URL エンコード済み）
|
||||
- `{title}` - ページのタイトル（URL エンコード済み）
|
||||
- `{markdown_url}` - 生の Markdown コンテンツの URL（URL エンコード済み）
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
links:
|
||||
- name: ChatGPT で開く
|
||||
icon: chatgpt
|
||||
url: "https://chatgpt.com/?hints=search&q=I%27m+looking+at+this+documentation%3A+{url}%0AHelp+me+understand+how+to+use+it."
|
||||
```
|
||||
|
||||
各リンクには以下を設定できます：
|
||||
- `name` - リンクの表示テキスト
|
||||
- `icon` - オプションのアイコン名（[アイコン]({{% relref "docs/guide/shortcodes/icon" %}})を参照）
|
||||
- `url` - オプションのプレースホルダーを含む URL
|
||||
|
||||
### FlexSearch インデックス
|
||||
|
||||
[FlexSearch](https://github.com/nextapps-de/flexsearch) を利用した全文検索はデフォルトで有効です。
|
||||
検索インデックスをカスタマイズするには、設定ファイルで `params.search.flexsearch.index` パラメータを設定します：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
# 検索
|
||||
search:
|
||||
enable: true
|
||||
type: flexsearch
|
||||
|
||||
flexsearch:
|
||||
# インデックス対象: content | summary | heading | title
|
||||
index: content
|
||||
```
|
||||
|
||||
FlexSearch ランタイムの読み込み元も制御できます:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
search:
|
||||
flexsearch:
|
||||
version: "0.8.143" # デフォルトの CDN バージョン
|
||||
# base: "https://mirror.example.com/flexsearch/dist" # オプションのリモート base URL
|
||||
# js: "js/vendor/flexsearch.bundle.min.js" # ローカルアセットのパス、またはリモート base 配下のカスタムファイル
|
||||
```
|
||||
|
||||
`flexsearch.index` のオプション：
|
||||
|
||||
- `content` - ページの全文（デフォルト）
|
||||
- `summary` - ページの要約、詳細は [Hugo コンテンツ要約](https://gohugo.io/content-management/summaries/) を参照
|
||||
- `heading` - レベル1とレベル2の見出し
|
||||
- `title` - ページタイトルのみを含める
|
||||
|
||||
検索トークン化をカスタマイズするには、設定ファイルで `params.search.flexsearch.tokenize` パラメータを設定します：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
search:
|
||||
# ...
|
||||
flexsearch:
|
||||
# full | forward | reverse | strict
|
||||
tokenize: forward
|
||||
```
|
||||
|
||||
[`flexsearch.tokenize`](https://github.com/nextapps-de/flexsearch/#tokenizer-prefix-search) のオプション：
|
||||
|
||||
- `strict` - 単語全体をインデックス
|
||||
- `forward` - 前方方向に単語を増分的にインデックス
|
||||
- `reverse` - 両方向に単語を増分的にインデックス
|
||||
- `full` - すべての可能な組み合わせをインデックス
|
||||
|
||||
FlexSearch 検索インデックスからページを除外するには、ページのフロントマターで `excludeSearch: true` を設定します：
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: 設定
|
||||
excludeSearch: true
|
||||
---
|
||||
```
|
||||
|
||||
### Google アナリティクス
|
||||
|
||||
[Google アナリティクス](https://marketingplatform.google.com/about/analytics/) を有効にするには、`hugo.yaml` で `services.googleAnalytics.ID` フラグを設定します：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
services:
|
||||
googleAnalytics:
|
||||
ID: G-MEASUREMENT_ID
|
||||
```
|
||||
|
||||
### Google 検索インデックス
|
||||
|
||||
ページを [Google 検索のインデックスからブロック](https://developers.google.com/search/docs/crawling-indexing/block-indexing) するには、ページのフロントマターで `noindex` を true に設定します：
|
||||
|
||||
```yaml
|
||||
title: 設定（アーカイブ版）
|
||||
params:
|
||||
noindex: true
|
||||
```
|
||||
|
||||
ディレクトリ全体を除外するには、親の `_index.md` ファイルで [`cascade`](https://gohugo.io/configuration/cascade/) キーを使用します。
|
||||
|
||||
> [!NOTE]
|
||||
> 検索クローラーをブロックするには、[`robots.txt` テンプレート](https://gohugo.io/templates/robots/) を作成できます。
|
||||
> ただし、`robots.txt` の指示は必ずしも Google 検索結果からページを除外するわけではありません。
|
||||
|
||||
### LLMS.txt サポート
|
||||
|
||||
サイトの [大規模言語モデル](https://ja.wikipedia.org/wiki/大規模言語モデル) や AI エージェント向けの構造化テキストアウトラインを提供する [llms.txt](https://llmstxt.org/) 出力形式を有効にするには、サイトの `hugo.yaml` に `llms` 出力形式を追加します：
|
||||
|
||||
```diff {filename="hugo.yaml"}
|
||||
outputs:
|
||||
- home: [html]
|
||||
+ home: [html, llms]
|
||||
page: [html]
|
||||
section: [html, rss]
|
||||
```
|
||||
|
||||
これにより、サイトのルートに `llms.txt` ファイルが生成され、以下が含まれます：
|
||||
|
||||
- サイトタイトルと説明
|
||||
- すべてのセクションとページの階層リスト
|
||||
- ページの要約と公開日
|
||||
- すべてのコンテンツへの直接リンク
|
||||
|
||||
フロントマターで `llms: false` を設定することで、特定のページやセクションを除外できます：
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "内部メモ"
|
||||
llms: false
|
||||
---
|
||||
```
|
||||
|
||||
llms.txt ファイルはコンテンツ構造から自動生成され、AI ツールや言語モデルがコンテキストや参照のためにあなたのサイトにアクセスしやすくします。
|
||||
|
||||
### Open Graph
|
||||
|
||||
ページに [Open Graph](https://ogp.me/) メタデータを追加するには、フロントマターの params に値を追加します。
|
||||
|
||||
ページは複数の `image` と `video` タグを持つことができるため、それらの値は配列に配置します。
|
||||
他の Open Graph プロパティは単一の値のみを持つことができます。
|
||||
例えば、このページには `og:image` タグ（ソーシャルシェアでプレビューする画像を設定）と `og:audio` タグがあります。
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
title: "設定"
|
||||
params:
|
||||
images:
|
||||
- "img/config-image.jpg"
|
||||
audio: "config-talk.mp3"
|
||||
```
|
||||
@@ -0,0 +1,780 @@
|
||||
---
|
||||
title: Configuration
|
||||
weight: 2
|
||||
tags:
|
||||
- Config
|
||||
---
|
||||
|
||||
Hugo reads its configuration from `hugo.yaml` in the root of your Hugo site.
|
||||
The config file is where you can configure all aspects of your site.
|
||||
Check out the config file for this site [`docs/hugo.yaml`](https://github.com/imfing/hextra/blob/main/docs/hugo.yaml) on GitHub to get a comprehensive idea of available settings and best practices.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Navigation
|
||||
|
||||
### Menu
|
||||
|
||||
Top right menu is defined under the `menu.main` section in the config file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- name: Documentation
|
||||
pageRef: /docs
|
||||
weight: 1
|
||||
- name: Blog
|
||||
pageRef: /blog
|
||||
weight: 2
|
||||
- name: About
|
||||
pageRef: /about
|
||||
weight: 3
|
||||
- name: Search
|
||||
weight: 4
|
||||
params:
|
||||
type: search
|
||||
- name: GitHub
|
||||
weight: 5
|
||||
url: "https://github.com/imfing/hextra"
|
||||
params:
|
||||
icon: github
|
||||
```
|
||||
|
||||
There are different types of menu items:
|
||||
|
||||
1. Link to a page in the site with `pageRef`
|
||||
```yaml
|
||||
- name: Documentation
|
||||
pageRef: /docs
|
||||
```
|
||||
2. Link to an external URL with `url`
|
||||
```yaml
|
||||
- name: GitHub
|
||||
url: "https://github.com"
|
||||
```
|
||||
3. Search bar with `type: search`
|
||||
```yaml
|
||||
- name: Search
|
||||
params:
|
||||
type: search
|
||||
```
|
||||
4. Icon Only
|
||||
```yaml
|
||||
- name: GitHub
|
||||
params:
|
||||
icon: github
|
||||
```
|
||||
5. Link with Icon
|
||||
```yaml
|
||||
- name: Blog
|
||||
params:
|
||||
type: link
|
||||
icon: rss
|
||||
```
|
||||
6. Theme Toggle
|
||||
```yaml
|
||||
- name: Theme Toggle
|
||||
params:
|
||||
type: theme-toggle
|
||||
label: true # optional, default is false
|
||||
```
|
||||
7. Language Switcher
|
||||
```yaml
|
||||
- name: Language Switcher
|
||||
params:
|
||||
type: language-switch
|
||||
label: true # optional, default is false
|
||||
icon: "globe-alt" # optional, default is "translate"
|
||||
```
|
||||
|
||||
These menu items can be sorted by setting the `weight` parameter.
|
||||
|
||||
### Nested Menus
|
||||
|
||||
You can create dropdown menus by defining child menu items. Child menus appear when clicking on the parent menu item.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: sdk
|
||||
name: SDK
|
||||
- identifier: python
|
||||
name: Python ↗
|
||||
url: https://python.org
|
||||
parent: sdk
|
||||
- identifier: go
|
||||
name: Go
|
||||
url: https://go.dev
|
||||
parent: sdk
|
||||
```
|
||||
|
||||
Child menu items need to specify the `parent` parameter with the parent's `identifier` value.
|
||||
|
||||
### Logo and Title
|
||||
|
||||
To modify the default logo, edit `hugo.yaml` and add the path to your logo file under `static` directory.
|
||||
Optionally, you can change the link that users are redirected to when clicking on your logo, as well as set the width & height of the logo in pixels.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
navbar:
|
||||
displayTitle: true
|
||||
displayLogo: true
|
||||
logo:
|
||||
path: images/logo.svg
|
||||
dark: images/logo-dark.svg
|
||||
link: /
|
||||
width: 40
|
||||
height: 20
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
To disable the previous/next navigation at the bottom of docs pages or blog articles:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
displayPagination: false # for docs pages
|
||||
blog:
|
||||
article:
|
||||
displayPagination: false # for blog articles
|
||||
```
|
||||
|
||||
## Sidebar
|
||||
|
||||
### Main Sidebar
|
||||
|
||||
For the main sidebar, it is automatically generated from the structure of the content directory.
|
||||
See the [Organize Files](/docs/guide/organize-files) page for more details.
|
||||
|
||||
To exclude a single page from the left sidebar, set the `sidebar.exclude` parameter in the front matter of the page:
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: Configuration
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
```
|
||||
|
||||
### Extra Links
|
||||
|
||||
Sidebar extra links are defined under the `menu.sidebar` section in the config file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
sidebar:
|
||||
- name: More
|
||||
params:
|
||||
type: separator
|
||||
weight: 1
|
||||
- name: "About"
|
||||
pageRef: "/about"
|
||||
weight: 2
|
||||
- name: "Hugo Docs ↗"
|
||||
url: "https://gohugo.io/documentation/"
|
||||
weight: 3
|
||||
```
|
||||
|
||||
### Hiding
|
||||
|
||||
Hiding the sidebar can be done using front matter:
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: Configuration
|
||||
sidebar:
|
||||
hide: true
|
||||
---
|
||||
```
|
||||
|
||||
This will hide the main sidebar from the page, freeing up space for the main content of the page.
|
||||
|
||||
|
||||
## Right Sidebar
|
||||
|
||||
### Table of Contents
|
||||
|
||||
Table of contents is automatically generated from the headings in the content file. It can be disabled by setting `toc: false` in the front matter of the page.
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: Configuration
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
|
||||
### Page Edit Link
|
||||
|
||||
To configure the page edit link, we can set the `params.editURL.base` parameter in the config file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
editURL:
|
||||
enable: true
|
||||
base: "https://github.com/your-username/your-repo/edit/main"
|
||||
```
|
||||
|
||||
The edit links will be automatically generated for each page based on the provided url as root directory.
|
||||
If you want to set edit link for a specific page, you can set the `editURL` parameter in the front matter of the page:
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: Configuration
|
||||
editURL: "https://example.com/edit/this/page"
|
||||
---
|
||||
```
|
||||
|
||||
## Footer
|
||||
|
||||
### Copyright
|
||||
|
||||
To modify the copyright text displayed in your website's footer, you'll need to create a file named `i18n/en.yaml`.
|
||||
In this file, specify your new copyright text as shown below:
|
||||
|
||||
```yaml {filename="i18n/en.yaml"}
|
||||
copyright: "© 2024 YOUR TEXT HERE"
|
||||
```
|
||||
|
||||
For your reference, an example [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) file can be found in the GitHub repository. Additionally, you could use Markdown format in the copyright text.
|
||||
|
||||
## Others
|
||||
|
||||
### Favicon
|
||||
|
||||
To customize the [favicon](https://en.wikipedia.org/wiki/Favicon) for your site, place icon files under the `static` folder to override the [default favicons from the theme](https://github.com/imfing/hextra/tree/main/static):
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="static" >}}
|
||||
{{< filetree/file name="android-chrome-192x192.png" >}}
|
||||
{{< filetree/file name="android-chrome-512x512.png" >}}
|
||||
{{< filetree/file name="apple-touch-icon.png" >}}
|
||||
{{< filetree/file name="favicon-16x16.png" >}}
|
||||
{{< filetree/file name="favicon-32x32.png" >}}
|
||||
{{< filetree/file name="favicon-dark.svg" >}}
|
||||
{{< filetree/file name="favicon.ico" >}}
|
||||
{{< filetree/file name="favicon.svg" >}}
|
||||
{{< filetree/file name="site.webmanifest" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
#### Basic Setup
|
||||
|
||||
At minimum, include `favicon.svg` in your `static` folder. This will be used as the default favicon for your site.
|
||||
|
||||
You can create an adaptive SVG favicon that responds to system theme preferences by using CSS media queries within the SVG itself, following the approach described in [Building an Adaptive Favicon](https://web.dev/articles/building/an-adaptive-favicon).
|
||||
|
||||
#### Dark Mode Support
|
||||
|
||||
For enhanced dark mode support, add `favicon-dark.svg` to your `static` folder alongside `favicon.svg`. When both files are present, Hextra will automatically:
|
||||
|
||||
- Use `favicon.svg` for light mode or when no theme preference is detected
|
||||
- Switch to `favicon-dark.svg` when the user's system is set to dark mode
|
||||
- Respect the system's `prefers-color-scheme` setting for automatic switching
|
||||
|
||||
The dark mode favicon switching works across all modern browsers, including Firefox, and provides a seamless experience that matches your site's theme.
|
||||
|
||||
#### Additional Formats
|
||||
|
||||
While `favicon.ico` is generally for older browsers, modern browsers support SVG favicons which are preferred for their scalability and small file size.
|
||||
Use tools like [favicon.io](https://favicon.io/) or [favycon](https://github.com/ruisaraiva19/favycon) to generate additional favicon formats if needed.
|
||||
|
||||
### Theme Configuration
|
||||
|
||||
Use the `theme` setting to configure the default theme mode and toggle button, allowing visitors to switch between light or dark mode.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
theme:
|
||||
# light | dark | system
|
||||
default: system
|
||||
displayToggle: true
|
||||
```
|
||||
|
||||
Options for `theme.default`:
|
||||
|
||||
- `light` - always use light mode
|
||||
- `dark` - always use dark mode
|
||||
- `system` - sync with the operating system setting (default)
|
||||
|
||||
The `theme.displayToggle` parameter allows you to display a toggle button for changing themes.
|
||||
When set to `true`, visitors can switch between light or dark mode, overriding the default setting.
|
||||
|
||||
### Page Last Modification
|
||||
|
||||
The date of the page's last modification can be displayed by enabling the `params.displayUpdatedDate` flag. To use Git commit date as the source, enable also the `enableGitInfo` flag.
|
||||
|
||||
To customize the date format, set the `params.dateFormat` parameter. Its layout matches Hugo's [`time.Format`](https://gohugo.io/functions/time/format/).
|
||||
|
||||
Additionally, the author of the last modification can be displayed by enabling the `params.displayUpdatedAuthor` flag. This requires `enableGitInfo: true` to be set.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
# Parse Git commit
|
||||
enableGitInfo: true
|
||||
|
||||
params:
|
||||
# Display the last modification date
|
||||
displayUpdatedDate: true
|
||||
dateFormat: "January 2, 2006"
|
||||
# Display the author of the last modification
|
||||
displayUpdatedAuthor: true
|
||||
```
|
||||
|
||||
### Tags
|
||||
|
||||
To display page tags, set following flags in the config file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
blog:
|
||||
list:
|
||||
displayTags: true
|
||||
toc:
|
||||
displayTags: true
|
||||
```
|
||||
|
||||
Hugo creates taxonomy pages for `tags` and `categories` by default. If your site does not use taxonomy pages and you want to omit the generated `public/tags/` and `public/categories/` directories, disable the `taxonomy` and `term` page kinds:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
disableKinds:
|
||||
- taxonomy
|
||||
- term
|
||||
```
|
||||
|
||||
Only disable these kinds when you are not relying on tag or category archive pages.
|
||||
|
||||
### Image Zoom
|
||||
|
||||
Image zoom is disabled by default. When enabled, clicking a Markdown image opens a zoomed view.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
```
|
||||
|
||||
To disable zoom on a specific page, add this to the page front matter:
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
imageZoom: false
|
||||
---
|
||||
```
|
||||
|
||||
If you want to pin the Medium Zoom asset or load it from local assets:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
base: "https://cdn.jsdelivr.net/npm/medium-zoom@1.1.0/dist"
|
||||
# js: "js/medium-zoom.min.js" # optional, relative to the base or local assets
|
||||
```
|
||||
|
||||
### Local and Mirrored Script Assets
|
||||
|
||||
Hextra can load optional frontend dependencies from different sources:
|
||||
|
||||
- Theme defaults (CDN)
|
||||
- Internal mirror URLs via `base`
|
||||
- Local Hugo assets via `js` / `css`
|
||||
|
||||
For local assets, place vendor files under your site's `assets/` directory and point config values to those asset paths:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
js: "js/vendor/medium-zoom.min.js"
|
||||
|
||||
mermaid:
|
||||
js: "js/vendor/mermaid.min.js"
|
||||
|
||||
asciinema:
|
||||
js: "js/vendor/asciinema-player.min.js"
|
||||
css: "css/vendor/asciinema-player.css"
|
||||
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
css: "css/vendor/katex.min.css"
|
||||
assets:
|
||||
- "fonts/KaTeX_Main-Regular.woff2"
|
||||
- "fonts/KaTeX_Math-Italic.woff2"
|
||||
|
||||
search:
|
||||
type: flexsearch
|
||||
flexsearch:
|
||||
js: "js/vendor/flexsearch.bundle.min.js"
|
||||
```
|
||||
|
||||
`imageZoom.enable: true` is only needed here because image zoom is disabled by default.
|
||||
For KaTeX, make sure to publish all font files referenced by your chosen CSS file, not just the two shown in this example.
|
||||
|
||||
To use an internal mirror instead, set `base` (and optionally `js` / `css` when the filename differs):
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
base: "https://mirror.example.com/medium-zoom/dist"
|
||||
|
||||
mermaid:
|
||||
base: "https://mirror.example.com/mermaid/dist"
|
||||
|
||||
asciinema:
|
||||
base: "https://mirror.example.com/asciinema-player/dist/bundle"
|
||||
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
base: "https://mirror.example.com/katex/dist"
|
||||
|
||||
search:
|
||||
flexsearch:
|
||||
base: "https://mirror.example.com/flexsearch/dist"
|
||||
# js: "flexsearch.bundle.min.js"
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> To customize MathJax source loading, override `layouts/_partials/scripts/mathjax.html` in your site.
|
||||
|
||||
### Page Width
|
||||
|
||||
The layout shell width can be customized by the `params.page.width` parameter in the config file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
# full (100%), wide (90rem), normal (1280px)
|
||||
width: wide
|
||||
```
|
||||
|
||||
Available options for `params.page.width`: `full`, `wide`, `normal`.
|
||||
|
||||
The main reading content width remains fixed at `72rem` by default.
|
||||
|
||||
To customize content width, override the CSS variable in your custom stylesheet:
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
--hextra-max-content-width: 100%;
|
||||
}
|
||||
```
|
||||
|
||||
Similarly, the width of the navbar and footer can be customized by the `params.navbar.width` and `params.footer.width` parameters.
|
||||
|
||||
### Page Context Menu
|
||||
|
||||
The page context menu provides a dropdown button that allows users to copy the page content as Markdown or view the raw Markdown source. This feature is useful for documentation sites where readers may want to share or reference the content in Markdown format.
|
||||
|
||||
#### Enabling the Context Menu
|
||||
|
||||
To enable the context menu globally, add the following to your config file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
```
|
||||
|
||||
You also need to enable the `markdown` output format for pages:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
page: [html, markdown]
|
||||
section: [html, rss, markdown]
|
||||
```
|
||||
|
||||
#### Per-Page Control
|
||||
|
||||
To enable or disable the context menu for a specific page, use the `contextMenu` parameter in the front matter:
|
||||
|
||||
```yaml {filename="content/docs/example.md"}
|
||||
---
|
||||
title: Example Page
|
||||
contextMenu: false
|
||||
---
|
||||
```
|
||||
|
||||
#### Custom Links
|
||||
|
||||
You can add custom links to the context menu dropdown. This is useful for integrating with external services. The links support the following placeholders:
|
||||
|
||||
- `{url}` - The page URL (URL-encoded)
|
||||
- `{title}` - The page title (URL-encoded)
|
||||
- `{markdown_url}` - The URL to the raw Markdown content (URL-encoded)
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
links:
|
||||
- name: Open in ChatGPT
|
||||
icon: chatgpt
|
||||
url: "https://chatgpt.com/?hints=search&q=I%27m+looking+at+this+documentation%3A+{url}%0AHelp+me+understand+how+to+use+it."
|
||||
```
|
||||
|
||||
Each link can have:
|
||||
- `name` - The display text for the link
|
||||
- `icon` - An optional icon name (see [Icons]({{% relref "docs/guide/shortcodes/icon" %}}))
|
||||
- `url` - The URL with optional placeholders
|
||||
|
||||
### FlexSearch Index
|
||||
|
||||
Full-text search powered by [FlexSearch](https://github.com/nextapps-de/flexsearch) is enabled by default.
|
||||
To customize the search index, set the `params.search.flexsearch.index` parameter in the config file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
# Search
|
||||
search:
|
||||
enable: true
|
||||
type: flexsearch
|
||||
|
||||
flexsearch:
|
||||
# index page by: content | summary | heading | title
|
||||
index: content
|
||||
```
|
||||
|
||||
You can also control where the FlexSearch runtime is loaded from:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
search:
|
||||
flexsearch:
|
||||
version: "0.8.143" # default CDN version
|
||||
# base: "https://mirror.example.com/flexsearch/dist" # optional remote base URL
|
||||
# js: "js/vendor/flexsearch.bundle.min.js" # local asset path, or custom file under remote base
|
||||
```
|
||||
|
||||
Options for `flexsearch.index`:
|
||||
|
||||
- `content` - full content of the page (default)
|
||||
- `summary` - summary of the page, see [Hugo Content Summaries](https://gohugo.io/content-management/summaries/) for more details
|
||||
- `heading` - level 1 and level 2 headings
|
||||
- `title` - only include the page title
|
||||
|
||||
To customize the search tokenize, set the `params.search.flexsearch.tokenize` parameter in the config file:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
search:
|
||||
# ...
|
||||
flexsearch:
|
||||
# full | forward | reverse | strict
|
||||
tokenize: forward
|
||||
```
|
||||
|
||||
Options for [`flexsearch.tokenize`](https://github.com/nextapps-de/flexsearch/#tokenizer-prefix-search):
|
||||
|
||||
- `strict` - index whole words
|
||||
- `forward` - incrementally index words in forward direction
|
||||
- `reverse` - incrementally index words in both directions
|
||||
- `full` - index every possible combination
|
||||
|
||||
To exclude a page from the FlexSearch search index, set the `excludeSearch: true` in the front matter of the page:
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: Configuration
|
||||
excludeSearch: true
|
||||
---
|
||||
```
|
||||
|
||||
### Google Search Index
|
||||
|
||||
To [block Google Search](https://developers.google.com/search/docs/crawling-indexing/block-indexing) from indexing a page, set `noindex` to true in your page frontmatter:
|
||||
|
||||
```yaml
|
||||
title: Configuration (archive version)
|
||||
params:
|
||||
noindex: true
|
||||
```
|
||||
|
||||
To exclude an entire directory, use the [`cascade`](https://gohugo.io/configuration/cascade/) key in the parent `_index.md` file.
|
||||
|
||||
> [!NOTE]
|
||||
> To block search crawlers, you can make a [`robots.txt` template](https://gohugo.io/templates/robots/).
|
||||
> However, `robots.txt` instructions do not necessarily keep a page out of Google search results.
|
||||
|
||||
### Analytics
|
||||
|
||||
Hextra has support for several different analytics solutions. Hextra only supports analytics in production environments. This is to ensure that you do not accidentally send analytic events when working locally. If, however, you do want to test analytics locally, you can run a production server using:
|
||||
|
||||
```
|
||||
hugo server --environment production
|
||||
```
|
||||
|
||||
#### Google Analytics
|
||||
|
||||
To enable [Google Analytics](https://marketingplatform.google.com/about/analytics/), set `services.googleAnalytics.ID` flag in `hugo.yaml`:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
services:
|
||||
googleAnalytics:
|
||||
ID: G-MEASUREMENT_ID
|
||||
```
|
||||
|
||||
#### Umami Analytics
|
||||
|
||||
To enable [Umami](https://umami.is/docs/), set `params.analytics.umami.serverURL` and `params.analytics.umami.websiteID` flag in `hugo.yaml`:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
analytics:
|
||||
umami:
|
||||
serverURL: "https://example.com"
|
||||
websiteID: "94db1cb1-74f4-4a40-ad6c-962362670409"
|
||||
# scriptName: "script.js" # optional (default: script.js)
|
||||
# https://umami.is/docs/tracker-configuration#data-host-url
|
||||
# hostURL: "http://stats.example.org" # optional
|
||||
# https://umami.is/docs/tracker-configuration#data-auto-track
|
||||
# autoTrack: "false" # optional
|
||||
# https://umami.is/docs/tracker-configuration#data-tag
|
||||
# domains: "example.net,example.org" # optional
|
||||
# https://umami.is/docs/tracker-configuration#data-exclude-search
|
||||
# tag: "umami-eu" # optional
|
||||
# https://umami.is/docs/tracker-configuration#data-exclude-hash
|
||||
# excludeSearch: "true" # optional
|
||||
# https://umami.is/docs/tracker-configuration#data-do-not-track
|
||||
# excludeHash: "true" # optional
|
||||
# https://umami.is/docs/tracker-configuration#data-domains
|
||||
# doNotTrack: "true" # optional
|
||||
```
|
||||
|
||||
#### Matomo Analytics
|
||||
|
||||
To enable [Matomo](https://matomo.org/), set `params.analytics.matomo.URL` and `params.analytics.matomo.ID` flag in `hugo.yaml`:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
analytics:
|
||||
matomo:
|
||||
serverURL: "https://example.com"
|
||||
websiteID: "94db1cb1-74f4-4a40-ad6c-962362670409"
|
||||
```
|
||||
|
||||
#### GoatCounter Analytics
|
||||
|
||||
To enable [GoatCounter](https://www.goatcounter.com/), set `params.analytics.goatCounter.code` in `hugo.yaml`
|
||||
All settings available here are mirrors of the settings described in GoatCounter [settings](https://www.goatcounter.com/help/js#settings-44186)
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
analytics:
|
||||
goatCounter:
|
||||
code: "ABCDE"
|
||||
|
||||
# Optional Settings
|
||||
#------------------
|
||||
# disables automatic collection of data
|
||||
# noOnload: true
|
||||
|
||||
# disables event binding. See more here https://www.goatcounter.com/help/events
|
||||
# noEvents: true
|
||||
|
||||
# allows data collection from local addresses. Use this with a production environment to test locally
|
||||
# allowLocal: true
|
||||
|
||||
# Allow data collection when a page is loaded in a frame or iframe
|
||||
# allowFrame: true
|
||||
```
|
||||
|
||||
### LLMS.txt Support
|
||||
|
||||
To enable [llms.txt](https://llmstxt.org/) output format for your site, which provides a structured text outline for [large language models](https://en.wikipedia.org/wiki/Large_language_model) and AI agents, add the `llms` output format to your site's `hugo.yaml`:
|
||||
|
||||
```diff {filename="hugo.yaml"}
|
||||
outputs:
|
||||
- home: [html]
|
||||
+ home: [html, llms]
|
||||
page: [html]
|
||||
section: [html, rss]
|
||||
```
|
||||
|
||||
This will generate an `llms.txt` file at your site's root containing:
|
||||
|
||||
- Site title and description
|
||||
- Hierarchical listing of all sections and pages
|
||||
- Page summaries and publication dates
|
||||
- Direct links to all content
|
||||
|
||||
You can exclude specific pages or sections by setting `llms: false` in their front matter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Internal Notes"
|
||||
llms: false
|
||||
---
|
||||
```
|
||||
|
||||
The llms.txt file is automatically generated from your content structure and makes your site more accessible to AI tools and language models for context and reference.
|
||||
|
||||
### Open Graph
|
||||
|
||||
To add [Open Graph](https://ogp.me/) metadata, you can:
|
||||
- add values in the front-matter params of a page
|
||||
- or add values in the Hugo configuration file
|
||||
|
||||
As a page can have multiple `image` and `video` tags, place their values in an array.
|
||||
Other Open Graph properties can have only one value.
|
||||
|
||||
{{< tabs >}}
|
||||
{{< tab name="Page Level" >}}
|
||||
|
||||
```md {filename="mypage.md"}
|
||||
---
|
||||
title: "My Page"
|
||||
params:
|
||||
images:
|
||||
- "images/image01.jpg"
|
||||
audio: "podcast02.mp3"
|
||||
videos:
|
||||
- "video01.mp4"
|
||||
---
|
||||
|
||||
Page content.
|
||||
```
|
||||
{{< /tab >}}
|
||||
{{< tab name="Global Level" >}}
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
images:
|
||||
- "images/image01.jpg"
|
||||
audio: "podcast02.mp3"
|
||||
videos:
|
||||
- "video01.mp4"
|
||||
```
|
||||
{{< /tab >}}
|
||||
{{< /tabs >}}
|
||||
|
||||
### Banner
|
||||
|
||||
To add a banner to your site, add the following to your `hugo.yaml`:
|
||||
|
||||
```yaml
|
||||
params:
|
||||
banner:
|
||||
key: 'announcement-xxx'
|
||||
message: |
|
||||
🎉 Welcome! [Hextra](https://github.com/hextra/hextra) is a static site generator that helps you build modern websites.
|
||||
```
|
||||
|
||||
The banner will be displayed on all pages.
|
||||
|
||||
The field `message` supports Markdown syntax.
|
||||
|
||||
If you want to use template syntax, you can define the partial in `layouts/_partials/custom/banner.html`.
|
||||
In this case, the field `message` will be ignored.
|
||||
|
||||
### External Link Decoration
|
||||
|
||||
Adds an arrow icon to external links (default: false) when rendering links from Markdown.
|
||||
|
||||
```yaml
|
||||
params:
|
||||
externalLinkDecoration: true
|
||||
```
|
||||
@@ -0,0 +1,635 @@
|
||||
---
|
||||
title: 配置
|
||||
weight: 2
|
||||
tags:
|
||||
- 配置
|
||||
---
|
||||
|
||||
Hugo 从站点根目录的 `hugo.yaml` 读取配置。
|
||||
配置文件可用来调整站点的所有方面。
|
||||
查看本网站的示例配置文件 [`docs/hugo.yaml`](https://github.com/imfing/hextra/blob/main/docs/hugo.yaml) 以全面了解可用设置和最佳实践。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## 导航
|
||||
|
||||
### 菜单
|
||||
|
||||
右上角菜单在配置文件的 `menu.main` 部分定义：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- name: 文档
|
||||
pageRef: /docs
|
||||
weight: 1
|
||||
- name: 博客
|
||||
pageRef: /blog
|
||||
weight: 2
|
||||
- name: 关于
|
||||
pageRef: /about
|
||||
weight: 3
|
||||
- name: 搜索
|
||||
weight: 4
|
||||
params:
|
||||
type: search
|
||||
- name: GitHub
|
||||
weight: 5
|
||||
url: "https://github.com/imfing/hextra"
|
||||
params:
|
||||
icon: github
|
||||
```
|
||||
|
||||
菜单项有以下几种类型：
|
||||
|
||||
1. 通过 `pageRef` 链接到站内页面
|
||||
```yaml
|
||||
- name: 文档
|
||||
pageRef: /docs
|
||||
```
|
||||
2. 通过 `url` 链接到外部网址
|
||||
```yaml
|
||||
- name: GitHub
|
||||
url: "https://github.com"
|
||||
```
|
||||
3. 搜索栏，使用 `type: search`
|
||||
```yaml
|
||||
- name: 搜索
|
||||
params:
|
||||
type: search
|
||||
```
|
||||
4. 图标
|
||||
```yaml
|
||||
- name: GitHub
|
||||
params:
|
||||
icon: github
|
||||
```
|
||||
5. 主题切换
|
||||
```yaml
|
||||
- name: Theme Toggle
|
||||
params:
|
||||
type: theme-toggle
|
||||
label: true # optional, default is false
|
||||
```
|
||||
6. 语言切换器
|
||||
```yaml
|
||||
- name: 语言切换器
|
||||
params:
|
||||
type: language-switch
|
||||
label: true # optional, default is false
|
||||
icon: "globe-alt" # optional, default is "translate"
|
||||
```
|
||||
|
||||
通过设置 `weight` 参数可以调整菜单项的排序。
|
||||
|
||||
### 嵌套菜单
|
||||
|
||||
通过定义子菜单项可以创建下拉菜单。点击父菜单项时会显示子菜单。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
main:
|
||||
- identifier: sdk
|
||||
name: SDK
|
||||
- identifier: python
|
||||
name: Python ↗
|
||||
url: https://python.org
|
||||
parent: sdk
|
||||
- identifier: go
|
||||
name: Go
|
||||
url: https://go.dev
|
||||
parent: sdk
|
||||
```
|
||||
|
||||
子菜单项需要通过 `parent` 参数指定父菜单的 `identifier` 值。
|
||||
|
||||
### 徽标与标题
|
||||
|
||||
要修改默认徽标，编辑 `hugo.yaml` 并在 `static` 目录下添加徽标文件路径。
|
||||
可选地，可以更改点击徽标时的跳转链接，以及设置徽标的像素宽度和高度。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
navbar:
|
||||
displayTitle: true
|
||||
displayLogo: true
|
||||
logo:
|
||||
path: images/logo.svg
|
||||
dark: images/logo-dark.svg
|
||||
link: /
|
||||
width: 40
|
||||
height: 20
|
||||
```
|
||||
|
||||
### 分页导航
|
||||
|
||||
禁用文档页面或博客文章底部的上一篇/下一篇导航：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
displayPagination: false # 文档页面
|
||||
blog:
|
||||
article:
|
||||
displayPagination: false # 博客文章
|
||||
```
|
||||
|
||||
## 侧边栏
|
||||
|
||||
### 主侧边栏
|
||||
|
||||
主侧边栏会根据内容目录结构自动生成。
|
||||
详情参见[文件组织](/docs/guide/organize-files)页面。
|
||||
|
||||
要从左侧边栏排除单个页面，在页面的 front matter 中设置 `sidebar.exclude` 参数：
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: 配置
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
```
|
||||
|
||||
### 额外链接
|
||||
|
||||
侧边栏额外链接在配置文件的 `menu.sidebar` 部分定义：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
menu:
|
||||
sidebar:
|
||||
- name: 更多
|
||||
params:
|
||||
type: separator
|
||||
weight: 1
|
||||
- name: "关于"
|
||||
pageRef: "/about"
|
||||
weight: 2
|
||||
- name: "Hugo 文档 ↗"
|
||||
url: "https://gohugo.io/documentation/"
|
||||
weight: 3
|
||||
```
|
||||
|
||||
## 右侧边栏
|
||||
|
||||
### 目录
|
||||
|
||||
目录会根据内容文件中的标题自动生成。可以通过在页面的 front matter 中设置 `toc: false` 来禁用。
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: 配置
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
|
||||
### 页面编辑链接
|
||||
|
||||
要配置页面编辑链接，可以在配置文件中设置 `params.editURL.base` 参数：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
editURL:
|
||||
enable: true
|
||||
base: "https://github.com/your-username/your-repo/edit/main"
|
||||
```
|
||||
|
||||
编辑链接将基于提供的 URL 作为根目录自动为每个页面生成。
|
||||
如果想为特定页面设置编辑链接，可以在页面的 front matter 中设置 `editURL` 参数：
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: 配置
|
||||
editURL: "https://example.com/edit/this/page"
|
||||
---
|
||||
```
|
||||
|
||||
## 页脚
|
||||
|
||||
### 版权信息
|
||||
|
||||
要修改网站页脚显示的版权文本，需要创建一个名为 `i18n/en.yaml` 的文件。
|
||||
在该文件中指定新的版权文本，如下所示：
|
||||
|
||||
```yaml {filename="i18n/en.yaml"}
|
||||
copyright: "© 2024 你的文本内容"
|
||||
```
|
||||
|
||||
可以参考 GitHub 仓库中的示例 [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) 文件。此外，可以在版权文本中使用 Markdown 格式。
|
||||
|
||||
## 其他
|
||||
|
||||
### 网站图标
|
||||
|
||||
要自定义网站的 [favicon](https://en.wikipedia.org/wiki/Favicon)，将图标文件放在 `static` 文件夹下以覆盖[主题默认的网站图标](https://github.com/imfing/hextra/tree/main/static)：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="static" >}}
|
||||
{{< filetree/file name="android-chrome-192x192.png" >}}
|
||||
{{< filetree/file name="android-chrome-512x512.png" >}}
|
||||
{{< filetree/file name="apple-touch-icon.png" >}}
|
||||
{{< filetree/file name="favicon-16x16.png" >}}
|
||||
{{< filetree/file name="favicon-32x32.png" >}}
|
||||
{{< filetree/file name="favicon-dark.svg" >}}
|
||||
{{< filetree/file name="favicon.ico" >}}
|
||||
{{< filetree/file name="favicon.svg" >}}
|
||||
{{< filetree/file name="site.webmanifest" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
#### 基本设置
|
||||
|
||||
至少需要在 `static` 文件夹中包含 `favicon.svg`。这将作为网站的默认图标。
|
||||
|
||||
可以通过在 SVG 文件中使用 CSS 媒体查询来创建自适应图标，响应系统主题偏好，具体方法参考[构建自适应网站图标](https://web.dev/articles/building/an-adaptive-favicon)。
|
||||
|
||||
#### 暗色模式支持
|
||||
|
||||
为了增强暗色模式支持，在 `static` 文件夹中添加 `favicon-dark.svg` 与 `favicon.svg` 一起。当两个文件都存在时，Hextra 会自动：
|
||||
|
||||
- 在亮色模式或未检测到主题偏好时使用 `favicon.svg`
|
||||
- 当用户系统设置为暗色模式时切换到 `favicon-dark.svg`
|
||||
- 尊重系统的 `prefers-color-scheme` 设置实现自动切换
|
||||
|
||||
暗色模式图标切换在所有现代浏览器中都有效，包括 Firefox，提供与网站主题一致的无缝体验。
|
||||
|
||||
#### 其他格式
|
||||
|
||||
虽然 `favicon.ico` 通常用于旧版浏览器，现代浏览器支持 SVG 图标，因其可缩放性和小文件大小而更受青睐。
|
||||
如果需要，可以使用 [favicon.io](https://favicon.io/) 或 [favycon](https://github.com/ruisaraiva19/favycon) 等工具生成其他格式的图标。
|
||||
|
||||
### 主题配置
|
||||
|
||||
使用 `theme` 设置来配置默认主题模式和切换按钮，允许访问者在亮色或暗色模式之间切换。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
theme:
|
||||
# light | dark | system
|
||||
default: system
|
||||
displayToggle: true
|
||||
```
|
||||
|
||||
`theme.default` 的选项：
|
||||
|
||||
- `light` - 始终使用亮色模式
|
||||
- `dark` - 始终使用暗色模式
|
||||
- `system` - 与操作系统设置同步（默认）
|
||||
|
||||
`theme.displayToggle` 参数允许显示主题切换按钮。
|
||||
当设置为 `true` 时，访问者可以切换亮色或暗色模式，覆盖默认设置。
|
||||
|
||||
### 页面最后修改时间
|
||||
|
||||
可以通过启用 `params.displayUpdatedDate` 标志来显示页面的最后修改日期。要使用 Git 提交日期作为来源，还需启用 `enableGitInfo` 标志。
|
||||
|
||||
要自定义日期格式，设置 `params.dateFormat` 参数。其布局与 Hugo 的 [`time.Format`](https://gohugo.io/functions/time/format/) 匹配。
|
||||
|
||||
此外，可以通过启用 `params.displayUpdatedAuthor` 标志来显示最后修改的作者。这需要设置 `enableGitInfo: true`。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
# 解析 Git 提交
|
||||
enableGitInfo: true
|
||||
|
||||
params:
|
||||
# 显示最后修改日期
|
||||
displayUpdatedDate: true
|
||||
dateFormat: "2006年1月2日"
|
||||
# 显示最后修改的作者
|
||||
displayUpdatedAuthor: true
|
||||
```
|
||||
|
||||
### 标签
|
||||
|
||||
要显示页面标签，在配置文件中设置以下标志：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
blog:
|
||||
list:
|
||||
displayTags: true
|
||||
toc:
|
||||
displayTags: true
|
||||
```
|
||||
|
||||
Hugo 默认会为 `tags` 和 `categories` 创建分类页面。如果你的网站不使用分类页面，并且想省略生成的 `public/tags/` 和 `public/categories/` 目录，请禁用 `taxonomy` 和 `term` 页面类型：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
disableKinds:
|
||||
- taxonomy
|
||||
- term
|
||||
```
|
||||
|
||||
只有在不依赖标签或分类归档页面时，才禁用这些类型。
|
||||
|
||||
### 图片缩放
|
||||
|
||||
图片缩放默认禁用。启用后，点击 Markdown 图片会打开放大视图。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
```
|
||||
|
||||
要在特定页面禁用缩放，在页面的 front matter 中添加：
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
imageZoom: false
|
||||
---
|
||||
```
|
||||
|
||||
如果想固定 Medium Zoom 资源或从本地资源加载：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
base: "https://cdn.jsdelivr.net/npm/medium-zoom@1.1.0/dist"
|
||||
# js: "js/medium-zoom.min.js" # 可选，相对于 base 或本地资源
|
||||
```
|
||||
|
||||
### 本地与镜像脚本资源
|
||||
|
||||
Hextra 可以从多种来源加载可选的前端依赖：
|
||||
|
||||
- 主题默认配置（CDN）
|
||||
- 通过 `base` 指定的内部镜像 URL
|
||||
- 通过 `js` / `css` 指定的 Hugo 本地资源
|
||||
|
||||
对于本地资源，请将 vendor 文件放在站点的 `assets/` 目录下，并在配置中引用这些资源路径：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
enable: true
|
||||
js: "js/vendor/medium-zoom.min.js"
|
||||
|
||||
mermaid:
|
||||
js: "js/vendor/mermaid.min.js"
|
||||
|
||||
asciinema:
|
||||
js: "js/vendor/asciinema-player.min.js"
|
||||
css: "css/vendor/asciinema-player.css"
|
||||
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
css: "css/vendor/katex.min.css"
|
||||
assets:
|
||||
- "fonts/KaTeX_Main-Regular.woff2"
|
||||
- "fonts/KaTeX_Math-Italic.woff2"
|
||||
|
||||
search:
|
||||
type: flexsearch
|
||||
flexsearch:
|
||||
js: "js/vendor/flexsearch.bundle.min.js"
|
||||
```
|
||||
|
||||
这里只有因为图片缩放默认关闭，才需要设置 `imageZoom.enable: true`。
|
||||
对于 KaTeX，请确保发布你所选 CSS 文件引用的全部字体文件，而不仅仅是此示例中的两个。
|
||||
|
||||
如果要使用内部镜像，请设置 `base`；只有当文件名不同时，才需要额外设置 `js` / `css`：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
imageZoom:
|
||||
base: "https://mirror.example.com/medium-zoom/dist"
|
||||
|
||||
mermaid:
|
||||
base: "https://mirror.example.com/mermaid/dist"
|
||||
|
||||
asciinema:
|
||||
base: "https://mirror.example.com/asciinema-player/dist/bundle"
|
||||
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
base: "https://mirror.example.com/katex/dist"
|
||||
|
||||
search:
|
||||
flexsearch:
|
||||
base: "https://mirror.example.com/flexsearch/dist"
|
||||
# js: "flexsearch.bundle.min.js"
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> 如需自定义 MathJax 的加载来源，请在项目中覆盖 `layouts/_partials/scripts/mathjax.html`。
|
||||
|
||||
### 页面宽度
|
||||
|
||||
页面整体布局宽度可通过 `params.page.width` 配置：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
# full (100%), wide (90rem), normal (1280px)
|
||||
width: wide
|
||||
```
|
||||
|
||||
`params.page.width` 可用选项：`full`、`wide`、`normal`。
|
||||
|
||||
正文内容宽度默认固定为 `72rem`。
|
||||
|
||||
如需自定义内容宽度，请在自定义样式表中覆盖 CSS 变量：
|
||||
|
||||
```css {filename="assets/css/custom.css"}
|
||||
:root {
|
||||
--hextra-max-content-width: 100%;
|
||||
}
|
||||
```
|
||||
|
||||
类似地，导航栏和页脚的宽度可以通过 `params.navbar.width` 和 `params.footer.width` 参数自定义。
|
||||
|
||||
### 页面上下文菜单
|
||||
|
||||
页面上下文菜单提供一个下拉按钮，允许用户将页面内容复制为 Markdown 或查看原始 Markdown 源码。此功能对于读者可能希望以 Markdown 格式共享或引用内容的文档站点非常有用。
|
||||
|
||||
#### 启用上下文菜单
|
||||
|
||||
要全局启用上下文菜单，请在配置文件中添加以下内容：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
```
|
||||
|
||||
您还需要为页面启用 `markdown` 输出格式：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
outputs:
|
||||
page: [html, markdown]
|
||||
section: [html, rss, markdown]
|
||||
```
|
||||
|
||||
#### 单页控制
|
||||
|
||||
要为特定页面启用或禁用上下文菜单，请在 front matter 中使用 `contextMenu` 参数：
|
||||
|
||||
```yaml {filename="content/docs/example.md"}
|
||||
---
|
||||
title: 示例页面
|
||||
contextMenu: false
|
||||
---
|
||||
```
|
||||
|
||||
#### 自定义链接
|
||||
|
||||
您可以向上下文菜单下拉列表添加自定义链接。这对于与外部服务集成非常有用。链接支持以下占位符：
|
||||
|
||||
- `{url}` - 页面 URL（URL 编码）
|
||||
- `{title}` - 页面标题（URL 编码）
|
||||
- `{markdown_url}` - 原始 Markdown 内容的 URL（URL 编码）
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
page:
|
||||
contextMenu:
|
||||
enable: true
|
||||
links:
|
||||
- name: 在 ChatGPT 中打开
|
||||
icon: chatgpt
|
||||
url: "https://chatgpt.com/?hints=search&q=I%27m+looking+at+this+documentation%3A+{url}%0AHelp+me+understand+how+to+use+it."
|
||||
```
|
||||
|
||||
每个链接可以包含：
|
||||
- `name` - 链接的显示文本
|
||||
- `icon` - 可选的图标名称（参见[图标]({{% relref "docs/guide/shortcodes/icon" %}})）
|
||||
- `url` - 包含可选占位符的 URL
|
||||
|
||||
### FlexSearch 索引
|
||||
|
||||
默认启用由 [FlexSearch](https://github.com/nextapps-de/flexsearch) 提供的全文搜索。
|
||||
要自定义搜索索引，在配置文件中设置 `params.search.flexsearch.index` 参数：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
# 搜索
|
||||
search:
|
||||
enable: true
|
||||
type: flexsearch
|
||||
|
||||
flexsearch:
|
||||
# 索引页面方式: content | summary | heading | title
|
||||
index: content
|
||||
```
|
||||
|
||||
你也可以控制 FlexSearch runtime 的加载来源：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
search:
|
||||
flexsearch:
|
||||
version: "0.8.143" # 默认 CDN 版本
|
||||
# base: "https://mirror.example.com/flexsearch/dist" # 可选的远程 base URL
|
||||
# js: "js/vendor/flexsearch.bundle.min.js" # 本地资源路径，或远程 base 下的自定义文件
|
||||
```
|
||||
|
||||
`flexsearch.index` 的选项：
|
||||
|
||||
- `content` - 页面的完整内容（默认）
|
||||
- `summary` - 页面摘要，详见 [Hugo 内容摘要](https://gohugo.io/content-management/summaries/)
|
||||
- `heading` - 一级和二级标题
|
||||
- `title` - 仅包含页面标题
|
||||
|
||||
要自定义搜索分词方式，在配置文件中设置 `params.search.flexsearch.tokenize` 参数：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
search:
|
||||
# ...
|
||||
flexsearch:
|
||||
# full | forward | reverse | strict
|
||||
tokenize: forward
|
||||
```
|
||||
|
||||
[`flexsearch.tokenize`](https://github.com/nextapps-de/flexsearch/#tokenizer-prefix-search) 的选项：
|
||||
|
||||
- `strict` - 索引完整单词
|
||||
- `forward` - 正向逐步索引单词
|
||||
- `reverse` - 双向逐步索引单词
|
||||
- `full` - 索引所有可能的组合
|
||||
|
||||
要从 FlexSearch 搜索索引中排除页面，在页面的 front matter 中设置 `excludeSearch: true`：
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
---
|
||||
title: 配置
|
||||
excludeSearch: true
|
||||
---
|
||||
```
|
||||
|
||||
### Google 分析
|
||||
|
||||
要启用 [Google Analytics](https://marketingplatform.google.com/about/analytics/)，在 `hugo.yaml` 中设置 `services.googleAnalytics.ID` 标志：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
services:
|
||||
googleAnalytics:
|
||||
ID: G-MEASUREMENT_ID
|
||||
```
|
||||
|
||||
### Google 搜索索引
|
||||
|
||||
要[阻止 Google 搜索](https://developers.google.com/search/docs/crawling-indexing/block-indexing)索引页面，在页面的 frontmatter 中设置 `noindex` 为 true：
|
||||
|
||||
```yaml
|
||||
title: 配置（存档版本）
|
||||
params:
|
||||
noindex: true
|
||||
```
|
||||
|
||||
要排除整个目录，在父级 `_index.md` 文件中使用 [`cascade`](https://gohugo.io/configuration/cascade/) 键。
|
||||
|
||||
> [!注意]
|
||||
> 要阻止搜索引擎爬虫，可以制作 [`robots.txt` 模板](https://gohugo.io/templates/robots/)。
|
||||
> 但是，`robots.txt` 指令不一定能阻止页面出现在 Google 搜索结果中。
|
||||
|
||||
### LLMS.txt 支持
|
||||
|
||||
要为网站启用 [llms.txt](https://llmstxt.org/) 输出格式，为[大型语言模型](https://en.wikipedia.org/wiki/Large_language_model)和 AI 代理提供结构化文本大纲，在站点的 `hugo.yaml` 中添加 `llms` 输出格式：
|
||||
|
||||
```diff {filename="hugo.yaml"}
|
||||
outputs:
|
||||
- home: [html]
|
||||
+ home: [html, llms]
|
||||
page: [html]
|
||||
section: [html, rss]
|
||||
```
|
||||
|
||||
这将在站点根目录生成一个 `llms.txt` 文件，包含：
|
||||
|
||||
- 站点标题和描述
|
||||
- 所有章节和页面的层次结构列表
|
||||
- 页面摘要和发布日期
|
||||
- 所有内容的直接链接
|
||||
|
||||
您可以通过在 front matter 中设置 `llms: false` 来排除特定页面或章节：
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "内部笔记"
|
||||
llms: false
|
||||
---
|
||||
```
|
||||
|
||||
llms.txt 文件根据内容结构自动生成，使 AI 工具和语言模型更容易获取上下文和参考。
|
||||
|
||||
### Open Graph
|
||||
|
||||
要在页面中添加 [Open Graph](https://ogp.me/) 元数据，在 frontmatter 的 params 中添加值。
|
||||
|
||||
由于一个页面可以有多个 `image` 和 `video` 标签，将它们的值放在数组中。
|
||||
其他 Open Graph 属性只能有一个值。
|
||||
例如，此页面有一个 `og:image` 标签（配置社交分享时的预览图片）和一个 `og:audio` 标签。
|
||||
|
||||
```yaml {filename="content/docs/guide/configuration.md"}
|
||||
title: "配置"
|
||||
params:
|
||||
images:
|
||||
- "img/config-image.jpg"
|
||||
audio: "config-talk.mp3"
|
||||
```
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
title: استقرار سایت
|
||||
prev: /docs/guide/shortcodes
|
||||
next: /docs/advanced
|
||||
---
|
||||
|
||||
Hugo وبسایتهای استاتیک تولید میکند که امکان میزبانی انعطافپذیر را فراهم میسازد.
|
||||
این صفحه راهنماهایی برای استقرار سایت Hextra شما روی پلتفرمهای مختلف ارائه میدهد.
|
||||
|
||||
<!--more-->
|
||||
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
[GitHub Pages](https://docs.github.com/pages) روش توصیهشده برای استقرار و میزبانی رایگان وبسایت شماست.
|
||||
|
||||
اگر سایت را با استفاده از [hextra-starter-template](https://github.com/imfing/hextra-starter-template) راهاندازی کردهاید، این قالب از پیش یک گردش کار GitHub Actions برای استقرار خودکار در GitHub Pages ارائه میدهد.
|
||||
|
||||
{{% details title="پیکربندی GitHub Actions" closed="true" %}}
|
||||
|
||||
در زیر یک نمونه پیکربندی از [hextra-starter-template](https://github.com/imfing/hextra-starter-template) آمده است:
|
||||
|
||||
```yaml {filename=".github/workflows/pages.yaml"}
|
||||
# نمونه گردش کار برای ساخت و استقرار یک سایت Hugo در GitHub Pages
|
||||
name: استقرار سایت Hugo در Pages
|
||||
|
||||
on:
|
||||
# در push به شاخه پیشفرض اجرا میشود
|
||||
push:
|
||||
branches: ["main"]
|
||||
|
||||
# امکان اجرای دستی این گردش کار از تب Actions
|
||||
workflow_dispatch:
|
||||
|
||||
# تنظیم مجوزهای GITHUB_TOKEN برای امکان استقرار در GitHub Pages
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# اجازه فقط یک استقرار همزمان، رد کردن اجراهای در صف بین اجرای در حال انجام و آخرین صف
|
||||
# با این حال، اجراهای در حال انجام را لغو نکنید زیرا میخواهیم این استقرارها کامل شوند.
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
# پیشفرض bash
|
||||
defaults:
|
||||
run:
|
||||
shell: bash
|
||||
|
||||
jobs:
|
||||
# کار ساخت
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
HUGO_VERSION: 0.147.7
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # دریافت تمام تاریخچه برای .GitInfo و .Lastmod
|
||||
submodules: recursive
|
||||
- name: راهاندازی Go
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: '1.22'
|
||||
- name: راهاندازی Pages
|
||||
id: pages
|
||||
uses: actions/configure-pages@v4
|
||||
- name: راهاندازی Hugo
|
||||
run: |
|
||||
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
|
||||
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
|
||||
- name: ساخت با Hugo
|
||||
env:
|
||||
# برای حداکثر سازگاری با ماژولهای Hugo
|
||||
HUGO_ENVIRONMENT: production
|
||||
HUGO_ENV: production
|
||||
run: |
|
||||
hugo \
|
||||
--gc --minify \
|
||||
--baseURL "${{ steps.pages.outputs.base_url }}/"
|
||||
- name: آپلود آرتیفکت
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: ./public
|
||||
|
||||
# کار استقرار
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
steps:
|
||||
- name: استقرار در GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
```
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
|
||||
{{< callout >}}
|
||||
در تنظیمات مخزن، بخش **Pages** > **Build and deployment** > **Source** را روی **GitHub Actions** تنظیم کنید:
|
||||
|
||||
{{< /callout >}}
|
||||
|
||||
به طور پیشفرض، گردش کار GitHub Actions فوق `.github/workflows/pages.yaml` فرض میکند که سایت در `https://<USERNAME>.github.io/<REPO>/` مستقر میشود.
|
||||
|
||||
اگر در `https://<USERNAME>.github.io/` مستقر میکنید، `--baseURL` را اصلاح کنید:
|
||||
|
||||
```yaml {filename=".github/workflows/pages.yaml",linenos=table,linenostart=54,hl_lines=[4]}
|
||||
run: |
|
||||
hugo \
|
||||
--gc --minify \
|
||||
--baseURL "https://${{ github.repository_owner }}.github.io/"
|
||||
```
|
||||
|
||||
اگر در دامنه خود مستقر میکنید، لطفاً مقدار `--baseURL` را متناسب با آن تغییر دهید.
|
||||
|
||||
|
||||
## Cloudflare Pages
|
||||
|
||||
1. کد منبع سایت را در یک مخزن Git (مثلاً GitHub) قرار دهید.
|
||||
2. به [داشبورد Cloudflare](https://dash.cloudflare.com/) وارد شوید و حساب خود را انتخاب کنید.
|
||||
3. در صفحه اصلی حساب، **Workers & Pages** > **Create application** > **Pages** > **Connect to Git** را انتخاب کنید.
|
||||
4. مخزن را انتخاب کنید و در بخش **Set up builds and deployments** اطلاعات زیر را ارائه دهید:
|
||||
|
||||
| تنظیمات | مقدار |
|
||||
| ---------------- | -------------------- |
|
||||
| شاخه تولید | `main` |
|
||||
| دستور ساخت | `hugo --gc --minify` |
|
||||
| دایرکتوری ساخت | `public` |
|
||||
|
||||
برای جزئیات بیشتر، بررسی کنید:
|
||||
- [استقرار یک سایت Hugo](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages).
|
||||
- [پشتیبانی زبان و ابزارها](https://developers.cloudflare.com/pages/platform/language-support-and-tools/).
|
||||
|
||||
|
||||
## Netlify
|
||||
|
||||
1. کد خود را به مخزن Git (GitHub, GitLab و غیره) push کنید.
|
||||
2. [پروژه را به Netlify وارد کنید](https://app.netlify.com/start).
|
||||
3. اگر از [hextra-starter-template][hextra-starter-template] استفاده نمیکنید، موارد زیر را به صورت دستی پیکربندی کنید:
|
||||
- دستور ساخت را روی `hugo --gc --minify` تنظیم کنید.
|
||||
- دایرکتوری انتشار را روی `public` مشخص کنید.
|
||||
- متغیر محیطی `HUGO_VERSION` را اضافه کرده و روی `0.147.7` تنظیم کنید، یا آن را در فایل `netlify.toml` مشخص کنید.
|
||||
4. استقرار دهید!
|
||||
|
||||
برای جزئیات بیشتر، [Hugo در Netlify](https://docs.netlify.com/integrations/frameworks/hugo/) را بررسی کنید.
|
||||
|
||||
|
||||
## Vercel
|
||||
|
||||
1. کد خود را به مخزن Git (GitHub, GitLab و غیره) push کنید.
|
||||
2. به [داشبورد Vercel](https://vercel.com/dashboard) بروید و پروژه Hugo خود را وارد کنید.
|
||||
3. پروژه را پیکربندی کنید، Hugo را به عنوان پیشتنظیم فریمورک انتخاب کنید.
|
||||
4. دستور ساخت و دستور نصب را بازنویسی کنید:
|
||||
1. دستور ساخت را روی `hugo --gc --minify` تنظیم کنید.
|
||||
2. دستور نصب را روی `yum install golang` تنظیم کنید.
|
||||
|
||||
|
||||
@@ -0,0 +1,163 @@
|
||||
---
|
||||
title: サイトのデプロイ
|
||||
prev: /docs/guide/shortcodes
|
||||
next: /docs/advanced
|
||||
---
|
||||
|
||||
Hugo は静的サイトを生成するため、柔軟なホスティングオプションが利用可能です。
|
||||
このページでは、Hextra サイトを様々なプラットフォームにデプロイする方法を解説します。
|
||||
|
||||
<!--more-->
|
||||
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
[GitHub Pages](https://docs.github.com/pages) は無料でサイトをデプロイ・ホストするための推奨方法です。
|
||||
|
||||
[hextra-starter-template](https://github.com/imfing/hextra-starter-template) を使用してサイトを構築した場合、GitHub Pages への自動デプロイを支援する GitHub Actions ワークフローが最初から用意されています。
|
||||
|
||||
{{% details title="GitHub Actions 設定" closed="true" %}}
|
||||
|
||||
以下は [hextra-starter-template](https://github.com/imfing/hextra-starter-template) の設定例です:
|
||||
|
||||
```yaml {filename=".github/workflows/pages.yaml"}
|
||||
# Hugo サイトをビルドし GitHub Pages にデプロイするサンプルワークフロー
|
||||
name: Deploy Hugo site to Pages
|
||||
|
||||
on:
|
||||
# デフォルトブランチへのプッシュ時に実行
|
||||
push:
|
||||
branches: ["main"]
|
||||
|
||||
# Actions タブから手動で実行可能
|
||||
workflow_dispatch:
|
||||
|
||||
# GITHUB_TOKEN の権限を設定（GitHub Pages へのデプロイを許可）
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# 同時実行を1つに制限（進行中の実行はキャンセルしない）
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
# デフォルトシェルを bash に設定
|
||||
defaults:
|
||||
run:
|
||||
shell: bash
|
||||
|
||||
jobs:
|
||||
# ビルドジョブ
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
HUGO_VERSION: 0.147.7
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # .GitInfo と .Lastmod 用に全履歴を取得
|
||||
submodules: recursive
|
||||
- name: Setup Go
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: '1.22'
|
||||
- name: Setup Pages
|
||||
id: pages
|
||||
uses: actions/configure-pages@v4
|
||||
- name: Setup Hugo
|
||||
run: |
|
||||
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
|
||||
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
|
||||
- name: Build with Hugo
|
||||
env:
|
||||
# Hugo モジュールとの最大互換性のため
|
||||
HUGO_ENVIRONMENT: production
|
||||
HUGO_ENV: production
|
||||
run: |
|
||||
hugo \
|
||||
--gc --minify \
|
||||
--baseURL "${{ steps.pages.outputs.base_url }}/"
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: ./public
|
||||
|
||||
# デプロイジョブ
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
```
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
|
||||
{{< callout type="warning" >}}
|
||||
リポジトリ設定で、**Pages** > **Build and deployment** > **Source** を **GitHub Actions** に設定してください:
|
||||
|
||||
{{< /callout >}}
|
||||
|
||||
デフォルトでは、上記の GitHub Actions ワークフロー `.github/workflows/pages.yaml` は `https://<USERNAME>.github.io/<REPO>/` へのデプロイを想定しています。
|
||||
|
||||
`https://<USERNAME>.github.io/` にデプロイする場合は `--baseURL` を修正してください:
|
||||
|
||||
```yaml {filename=".github/workflows/pages.yaml",linenos=table,linenostart=54,hl_lines=[4]}
|
||||
run: |
|
||||
hugo \
|
||||
--gc --minify \
|
||||
--baseURL "https://${{ github.repository_owner }}.github.io/"
|
||||
```
|
||||
|
||||
独自ドメインを使用する場合は、`--baseURL` の値を適宜変更してください。
|
||||
|
||||
|
||||
## Cloudflare Pages
|
||||
|
||||
1. サイトのソースコードを Git リポジトリ（GitHub など）に配置
|
||||
2. [Cloudflare ダッシュボード](https://dash.cloudflare.com/) にログインしアカウントを選択
|
||||
3. Account Home で **Workers & Pages** > **Create application** > **Pages** > **Connect to Git** を選択
|
||||
4. リポジトリを選択し、**Set up builds and deployments** セクションで以下を設定:
|
||||
|
||||
| 設定項目 | 値 |
|
||||
| ----------------- | -------------------- |
|
||||
| Production branch | `main` |
|
||||
| Build command | `hugo --gc --minify` |
|
||||
| Build directory | `public` |
|
||||
|
||||
詳細は以下を参照:
|
||||
- [Deploy a Hugo site](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages)
|
||||
- [Language support and tools](https://developers.cloudflare.com/pages/platform/language-support-and-tools/)
|
||||
|
||||
|
||||
## Netlify
|
||||
|
||||
1. コードを Git リポジトリ（GitHub, GitLab など）にプッシュ
|
||||
2. Netlify に [プロジェクトをインポート](https://app.netlify.com/start)
|
||||
3. [hextra-starter-template][hextra-starter-template] を使用していない場合、以下を手動設定:
|
||||
- Build command を `hugo --gc --minify` に設定
|
||||
- Publish directory を `public` に指定
|
||||
- 環境変数 `HUGO_VERSION` を追加し `0.147.7` を設定、または `netlify.toml` ファイルで設定
|
||||
4. デプロイ！
|
||||
|
||||
詳細は [Hugo on Netlify](https://docs.netlify.com/integrations/frameworks/hugo/) を参照
|
||||
|
||||
|
||||
## Vercel
|
||||
|
||||
1. コードを Git リポジトリ（GitHub, GitLab など）にプッシュ
|
||||
2. [Vercel ダッシュボード](https://vercel.com/dashboard) に移動し Hugo プロジェクトをインポート
|
||||
3. プロジェクトを設定、Framework Preset で Hugo を選択
|
||||
4. Build Command と Install command を上書き:
|
||||
1. Build Command を `hugo --gc --minify` に設定
|
||||
2. Install Command を `yum install golang` に設定
|
||||
|
||||
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
title: Deploy Site
|
||||
prev: /docs/guide/shortcodes
|
||||
next: /docs/advanced
|
||||
---
|
||||
|
||||
Hugo generates static websites, allowing for flexible hosting options.
|
||||
This page provides guides for deploying your Hextra site on various platforms.
|
||||
|
||||
<!--more-->
|
||||
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
[GitHub Pages](https://docs.github.com/pages) is the recommended way to deploy and host your website for free.
|
||||
|
||||
If you bootstrap the site using [hextra-starter-template](https://github.com/imfing/hextra-starter-template), it has provided GitHub Actions workflow out-of-the-box that helps automatically deploy to GitHub Pages.
|
||||
|
||||
{{% details title="GitHub Actions Configuration" closed="true" %}}
|
||||
|
||||
Below is an example configuration from [hextra-starter-template](https://github.com/imfing/hextra-starter-template):
|
||||
|
||||
```yaml {filename=".github/workflows/pages.yaml"}
|
||||
# Sample workflow for building and deploying a Hugo site to GitHub Pages
|
||||
name: Deploy Hugo site to Pages
|
||||
|
||||
on:
|
||||
# Runs on pushes targeting the default branch
|
||||
push:
|
||||
branches: ["main"]
|
||||
|
||||
# Allows you to run this workflow manually from the Actions tab
|
||||
workflow_dispatch:
|
||||
|
||||
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
|
||||
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
# Default to bash
|
||||
defaults:
|
||||
run:
|
||||
shell: bash
|
||||
|
||||
jobs:
|
||||
# Build job
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
HUGO_VERSION: 0.147.7
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # fetch all history for .GitInfo and .Lastmod
|
||||
submodules: recursive
|
||||
- name: Setup Go
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: '1.22'
|
||||
- name: Setup Pages
|
||||
id: pages
|
||||
uses: actions/configure-pages@v4
|
||||
- name: Setup Hugo
|
||||
run: |
|
||||
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
|
||||
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
|
||||
- name: Build with Hugo
|
||||
env:
|
||||
# For maximum backward compatibility with Hugo modules
|
||||
HUGO_ENVIRONMENT: production
|
||||
HUGO_ENV: production
|
||||
run: |
|
||||
hugo \
|
||||
--gc --minify \
|
||||
--baseURL "${{ steps.pages.outputs.base_url }}/"
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: ./public
|
||||
|
||||
# Deployment job
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
```
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
|
||||
{{< callout type="warning" >}}
|
||||
In your repository settings, set the **Pages** > **Build and deployment** > **Source** to **GitHub Actions**:
|
||||
|
||||
{{< /callout >}}
|
||||
|
||||
By default, the above GitHub Actions workflow `.github/workflows/pages.yaml` assumes that the site is deploying to `https://<USERNAME>.github.io/<REPO>/`.
|
||||
|
||||
If you are deploying to `https://<USERNAME>.github.io/` then modify the `--baseURL`:
|
||||
|
||||
```yaml {filename=".github/workflows/pages.yaml",linenos=table,linenostart=54,hl_lines=[4]}
|
||||
run: |
|
||||
hugo \
|
||||
--gc --minify \
|
||||
--baseURL "https://${{ github.repository_owner }}.github.io/"
|
||||
```
|
||||
|
||||
If you are deploying to your own domain, please change the `--baseURL` value accordingly.
|
||||
|
||||
|
||||
## Cloudflare Pages
|
||||
|
||||
1. Put your site source code in a Git repository (e.g. GitHub)
|
||||
2. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account
|
||||
3. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**
|
||||
4. Select the repository, and in the **Set up builds and deployments** section, provide the following information:
|
||||
|
||||
| Configuration | Value |
|
||||
| ----------------- | -------------------- |
|
||||
| Production branch | `main` |
|
||||
| Build command | `hugo --gc --minify` |
|
||||
| Build directory | `public` |
|
||||
|
||||
For more details, check out:
|
||||
- [Deploy a Hugo site](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages).
|
||||
- [Language support and tools](https://developers.cloudflare.com/pages/platform/language-support-and-tools/).
|
||||
|
||||
|
||||
## Netlify
|
||||
|
||||
1. Push your code to your Git repository (GitHub, GitLab, etc.)
|
||||
2. [Import the project](https://app.netlify.com/start) to Netlify
|
||||
3. If you are not using [hextra-starter-template][hextra-starter-template], configure the following manually:
|
||||
- Configure the Build command to `hugo --gc --minify`
|
||||
- Specify the Publish directory to `public`
|
||||
- Add Environment variable `HUGO_VERSION` and set to `0.147.7`, or alternatively, set it in `netlify.toml` file
|
||||
4. Deploy!
|
||||
|
||||
Check [Hugo on Netlify](https://docs.netlify.com/integrations/frameworks/hugo/) for more details.
|
||||
|
||||
|
||||
## Vercel
|
||||
|
||||
1. Push your code to your Git repository (GitHub, GitLab, etc.)
|
||||
2. Go to [Vercel Dashboard](https://vercel.com/dashboard) and import your Hugo project
|
||||
3. Configure the project, select Hugo as Framework Preset
|
||||
4. Override the Build Command and Install command:
|
||||
1. Set Build Command to `hugo --gc --minify`
|
||||
2. Set Install Command to `yum install golang`
|
||||
|
||||
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
title: 部署站点
|
||||
prev: /docs/guide/shortcodes
|
||||
next: /docs/advanced
|
||||
---
|
||||
|
||||
Hugo 生成静态网站，支持灵活的托管方案。
|
||||
本页提供在各类平台上部署 Hextra 站点的指南。
|
||||
|
||||
<!--more-->
|
||||
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
[GitHub Pages](https://docs.github.com/pages) 是推荐的免费部署托管方案。
|
||||
|
||||
若使用 [hextra-starter-template](https://github.com/imfing/hextra-starter-template) 初始化项目，已内置 GitHub Actions 工作流，可自动部署至 GitHub Pages。
|
||||
|
||||
{{% details title="GitHub Actions 配置" closed="true" %}}
|
||||
|
||||
以下是 [hextra-starter-template](https://github.com/imfing/hextra-starter-template) 的示例配置：
|
||||
|
||||
```yaml {filename=".github/workflows/pages.yaml"}
|
||||
# 构建并部署 Hugo 站点到 GitHub Pages 的示例工作流
|
||||
name: 部署 Hugo 站点到 Pages
|
||||
|
||||
on:
|
||||
# 针对默认分支的推送触发
|
||||
push:
|
||||
branches: ["main"]
|
||||
|
||||
# 允许从 Actions 标签手动运行
|
||||
workflow_dispatch:
|
||||
|
||||
# 设置 GITHUB_TOKEN 权限以允许部署到 GitHub Pages
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# 仅允许一个并发部署，跳过正在运行与最新排队之间的运行
|
||||
# 但不会取消进行中的运行，以确保生产部署完成
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
# 默认使用 bash
|
||||
defaults:
|
||||
run:
|
||||
shell: bash
|
||||
|
||||
jobs:
|
||||
# 构建任务
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
HUGO_VERSION: 0.147.7
|
||||
steps:
|
||||
- name: 检出代码
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # 获取完整历史记录以支持 .GitInfo 和 .Lastmod
|
||||
submodules: recursive
|
||||
- name: 设置 Go 环境
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: '1.22'
|
||||
- name: 配置 Pages
|
||||
id: pages
|
||||
uses: actions/configure-pages@v4
|
||||
- name: 安装 Hugo
|
||||
run: |
|
||||
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
|
||||
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
|
||||
- name: 使用 Hugo 构建
|
||||
env:
|
||||
# 为 Hugo 模块提供最大兼容性
|
||||
HUGO_ENVIRONMENT: production
|
||||
HUGO_ENV: production
|
||||
run: |
|
||||
hugo \
|
||||
--gc --minify \
|
||||
--baseURL "${{ steps.pages.outputs.base_url }}/"
|
||||
- name: 上传产物
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: ./public
|
||||
|
||||
# 部署任务
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
steps:
|
||||
- name: 部署到 GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
```
|
||||
|
||||
{{% /details %}}
|
||||
|
||||
|
||||
{{< callout type="warning" >}}
|
||||
在仓库设置中，将 **Pages** > **构建与部署** > **源** 设为 **GitHub Actions**：
|
||||
|
||||
{{< /callout >}}
|
||||
|
||||
默认配置中，GitHub Actions 工作流 `.github/workflows/pages.yaml` 假设站点部署在 `https://<用户名>.github.io/<仓库名>/`。
|
||||
|
||||
若需部署到 `https://<用户名>.github.io/`，请修改 `--baseURL`：
|
||||
|
||||
```yaml {filename=".github/workflows/pages.yaml",linenos=table,linenostart=54,hl_lines=[4]}
|
||||
run: |
|
||||
hugo \
|
||||
--gc --minify \
|
||||
--baseURL "https://${{ github.repository_owner }}.github.io/"
|
||||
```
|
||||
|
||||
若使用自定义域名，请相应调整 `--baseURL` 值。
|
||||
|
||||
|
||||
## Cloudflare Pages
|
||||
|
||||
1. 将站点源码存入 Git 仓库（如 GitHub）
|
||||
2. 登录 [Cloudflare 控制台](https://dash.cloudflare.com/) 并选择账户
|
||||
3. 在账户首页选择 **Workers & Pages** > **创建应用** > **Pages** > **连接 Git**
|
||||
4. 选择仓库后，在 **设置构建与部署** 部分填写：
|
||||
|
||||
| 配置项 | 值 |
|
||||
| ---------------- | -------------------- |
|
||||
| 生产分支 | `main` |
|
||||
| 构建命令 | `hugo --gc --minify` |
|
||||
| 构建输出目录 | `public` |
|
||||
|
||||
更多细节请参阅：
|
||||
- [部署 Hugo 站点](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages)
|
||||
- [语言支持与工具](https://developers.cloudflare.com/pages/platform/language-support-and-tools/)
|
||||
|
||||
|
||||
## Netlify
|
||||
|
||||
1. 将代码推送到 Git 仓库（GitHub/GitLab 等）
|
||||
2. 在 Netlify 中[导入项目](https://app.netlify.com/start)
|
||||
3. 若未使用 [hextra-starter-template][hextra-starter-template]，需手动配置：
|
||||
- 构建命令设为 `hugo --gc --minify`
|
||||
- 发布目录设为 `public`
|
||||
- 添加环境变量 `HUGO_VERSION` 并设为 `0.147.7`，或在 `netlify.toml` 中配置
|
||||
4. 开始部署！
|
||||
|
||||
详见 [Netlify 上的 Hugo](https://docs.netlify.com/integrations/frameworks/hugo/)
|
||||
|
||||
|
||||
## Vercel
|
||||
|
||||
1. 将代码推送到 Git 仓库（GitHub/GitLab 等）
|
||||
2. 进入 [Vercel 控制台](https://vercel.com/dashboard) 导入 Hugo 项目
|
||||
3. 配置项目时选择 Hugo 作为框架预设
|
||||
4. 覆盖构建命令与安装命令：
|
||||
1. 构建命令设为 `hugo --gc --minify`
|
||||
2. 安装命令设为 `yum install golang`
|
||||
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: نمودارها
|
||||
weight: 6
|
||||
next: /docs/guide/shortcodes
|
||||
---
|
||||
|
||||
در حال حاضر، Hextra از [Mermaid](#mermaid) برای نمودارها پشتیبانی میکند.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Mermaid
|
||||
|
||||
[Mermaid](https://github.com/mermaid-js/mermaid#readme) یک ابزار نمودار و چارت مبتنی بر جاوااسکریپت است که تعاریف متنی الهامگرفته از Markdown را گرفته و به صورت پویا در مرورگر نمودارها را ایجاد میکند. به عنوان مثال، Mermaid میتواند فلوچارتها، نمودارهای توالی، نمودارهای دایرهای و موارد دیگر را رندر کند.
|
||||
|
||||
استفاده از Mermaid در Hextra به سادگی نوشتن یک بلوک کد با زبان تنظیم شده `mermaid` است:
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->B;
|
||||
A-->C;
|
||||
B-->D;
|
||||
C-->D;
|
||||
```
|
||||
````
|
||||
|
||||
به صورت زیر رندر میشود:
|
||||
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->B;
|
||||
A-->C;
|
||||
B-->D;
|
||||
C-->D;
|
||||
```
|
||||
|
||||
نمودار توالی:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Alice
|
||||
participant Bob
|
||||
Alice->>John: Hello John, how are you?
|
||||
loop Healthcheck
|
||||
John->>John: Fight against hypochondria
|
||||
end
|
||||
Note right of John: Rational thoughts <br/>prevail!
|
||||
John-->>Alice: Great!
|
||||
John->>Bob: How about you?
|
||||
Bob-->>John: Jolly good!
|
||||
```
|
||||
|
||||
برای اطلاعات بیشتر، لطفاً به [مستندات Mermaid](https://mermaid-js.github.io/mermaid/#/) مراجعه کنید.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: ダイアグラム
|
||||
weight: 6
|
||||
next: /docs/guide/shortcodes
|
||||
---
|
||||
|
||||
現在、Hextra は [Mermaid](#mermaid) によるダイアグラム作成をサポートしています。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Mermaid
|
||||
|
||||
[Mermaid](https://github.com/mermaid-js/mermaid#readme) は、JavaScript ベースのダイアグラムおよびチャート作成ツールで、Markdown 風のテキスト定義をブラウザ上で動的にダイアグラムに変換します。例えば、Mermaid はフローチャート、シーケンス図、円グラフなどをレンダリングできます。
|
||||
|
||||
Hextra で Mermaid を使用するには、言語を `mermaid` に設定したコードブロックを記述するだけです:
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->B;
|
||||
A-->C;
|
||||
B-->D;
|
||||
C-->D;
|
||||
```
|
||||
````
|
||||
|
||||
これは以下のようにレンダリングされます:
|
||||
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->B;
|
||||
A-->C;
|
||||
B-->D;
|
||||
C-->D;
|
||||
```
|
||||
|
||||
シーケンス図の例:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Alice
|
||||
participant Bob
|
||||
Alice->>John: Hello John, how are you?
|
||||
loop Healthcheck
|
||||
John->>John: Fight against hypochondria
|
||||
end
|
||||
Note right of John: Rational thoughts <br/>prevail!
|
||||
John-->>Alice: Great!
|
||||
John->>Bob: How about you?
|
||||
Bob-->>John: Jolly good!
|
||||
```
|
||||
|
||||
詳細については、[Mermaid ドキュメント](https://mermaid-js.github.io/mermaid/#/)を参照してください。
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Diagrams
|
||||
weight: 6
|
||||
next: /docs/guide/shortcodes
|
||||
---
|
||||
|
||||
Currently, Hextra supports [Mermaid](#mermaid) for diagrams.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Mermaid
|
||||
|
||||
[Mermaid](https://github.com/mermaid-js/mermaid#readme) is a JavaScript based diagramming and charting tool that takes Markdown-inspired text definitions and creates diagrams dynamically in the browser. For example, Mermaid can render flow charts, sequence diagrams, pie charts and more.
|
||||
|
||||
Using Mermaid in Hextra is as simple as writing a code block with language set `mermaid`:
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->B;
|
||||
A-->C;
|
||||
B-->D;
|
||||
C-->D;
|
||||
```
|
||||
````
|
||||
|
||||
will be rendered as:
|
||||
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->B;
|
||||
A-->C;
|
||||
B-->D;
|
||||
C-->D;
|
||||
```
|
||||
|
||||
Sequence diagram:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Alice
|
||||
participant Bob
|
||||
Alice->>John: Hello John, how are you?
|
||||
loop Healthcheck
|
||||
John->>John: Fight against hypochondria
|
||||
end
|
||||
Note right of John: Rational thoughts <br/>prevail!
|
||||
John-->>Alice: Great!
|
||||
John->>Bob: How about you?
|
||||
Bob-->>John: Jolly good!
|
||||
```
|
||||
|
||||
For more information, please refer to [Mermaid Documentation](https://mermaid-js.github.io/mermaid/#/).
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: 图表
|
||||
weight: 6
|
||||
next: /docs/guide/shortcodes
|
||||
---
|
||||
|
||||
目前，Hextra 支持通过 [Mermaid](#mermaid) 绘制图表。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Mermaid
|
||||
|
||||
[Mermaid](https://github.com/mermaid-js/mermaid#readme) 是一个基于 JavaScript 的图表绘制工具，它能将类 Markdown 的文本定义动态转换为浏览器中渲染的图表。例如，Mermaid 可以绘制流程图、时序图、饼图等多种图表。
|
||||
|
||||
在 Hextra 中使用 Mermaid 非常简单，只需编写一个语言设置为 `mermaid` 的代码块：
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->B;
|
||||
A-->C;
|
||||
B-->D;
|
||||
C-->D;
|
||||
```
|
||||
````
|
||||
|
||||
上述代码将渲染为：
|
||||
|
||||
```mermaid
|
||||
graph TD;
|
||||
A-->B;
|
||||
A-->C;
|
||||
B-->D;
|
||||
C-->D;
|
||||
```
|
||||
|
||||
时序图示例：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Alice
|
||||
participant Bob
|
||||
Alice->>John: 你好 John，最近怎么样？
|
||||
loop 健康检查
|
||||
John->>John: 与疑病症斗争
|
||||
end
|
||||
Note right of John: 理性思考 <br/>占据上风！
|
||||
John-->>Alice: 好极了！
|
||||
John->>Bob: 你怎么样？
|
||||
Bob-->>John: 非常好！
|
||||
```
|
||||
|
||||
更多信息请参阅 [Mermaid 官方文档](https://mermaid-js.github.io/mermaid/#/)。
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: "LaTeX"
|
||||
weight: 4
|
||||
---
|
||||
|
||||
عبارات ریاضی LaTeX به طور پیشفرض با استفاده از \(\KaTeX\) ([katex.org](https://katex.org/)) نمایش داده میشوند. کافی است آنها را در محتوای Markdown خود قرار دهید بدون نیاز به هیچ پیکربندی دستی.
|
||||
|
||||
## نحوه استفاده
|
||||
|
||||
میتوانید از LaTeX هم برای عبارات درون خطی و هم برای بلوکهای بزرگتر متن استفاده کنید.
|
||||
|
||||
### ریاضی درون خطی
|
||||
|
||||
برای قرار دادن یک عبارت درون یک خط متن، آن را بین `\(` و `\)` قرار دهید.
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
این \(\sigma(z) = \frac{1}{1 + e^{-z}}\) یک عبارت درون خطی است.
|
||||
```
|
||||
|
||||
این \( \sigma(z) = \frac{1}{1 + e^{-z}} \) یک عبارت درون خطی است.
|
||||
|
||||
### ریاضی نمایشی
|
||||
|
||||
برای عباراتی که میخواهید به صورت مستقل در یک پاراگراف جداگانه نمایش داده شوند، از `$$` استفاده کنید.
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
|
||||
```
|
||||
|
||||
به این صورت نمایش داده میشود:
|
||||
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
|
||||
|
||||
همچنین میتوانید از محیطهای LaTeX مانند `aligned` برای عبارات چندخطی استفاده کنید.
|
||||
|
||||
```latex {filename="page.md"}
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
```
|
||||
|
||||
به این صورت نمایش داده میشود:
|
||||
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
برای مشاهده لیست توابع پشتیبانی شده، به [توابع پشتیبانی شده توسط KaTeX](https://katex.org/docs/supported.html) مراجعه کنید.
|
||||
|
||||
### عبارات شیمیایی
|
||||
|
||||
افزونه [mhchem][mhchem] به طور پیشفرض فعال است و به شما امکان میدهد معادلات و فرمولهای شیمیایی را به راحتی نمایش دهید.
|
||||
|
||||
درون خطی: \(\ce{H2O}\) آب است.
|
||||
|
||||
پاراگراف جداگانه:
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
```
|
||||
|
||||
به این صورت نمایش داده میشود:
|
||||
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
|
||||
## پیکربندی
|
||||
|
||||
> [!IMPORTANT]
|
||||
> لطفاً افزونه [passthrough](https://gohugo.io/content-management/mathematics/) را در فایل پیکربندی Hugo فعال و پیکربندی کنید تا Hugo بتواند عبارات ریاضی LaTeX را در محتوای Markdown شما تشخیص دهد.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ["$$", "$$"]]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
### موتور ریاضی
|
||||
|
||||
[KaTeX][katex] موتور پیشفرضی است که برای نمایش عبارات ریاضی LaTeX در فرآیند ساخت توسط [Hugo][hugo-transform-tomath] استفاده میشود.
|
||||
|
||||
پیشفرض KaTeX است، اما در صورت نیاز به ویژگیهایی که فقط در [MathJax][mathjax] موجود است، میتوانید به MathJax سوئیچ کنید.
|
||||
|
||||
#### KaTeX
|
||||
|
||||
پیکربندی پیشفرض نیاز به هیچ تنظیمی ندارد. Hugo فایل CSS مربوط به KaTeX را از CDN دریافت میکند.
|
||||
اگر نیاز به استفاده از نسخه خاصی از KaTeX یا استفاده از فایلهای محلی دارید، میتوانید این کار را در فایل `hugo.yaml` انجام دهید.
|
||||
|
||||
##### تغییر آدرس پایه CDN
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
base: "https://cdn.jsdelivr.net/npm/katex@0.16.22/dist"
|
||||
```
|
||||
|
||||
##### استفاده از فایلهای محلی
|
||||
|
||||
همچنین میتوانید فایل css را در پوشه `assets` قرار دهید و فایلهای فونت مورد نیاز KaTeX را منتشر کنید.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
css: "css/katex.min.css"
|
||||
assets:
|
||||
- "fonts/KaTeX_Main-Regular.woff2"
|
||||
# سایر فایلهای فونت را اینجا اضافه کنید
|
||||
```
|
||||
|
||||
این تنظیمات باعث میشود فایل CSS مربوط به KaTeX از `assets/css/katex.min.css` بارگیری شود به جای دانلود از CDN.
|
||||
|
||||
#### MathJax
|
||||
|
||||
به عنوان جایگزین، میتوانید از [MathJax][mathjax] برای نمایش عبارات ریاضی استفاده کنید:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: mathjax
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> میتوانید MathJax را بیشتر سفارشی کنید (مثلاً تنظیمات لودر را تغییر دهید یا CDN/منبع را عوض کنید) با بازنویسی قالب در `layouts/_partials/scripts/mathjax.html` در پروژه خود. Hugo به جای نسخه پیشفرض قالب، از نسخه شما استفاده خواهد کرد.
|
||||
|
||||
[katex]: https://katex.org/
|
||||
[mathjax]: https://www.mathjax.org/
|
||||
[mhchem]: https://mhchem.github.io/MathJax-mhchem/
|
||||
[hugo-transform-tomath]: https://gohugo.io/functions/transform/tomath/
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: "LaTeX"
|
||||
weight: 4
|
||||
---
|
||||
|
||||
LaTeX の数式表現はデフォルトで \(\KaTeX\) ([katex.org](https://katex.org/)) を使用してレンダリングされます。特別な設定なしで、Markdown コンテンツ内に直接記述できます。
|
||||
|
||||
## 使用方法
|
||||
|
||||
LaTeX はインライン式とブロック式の両方で使用できます。
|
||||
|
||||
### インライン数式
|
||||
|
||||
文中に数式を含めるには、`\(` と `\)` で囲みます。
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
この \(\sigma(z) = \frac{1}{1 + e^{-z}}\) はインライン式です。
|
||||
```
|
||||
|
||||
この \( \sigma(z) = \frac{1}{1 + e^{-z}} \) はインライン式です。
|
||||
|
||||
### ディスプレイ数式
|
||||
|
||||
独立した段落として表示する数式には、`$$` で囲みます。
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
|
||||
```
|
||||
|
||||
次のようにレンダリングされます:
|
||||
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
|
||||
|
||||
複数行の数式には `aligned` などの LaTeX 環境も使用できます。
|
||||
|
||||
```latex {filename="page.md"}
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
```
|
||||
|
||||
次のようにレンダリングされます:
|
||||
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
サポートされている関数の一覧は [KaTeX サポート関数](https://katex.org/docs/supported.html) を参照してください。
|
||||
|
||||
### 化学式
|
||||
|
||||
[mhchem][mhchem] 拡張がデフォルトで有効になっており、化学式を簡単に記述できます。
|
||||
|
||||
インライン: \(\ce{H2O}\) は水です。
|
||||
|
||||
独立段落:
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
```
|
||||
|
||||
次のようにレンダリングされます:
|
||||
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
|
||||
## 設定
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Hugo が Markdown コンテンツ内の LaTeX 数式を認識できるよう、[パススルー拡張](https://gohugo.io/content-management/mathematics/) を Hugo 設定ファイルで有効にしてください。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ["$$", "$$"]]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
### 数式エンジン
|
||||
|
||||
[KaTeX][katex] はビルド時に LaTeX 数式をレンダリングするデフォルトエンジンで、[Hugo][hugo-transform-tomath] でサポートされています。
|
||||
|
||||
デフォルトは KaTeX ですが、MathJax のみの機能が必要な場合は [MathJax][mathjax] に切り替えられます。
|
||||
|
||||
#### KaTeX
|
||||
|
||||
デフォルト設定では追加の設定は不要です。Hugo は KaTeX の CSS を CDN から取得します。
|
||||
特定のバージョンを固定したりローカルアセットを使用する場合は、`hugo.yaml` ファイルで設定できます。
|
||||
|
||||
##### CDN ベース URL の上書き
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
base: "https://cdn.jsdelivr.net/npm/katex@0.16.22/dist"
|
||||
```
|
||||
|
||||
##### ローカルアセットの使用
|
||||
|
||||
CSS ファイルを `assets` ディレクトリに配置し、KaTeX に必要なフォントファイルを追加できます。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
css: "css/katex.min.css"
|
||||
assets:
|
||||
- "fonts/KaTeX_Main-Regular.woff2"
|
||||
# 他のフォントファイルをここに追加
|
||||
```
|
||||
|
||||
これにより、CDN ではなく `assets/css/katex.min.css` から KaTeX CSS ファイルが読み込まれます。
|
||||
|
||||
#### MathJax
|
||||
|
||||
代わりに [MathJax][mathjax] を使用して数式をレンダリングすることもできます:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: mathjax
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> MathJax をさらにカスタマイズするには（ローダーオプションの調整や CDN/ソースの変更など）、プロジェクトの `layouts/_partials/scripts/mathjax.html` でテンプレートを上書きしてください。Hugo はテーマのデフォルトではなく、あなたのバージョンを使用します。
|
||||
|
||||
[katex]: https://katex.org/
|
||||
[mathjax]: https://www.mathjax.org/
|
||||
[mhchem]: https://mhchem.github.io/MathJax-mhchem/
|
||||
[hugo-transform-tomath]: https://gohugo.io/functions/transform/tomath/
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: "LaTeX"
|
||||
weight: 4
|
||||
---
|
||||
|
||||
LaTeX math expressions are rendered using \(\KaTeX\) ([katex.org](https://katex.org/)) by default. Simply start including them in your Markdown content without any manual configurations.
|
||||
|
||||
## Usage
|
||||
|
||||
You can use LaTeX for both inline expressions and for larger blocks of text.
|
||||
|
||||
### Inline Math
|
||||
|
||||
To include an expression within a line of text, wrap it in `\(` and `\)` delimiters.
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
This \(\sigma(z) = \frac{1}{1 + e^{-z}}\) is an inline expression.
|
||||
```
|
||||
|
||||
This \( \sigma(z) = \frac{1}{1 + e^{-z}} \) is an inline expression.
|
||||
|
||||
### Display Math
|
||||
|
||||
For expressions that you want to stand on their own in a separate paragraph, use `$$` delimiters.
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
|
||||
```
|
||||
|
||||
will be rendered as:
|
||||
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
|
||||
|
||||
You can also use LaTeX environments like `aligned` for multi-line expressions.
|
||||
|
||||
```latex {filename="page.md"}
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
```
|
||||
|
||||
will be rendered as:
|
||||
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
For a list of supported functions, see [KaTeX supported functions](https://katex.org/docs/supported.html).
|
||||
|
||||
### Chemistry Expressions
|
||||
|
||||
The [mhchem][mhchem] extension is enabled by default, allowing you to easily render chemistry equations and formulas.
|
||||
|
||||
Inline: \(\ce{H2O}\) is water.
|
||||
|
||||
Separate paragraph:
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
```
|
||||
|
||||
will be rendered as:
|
||||
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
|
||||
## Configuration
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Please enable and configure the [passthrough extension](https://gohugo.io/content-management/mathematics/) in the Hugo configuration file, so that Hugo can detect LaTeX math expressions in your Markdown content.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ["$$", "$$"]]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
### Math Engine
|
||||
|
||||
[KaTeX][katex] is the default engine used to render LaTeX math expressions during the build process supported by [Hugo][hugo-transform-tomath].
|
||||
|
||||
The default is KaTeX, but you can also switch to [MathJax][mathjax] if you need features only available in MathJax.
|
||||
|
||||
#### KaTeX
|
||||
|
||||
The default setup requires no configuration. Hugo fetches the KaTeX CSS from the CDN.
|
||||
If you need to pin a specific version of KaTeX or use local assets, you can do so in your `hugo.yaml` file.
|
||||
|
||||
##### Override CDN base URL
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
base: "https://cdn.jsdelivr.net/npm/katex@0.16.22/dist"
|
||||
```
|
||||
|
||||
##### Use local assets
|
||||
|
||||
You can also place the css file under `assets` and publish additional font files required by KaTeX.
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
css: "css/katex.min.css"
|
||||
assets:
|
||||
- "fonts/KaTeX_Main-Regular.woff2"
|
||||
# Add other font files here
|
||||
```
|
||||
|
||||
It will load the KaTeX CSS file from `assets/css/katex.min.css` instead of downloading from CDN.
|
||||
|
||||
#### MathJax
|
||||
|
||||
Alternatively, you can use [MathJax][mathjax] to render math expressions:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: mathjax
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> You can further customize MathJax (for example, adjust loader options, or change the CDN/source) by overriding the template at `layouts/_partials/scripts/mathjax.html` in your project. Hugo will use your version instead of the theme's default.
|
||||
|
||||
[katex]: https://katex.org/
|
||||
[mathjax]: https://www.mathjax.org/
|
||||
[mhchem]: https://mhchem.github.io/MathJax-mhchem/
|
||||
[hugo-transform-tomath]: https://gohugo.io/functions/transform/tomath/
|
||||
@@ -0,0 +1,145 @@
|
||||
---
|
||||
title: "数学公式"
|
||||
weight: 4
|
||||
---
|
||||
|
||||
LaTeX 数学表达式默认使用 \(\KaTeX\) 渲染。直接在 Markdown 内容中使用即可，无需手动配置。
|
||||
|
||||
## 使用方法
|
||||
|
||||
LaTeX 既可用于行内表达式，也可用于大段文本。
|
||||
|
||||
### 行内公式
|
||||
|
||||
要在文本行内插入表达式，用 `\(` 和 `\)` 包裹。
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
这个 \(\sigma(z) = \frac{1}{1 + e^{-z}}\) 是行内表达式。
|
||||
```
|
||||
|
||||
这个 \( \sigma(z) = \frac{1}{1 + e^{-z}} \) 是行内表达式。
|
||||
|
||||
### 独立公式
|
||||
|
||||
对于需要单独成段的表达式，使用 `$$` 包裹。
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
|
||||
```
|
||||
|
||||
将渲染为：
|
||||
|
||||
$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
|
||||
|
||||
还可以使用 LaTeX 环境如 `aligned` 处理多行公式。
|
||||
|
||||
```latex {filename="page.md"}
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
```
|
||||
|
||||
将渲染为：
|
||||
|
||||
$$
|
||||
\begin{aligned}
|
||||
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
|
||||
\nabla \cdot \mathbf{B} &= 0 \\
|
||||
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
|
||||
\nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
支持的函数列表见 [KaTeX 支持函数](https://katex.org/docs/supported.html)。
|
||||
|
||||
### 化学表达式
|
||||
|
||||
默认启用了 [mhchem][mhchem] 扩展，可轻松渲染化学方程式和分子式。
|
||||
|
||||
行内示例：\(\ce{H2O}\) 是水。
|
||||
|
||||
独立段落：
|
||||
|
||||
```markdown {filename="page.md"}
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
```
|
||||
|
||||
将渲染为：
|
||||
|
||||
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
|
||||
|
||||
## 配置
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 请在 Hugo 配置文件中启用并配置 [passthrough 扩展](https://gohugo.io/content-management/mathematics/)，以便 Hugo 能识别 Markdown 中的 LaTeX 数学表达式。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
extensions:
|
||||
passthrough:
|
||||
delimiters:
|
||||
block: [['\[', '\]'], ["$$", "$$"]]
|
||||
inline: [['\(', '\)']]
|
||||
enable: true
|
||||
```
|
||||
|
||||
### 数学引擎
|
||||
|
||||
构建过程中默认使用 [KaTeX][katex] 渲染 LaTeX 数学表达式，由 [Hugo][hugo-transform-tomath] 支持。
|
||||
|
||||
默认引擎是 KaTeX，但也可切换至 [MathJax][mathjax] 以使用其特有功能。
|
||||
|
||||
#### KaTeX
|
||||
|
||||
默认设置无需配置。Hugo 会从 CDN 获取 KaTeX CSS。如需指定 KaTeX 版本或使用本地资源，可在 `hugo.yaml` 中配置。
|
||||
|
||||
##### 覆盖 CDN 基础 URL
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
base: "https://cdn.jsdelivr.net/npm/katex@0.16.22/dist"
|
||||
```
|
||||
|
||||
##### 使用本地资源
|
||||
|
||||
可将 CSS 文件置于 `assets` 目录，并发布 KaTeX 所需的字体文件。
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: katex
|
||||
katex:
|
||||
css: "css/katex.min.css"
|
||||
assets:
|
||||
- "fonts/KaTeX_Main-Regular.woff2"
|
||||
# 在此添加其他字体文件
|
||||
```
|
||||
|
||||
此时将从 `assets/css/katex.min.css` 加载 KaTeX CSS 文件，而非从 CDN 下载。
|
||||
|
||||
#### MathJax
|
||||
|
||||
也可使用 [MathJax][mathjax] 渲染数学表达式：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
params:
|
||||
math:
|
||||
engine: mathjax
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> 可通过在项目中覆盖 `layouts/_partials/scripts/mathjax.html` 模板进一步定制 MathJax（如调整加载器选项或更改 CDN/源）。Hugo 将优先使用你的版本而非主题默认配置。
|
||||
|
||||
[katex]: https://katex.org/
|
||||
[mathjax]: https://www.mathjax.org/
|
||||
[mhchem]: https://mhchem.github.io/MathJax-mhchem/
|
||||
[hugo-transform-tomath]: https://gohugo.io/functions/transform/tomath/
|
||||
@@ -0,0 +1,210 @@
|
||||
---
|
||||
title: Markdown
|
||||
weight: 2
|
||||
---
|
||||
|
||||
Hugo از [Markdown](https://en.wikipedia.org/wiki/Markdown) برای قالببندی متن، ایجاد لیستها و موارد دیگر پشتیبانی میکند. این صفحه برخی از رایجترین نمونههای نحوه استفاده از Markdown را به شما نشان میدهد.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## نمونههای Markdown
|
||||
|
||||
### استایلدهی متن
|
||||
|
||||
| استایل | نحو | مثال | خروجی |
|
||||
| :------------ | :----------------------- | :-------------------------------------- | :------------------------------------ |
|
||||
| پررنگ | `**متن پررنگ**` | `**متن پررنگ**` | **متن پررنگ** |
|
||||
| مورب | `*متن مورب*` | `*متن مورب*` | _متن مورب_ |
|
||||
| خطخورده | `~~متن خطخورده~~` | `~~متن خطخورده~~` | ~~متن خطخورده~~ |
|
||||
| زیرنویس | `<sub></sub>` | `این یک <sub>زیرنویس</sub> است` | این یک <sub>زیرنویس</sub> است |
|
||||
| بالانویس | `<sup></sup>` | `این یک <sup>بالانویس</sup> است` | این یک <sup>بالانویس</sup> است |
|
||||
|
||||
### نقلقولها
|
||||
|
||||
نقلقول با ذکر منبع
|
||||
|
||||
> با اشتراکگذاری حافظه ارتباط برقرار نکنید، بلکه با ارتباط، حافظه را اشتراک بگذارید.<br>
|
||||
> — <cite>Rob Pike[^1]</cite>
|
||||
|
||||
[^1]: این نقلقول از [سخنرانی](https://www.youtube.com/watch?v=PAAkCSZUG1c) Rob Pike در Gopherfest در ۱۸ نوامبر ۲۰۱۵ گرفته شده است.
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
> با اشتراکگذاری حافظه ارتباط برقرار نکنید، بلکه با ارتباط، حافظه را اشتراک بگذارید.<br>
|
||||
> — <cite>Rob Pike[^1]</cite>
|
||||
|
||||
[^1]: این نقلقول از [سخنرانی](https://www.youtube.com/watch?v=PAAkCSZUG1c) Rob Pike در Gopherfest در ۱۸ نوامبر ۲۰۱۵ گرفته شده است.
|
||||
```
|
||||
|
||||
### هشدارها
|
||||
|
||||
{{< new-feature version="v0.9.0" >}}
|
||||
|
||||
هشدارها یک افزونه Markdown بر اساس نحو نقلقول هستند که میتوانید برای تأکید بر اطلاعات مهم از آنها استفاده کنید.
|
||||
[هشدارهای به سبک GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) پشتیبانی میشوند.
|
||||
لطفاً مطمئن شوید که از آخرین نسخه Hextra و [Hugo v0.146.0](https://github.com/gohugoio/hugo/releases/tag/v0.146.0) یا بالاتر استفاده میکنید.
|
||||
|
||||
> [!NOTE]
|
||||
> اطلاعات مفیدی که کاربران باید بدانند، حتی هنگام مرور سریع محتوا.
|
||||
|
||||
> [!TIP]
|
||||
> توصیههای مفید برای انجام بهتر یا آسانتر کارها.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> اطلاعات کلیدی که کاربران برای رسیدن به هدف خود نیاز دارند.
|
||||
|
||||
> [!WARNING]
|
||||
> اطلاعات فوری که نیاز به توجه فوری کاربر دارد تا از مشکلات جلوگیری شود.
|
||||
|
||||
> [!CAUTION]
|
||||
> هشدار درباره خطرات یا نتایج منفی برخی اقدامات.
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
> [!NOTE]
|
||||
> اطلاعات مفیدی که کاربران باید بدانند، حتی هنگام مرور سریع محتوا.
|
||||
|
||||
> [!TIP]
|
||||
> توصیههای مفید برای انجام بهتر یا آسانتر کارها.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> اطلاعات کلیدی که کاربران برای رسیدن به هدف خود نیاز دارند.
|
||||
|
||||
> [!WARNING]
|
||||
> اطلاعات فوری که نیاز به توجه فوری کاربر دارد تا از مشکلات جلوگیری شود.
|
||||
|
||||
> [!CAUTION]
|
||||
> هشدار درباره خطرات یا نتایج منفی برخی اقدامات.
|
||||
```
|
||||
|
||||
### جداول
|
||||
|
||||
جداول بخشی از مشخصه اصلی Markdown نیستند، اما Hugo به صورت پیشفرض از آنها پشتیبانی میکند.
|
||||
|
||||
| نام | سن |
|
||||
| :---- | :-- |
|
||||
| باب | ۲۷ |
|
||||
| آلیس | ۲۳ |
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
| نام | سن |
|
||||
| :---- | :-- |
|
||||
| باب | ۲۷ |
|
||||
| آلیس | ۲۳ |
|
||||
```
|
||||
|
||||
#### Markdown درونخطی در جداول
|
||||
|
||||
| مورب | پررنگ | کد |
|
||||
| :-------- | :------- | :----- |
|
||||
| _مورب_ | **پررنگ** | `کد` |
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
| مورب | پررنگ | کد |
|
||||
| :-------- | :------- | :----- |
|
||||
| _مورب_ | **پررنگ** | `کد` |
|
||||
```
|
||||
|
||||
### بلوکهای کد
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="../../guide/syntax-highlighting" title="رنگآمیزی نحوی" icon="sparkles" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
### لیستها
|
||||
|
||||
#### لیست مرتب
|
||||
|
||||
۱. مورد اول
|
||||
۲. مورد دوم
|
||||
۳. مورد سوم
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
۱. مورد اول
|
||||
۲. مورد دوم
|
||||
۳. مورد سوم
|
||||
```
|
||||
|
||||
#### لیست نامرتب
|
||||
|
||||
* مورد لیست
|
||||
* مورد دیگر
|
||||
* و یک مورد دیگر
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
* مورد لیست
|
||||
* مورد دیگر
|
||||
* و یک مورد دیگر
|
||||
```
|
||||
|
||||
#### لیست تو در تو
|
||||
|
||||
- میوه
|
||||
- سیب
|
||||
- پرتقال
|
||||
- موز
|
||||
- لبنیات
|
||||
- شیر
|
||||
- پنیر
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
- میوه
|
||||
- سیب
|
||||
- پرتقال
|
||||
- موز
|
||||
- لبنیات
|
||||
- شیر
|
||||
- پنیر
|
||||
```
|
||||
|
||||
#### لیست وظایف
|
||||
|
||||
- [x] نوشتن مستندات
|
||||
- [ ] بازبینی کد
|
||||
- [ ] استقرار تغییرات
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
- [x] نوشتن مستندات
|
||||
- [ ] بازبینی کد
|
||||
- [ ] استقرار تغییرات
|
||||
```
|
||||
|
||||
### تصاویر
|
||||
|
||||
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
|
||||
```
|
||||
|
||||
با عنوان:
|
||||
|
||||
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
|
||||
```
|
||||
|
||||
برای عملکرد پیشرفتهتر، از [shortcode Figure](https://gohugo.io/shortcodes/figure/) داخلی Hugo استفاده کنید.
|
||||
|
||||
## پیکربندی
|
||||
|
||||
Hugo از [Goldmark](https://github.com/yuin/goldmark) برای تجزیه Markdown استفاده میکند.
|
||||
رندر Markdown را میتوان در `hugo.yaml` تحت `markup.goldmark` پیکربندی کرد.
|
||||
در زیر پیکربندی پیشفرض Hextra آمده است:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
renderer:
|
||||
unsafe: true
|
||||
highlight:
|
||||
noClasses: false
|
||||
```
|
||||
|
||||
برای گزینههای پیکربندی بیشتر، مستندات Hugo در مورد [پیکربندی Markup](https://gohugo.io/getting-started/configuration-markup/) را ببینید.
|
||||
|
||||
## منابع یادگیری
|
||||
|
||||
- [راهنمای Markdown](https://www.markdownguide.org/)
|
||||
- [راهنمای سریع Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
|
||||
- [آموزش Markdown](https://www.markdowntutorial.com/)
|
||||
- [مرجع Markdown](https://commonmark.org/help/)
|
||||
@@ -0,0 +1,210 @@
|
||||
---
|
||||
title: Markdown
|
||||
weight: 2
|
||||
---
|
||||
|
||||
Hugo はテキストの書式設定やリスト作成などに [Markdown](https://en.wikipedia.org/wiki/Markdown) 構文をサポートしています。このページでは、最も一般的な Markdown 構文の例を紹介します。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Markdown の例
|
||||
|
||||
### テキストのスタイリング
|
||||
|
||||
| スタイル | 構文 | 例 | 出力 |
|
||||
| :------------ | :----------------------- | :------------------------------------ | :------------------------------------ |
|
||||
| 太字 | `**太字テキスト**` | `**太字テキスト**` | **太字テキスト** |
|
||||
| 斜体 | `*斜体テキスト*` | `*斜体テキスト*` | _斜体テキスト_ |
|
||||
| 打ち消し線 | `~~打ち消し線テキスト~~` | `~~打ち消し線テキスト~~` | ~~打ち消し線テキスト~~ |
|
||||
| 下付き文字 | `<sub></sub>` | `これは<sub>下付き文字</sub>です` | これは<sub>下付き文字</sub>です |
|
||||
| 上付き文字 | `<sup></sup>` | `これは<sup>上付き文字</sup>です` | これは<sup>上付き文字</sup>です |
|
||||
|
||||
### ブロッククォート
|
||||
|
||||
引用元付きのブロッククォート
|
||||
|
||||
> メモリを共有することで通信するのではなく、通信することでメモリを共有しなさい。<br>
|
||||
> — <cite>Rob Pike[^1]</cite>
|
||||
|
||||
[^1]: 上記の引用は、2015年11月18日のGopherfestでのRob Pikeの[講演](https://www.youtube.com/watch?v=PAAkCSZUG1c)から抜粋したものです。
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
> メモリを共有することで通信するのではなく、通信することでメモリを共有しなさい。<br>
|
||||
> — <cite>Rob Pike[^1]</cite>
|
||||
|
||||
[^1]: 上記の引用は、2015年11月18日のGopherfestでのRob Pikeの[講演](https://www.youtube.com/watch?v=PAAkCSZUG1c)から抜粋したものです。
|
||||
```
|
||||
|
||||
### アラート
|
||||
|
||||
{{< new-feature version="v0.9.0" >}}
|
||||
|
||||
アラートは、重要な情報を強調するために使用できるブロッククォート構文を基にしたMarkdown拡張機能です。
|
||||
[GitHubスタイルのアラート](https://docs.github.com/ja/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)がサポートされています。
|
||||
最新バージョンのHextraと[Hugo v0.146.0](https://github.com/gohugoio/hugo/releases/tag/v0.146.0)以降を使用していることを確認してください。
|
||||
|
||||
> [!NOTE]
|
||||
> コンテンツをざっと見る際にもユーザーが知っておくべき有用な情報。
|
||||
|
||||
> [!TIP]
|
||||
> 物事をより良く、または簡単に行うための役立つアドバイス。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> ユーザーが目標を達成するために知っておく必要がある重要な情報。
|
||||
|
||||
> [!WARNING]
|
||||
> 問題を回避するためにユーザーがすぐに対処する必要がある緊急情報。
|
||||
|
||||
> [!CAUTION]
|
||||
> 特定のアクションによるリスクやネガティブな結果についての警告。
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
> [!NOTE]
|
||||
> コンテンツをざっと見る際にもユーザーが知っておくべき有用な情報。
|
||||
|
||||
> [!TIP]
|
||||
> 物事をより良く、または簡単に行うための役立つアドバイス。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> ユーザーが目標を達成するために知っておく必要がある重要な情報。
|
||||
|
||||
> [!WARNING]
|
||||
> 問題を回避するためにユーザーがすぐに対処する必要がある緊急情報。
|
||||
|
||||
> [!CAUTION]
|
||||
> 特定のアクションによるリスクやネガティブな結果についての警告。
|
||||
```
|
||||
|
||||
### テーブル
|
||||
|
||||
テーブルはコアMarkdown仕様の一部ではありませんが、Hugoはデフォルトでサポートしています。
|
||||
|
||||
| 名前 | 年齢 |
|
||||
| :---- | :-- |
|
||||
| Bob | 27 |
|
||||
| Alice | 23 |
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
| 名前 | 年齢 |
|
||||
| :---- | :-- |
|
||||
| Bob | 27 |
|
||||
| Alice | 23 |
|
||||
```
|
||||
|
||||
#### テーブル内のインラインMarkdown
|
||||
|
||||
| 斜体 | 太字 | コード |
|
||||
| :-------- | :-------- | :-------- |
|
||||
| _斜体_ | **太字** | `コード` |
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
| 斜体 | 太字 | コード |
|
||||
| :-------- | :-------- | :-------- |
|
||||
| _斜体_ | **太字** | `コード` |
|
||||
```
|
||||
|
||||
### コードブロック
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="../../guide/syntax-highlighting" title="シンタックスハイライト" icon="sparkles" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
### リスト
|
||||
|
||||
#### 順序付きリスト
|
||||
|
||||
1. 最初の項目
|
||||
2. 2番目の項目
|
||||
3. 3番目の項目
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
1. 最初の項目
|
||||
2. 2番目の項目
|
||||
3. 3番目の項目
|
||||
```
|
||||
|
||||
#### 順序なしリスト
|
||||
|
||||
* リスト項目
|
||||
* 別の項目
|
||||
* さらに別の項目
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
* リスト項目
|
||||
* 別の項目
|
||||
* さらに別の項目
|
||||
```
|
||||
|
||||
#### ネストされたリスト
|
||||
|
||||
- 果物
|
||||
- りんご
|
||||
- オレンジ
|
||||
- バナナ
|
||||
- 乳製品
|
||||
- 牛乳
|
||||
- チーズ
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
- 果物
|
||||
- りんご
|
||||
- オレンジ
|
||||
- バナナ
|
||||
- 乳製品
|
||||
- 牛乳
|
||||
- チーズ
|
||||
```
|
||||
|
||||
#### タスクリスト
|
||||
|
||||
- [x] ドキュメント作成
|
||||
- [ ] コードレビュー
|
||||
- [ ] 変更のデプロイ
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
- [x] ドキュメント作成
|
||||
- [ ] コードレビュー
|
||||
- [ ] 変更のデプロイ
|
||||
```
|
||||
|
||||
### 画像
|
||||
|
||||
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
|
||||
```
|
||||
|
||||
キャプション付き:
|
||||
|
||||
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
|
||||
```
|
||||
|
||||
より高度な機能が必要な場合は、Hugoの組み込み[Figureショートコード](https://gohugo.io/shortcodes/figure/)を使用してください。
|
||||
|
||||
## 設定
|
||||
|
||||
HugoはMarkdown解析に[Goldmark](https://github.com/yuin/goldmark)を使用しています。
|
||||
Markdownのレンダリング設定は`hugo.yaml`の`markup.goldmark`で行えます。
|
||||
以下はHextraのデフォルト設定です:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
renderer:
|
||||
unsafe: true
|
||||
highlight:
|
||||
noClasses: false
|
||||
```
|
||||
|
||||
その他の設定オプションについては、Hugoドキュメントの[マークアップ設定](https://gohugo.io/getting-started/configuration-markup/)を参照してください。
|
||||
|
||||
## 学習リソース
|
||||
|
||||
- [Markdownガイド](https://www.markdownguide.org/)
|
||||
- [Markdownチートシート](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
|
||||
- [Markdownチュートリアル](https://www.markdowntutorial.com/)
|
||||
- [Markdownリファレンス](https://commonmark.org/help/)
|
||||
@@ -0,0 +1,210 @@
|
||||
---
|
||||
title: Markdown
|
||||
weight: 2
|
||||
---
|
||||
|
||||
Hugo supports [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax for formatting text, creating lists, and more. This page will show you some of the most common Markdown syntax examples.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Markdown Examples
|
||||
|
||||
### Styling Text
|
||||
|
||||
| Style | Syntax | Example | Output |
|
||||
| :------------ | :----------------------- | :-------------------------------------- | :------------------------------------ |
|
||||
| Bold | `**bold text**` | `**bold text**` | **bold text** |
|
||||
| Italic | `*italicized text*` | `*italicized text*` | _italicized text_ |
|
||||
| Strikethrough | `~~strikethrough text~~` | `~~strikethrough text~~` | ~~strikethrough text~~ |
|
||||
| Subscript | `<sub></sub>` | `This is a <sub>subscript</sub> text` | This is a <sub>subscript</sub> text |
|
||||
| Superscript | `<sup></sup>` | `This is a <sup>superscript</sup> text` | This is a <sup>superscript</sup> text |
|
||||
|
||||
### Blockquotes
|
||||
|
||||
Blockquote with attribution
|
||||
|
||||
> Don't communicate by sharing memory, share memory by communicating.<br>
|
||||
> — <cite>Rob Pike[^1]</cite>
|
||||
|
||||
[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
> Don't communicate by sharing memory, share memory by communicating.<br>
|
||||
> — <cite>Rob Pike[^1]</cite>
|
||||
|
||||
[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.
|
||||
```
|
||||
|
||||
### Alerts
|
||||
|
||||
{{< new-feature version="v0.9.0" >}}
|
||||
|
||||
Alerts are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information.
|
||||
[GitHub-style alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) are supported.
|
||||
Please make sure you are using the latest version of Hextra and [Hugo v0.146.0](https://github.com/gohugoio/hugo/releases/tag/v0.146.0) or later.
|
||||
|
||||
> [!NOTE]
|
||||
> Useful information that users should know, even when skimming content.
|
||||
|
||||
> [!TIP]
|
||||
> Helpful advice for doing things better or more easily.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Key information users need to know to achieve their goal.
|
||||
|
||||
> [!WARNING]
|
||||
> Urgent info that needs immediate user attention to avoid problems.
|
||||
|
||||
> [!CAUTION]
|
||||
> Advises about risks or negative outcomes of certain actions.
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
> [!NOTE]
|
||||
> Useful information that users should know, even when skimming content.
|
||||
|
||||
> [!TIP]
|
||||
> Helpful advice for doing things better or more easily.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Key information users need to know to achieve their goal.
|
||||
|
||||
> [!WARNING]
|
||||
> Urgent info that needs immediate user attention to avoid problems.
|
||||
|
||||
> [!CAUTION]
|
||||
> Advises about risks or negative outcomes of certain actions.
|
||||
```
|
||||
|
||||
### Tables
|
||||
|
||||
Tables aren't part of the core Markdown spec, but Hugo supports them out-of-the-box.
|
||||
|
||||
| Name | Age |
|
||||
| :---- | :-- |
|
||||
| Bob | 27 |
|
||||
| Alice | 23 |
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
| Name | Age |
|
||||
| :---- | :-- |
|
||||
| Bob | 27 |
|
||||
| Alice | 23 |
|
||||
```
|
||||
|
||||
#### Inline Markdown within tables
|
||||
|
||||
| Italics | Bold | Code |
|
||||
| :-------- | :------- | :----- |
|
||||
| _italics_ | **bold** | `code` |
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
| Italics | Bold | Code |
|
||||
| :-------- | :------- | :----- |
|
||||
| _italics_ | **bold** | `code` |
|
||||
```
|
||||
|
||||
### Code Blocks
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="../../guide/syntax-highlighting" title="Syntax Highlighting" icon="sparkles" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
### Lists
|
||||
|
||||
#### Ordered List
|
||||
|
||||
1. First item
|
||||
2. Second item
|
||||
3. Third item
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
1. First item
|
||||
2. Second item
|
||||
3. Third item
|
||||
```
|
||||
|
||||
#### Unordered List
|
||||
|
||||
* List item
|
||||
* Another item
|
||||
* And another item
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
* List item
|
||||
* Another item
|
||||
* And another item
|
||||
```
|
||||
|
||||
#### Nested list
|
||||
|
||||
- Fruit
|
||||
- Apple
|
||||
- Orange
|
||||
- Banana
|
||||
- Dairy
|
||||
- Milk
|
||||
- Cheese
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
- Fruit
|
||||
- Apple
|
||||
- Orange
|
||||
- Banana
|
||||
- Dairy
|
||||
- Milk
|
||||
- Cheese
|
||||
```
|
||||
|
||||
#### Task list
|
||||
|
||||
- [x] Write documentation
|
||||
- [ ] Review code
|
||||
- [ ] Deploy changes
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
- [x] Write documentation
|
||||
- [ ] Review code
|
||||
- [ ] Deploy changes
|
||||
```
|
||||
|
||||
### Images
|
||||
|
||||
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
|
||||
```
|
||||
|
||||
With caption:
|
||||
|
||||
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
|
||||
```
|
||||
|
||||
For more advanced functionality, use Hugo's built-in [Figure shortcode](https://gohugo.io/shortcodes/figure/).
|
||||
|
||||
## Configuration
|
||||
|
||||
Hugo uses [Goldmark](https://github.com/yuin/goldmark) for Markdown parsing.
|
||||
Markdown rendering can be configured in `hugo.yaml` under `markup.goldmark`.
|
||||
Below is the default configuration for Hextra:
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
renderer:
|
||||
unsafe: true
|
||||
highlight:
|
||||
noClasses: false
|
||||
```
|
||||
|
||||
For more configuration options, see Hugo documentation on [Configure Markup](https://gohugo.io/getting-started/configuration-markup/).
|
||||
|
||||
## Learning Resources
|
||||
|
||||
- [Markdown Guide](https://www.markdownguide.org/)
|
||||
- [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
|
||||
- [Markdown Tutorial](https://www.markdowntutorial.com/)
|
||||
- [Markdown Reference](https://commonmark.org/help/)
|
||||
@@ -0,0 +1,210 @@
|
||||
---
|
||||
title: Markdown
|
||||
weight: 2
|
||||
---
|
||||
|
||||
Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来格式化文本、创建列表等。本页将展示一些最常用的 Markdown 语法示例。
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Markdown 示例
|
||||
|
||||
### 文本样式
|
||||
|
||||
| 样式 | 语法 | 示例 | 输出 |
|
||||
| :----- | :--------------- | :------------------------ | :---------------------- |
|
||||
| 粗体 | `**粗体文本**` | `**粗体文本**` | **粗体文本** |
|
||||
| 斜体 | `*斜体文本*` | `*斜体文本*` | _斜体文本_ |
|
||||
| 删除线 | `~~删除线文本~~` | `~~删除线文本~~` | ~~删除线文本~~ |
|
||||
| 下标 | `<sub></sub>` | `这是<sub>下标</sub>文本` | 这是<sub>下标</sub>文本 |
|
||||
| 上标 | `<sup></sup>` | `这是<sup>上标</sup>文本` | 这是<sup>上标</sup>文本 |
|
||||
|
||||
### 引用块
|
||||
|
||||
带出处的引用
|
||||
|
||||
> 不要通过共享内存来通信，而要通过通信来共享内存。<br>
|
||||
> — <cite>Rob Pike[^1]</cite>
|
||||
|
||||
[^1]: 上述引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
> 不要通过共享内存来通信，而要通过通信来共享内存。<br>
|
||||
> — <cite>Rob Pike[^1]</cite>
|
||||
|
||||
[^1]: 上述引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。
|
||||
```
|
||||
|
||||
### 提示框
|
||||
|
||||
{{< new-feature version="v0.9.0" >}}
|
||||
|
||||
提示框是基于引用块语法的 Markdown 扩展，可用于强调关键信息。
|
||||
支持 [GitHub 风格的提示框](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)。
|
||||
请确保您使用的是最新版本的 Hextra 和 [Hugo v0.146.0](https://github.com/gohugoio/hugo/releases/tag/v0.146.0) 或更高版本。
|
||||
|
||||
> [!NOTE]
|
||||
> 即使用户只是浏览内容，也应该知道的有用信息。
|
||||
|
||||
> [!TIP]
|
||||
> 帮助用户更高效或更轻松完成任务的建议。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 用户需要了解的关键信息，以实现他们的目标。
|
||||
|
||||
> [!WARNING]
|
||||
> 需要用户立即关注的紧急信息，以避免出现问题。
|
||||
|
||||
> [!CAUTION]
|
||||
> 关于某些操作可能带来风险或负面结果的警告。
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
> [!NOTE]
|
||||
> 即使用户只是浏览内容，也应该知道的有用信息。
|
||||
|
||||
> [!TIP]
|
||||
> 帮助用户更高效或更轻松完成任务的建议。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 用户需要了解的关键信息，以实现他们的目标。
|
||||
|
||||
> [!WARNING]
|
||||
> 需要用户立即关注的紧急信息，以避免出现问题。
|
||||
|
||||
> [!CAUTION]
|
||||
> 关于某些操作可能带来风险或负面结果的警告。
|
||||
```
|
||||
|
||||
### 表格
|
||||
|
||||
表格不是 Markdown 核心规范的一部分，但 Hugo 原生支持它们。
|
||||
|
||||
| 姓名 | 年龄 |
|
||||
| :--- | :--- |
|
||||
| 张三 | 27 |
|
||||
| 李四 | 23 |
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
| 姓名 | 年龄 |
|
||||
| :--- | :--- |
|
||||
| 张三 | 27 |
|
||||
| 李四 | 23 |
|
||||
```
|
||||
|
||||
#### 表格内的行内 Markdown
|
||||
|
||||
| 斜体 | 粗体 | 代码 |
|
||||
| :----- | :------- | :----- |
|
||||
| _斜体_ | **粗体** | `代码` |
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
| 斜体 | 粗体 | 代码 |
|
||||
| :----- | :------- | :----- |
|
||||
| _斜体_ | **粗体** | `代码` |
|
||||
```
|
||||
|
||||
### 代码块
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="../../guide/syntax-highlighting" title="语法高亮" icon="sparkles" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
### 列表
|
||||
|
||||
#### 有序列表
|
||||
|
||||
1. 第一项
|
||||
2. 第二项
|
||||
3. 第三项
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
1. 第一项
|
||||
2. 第二项
|
||||
3. 第三项
|
||||
```
|
||||
|
||||
#### 无序列表
|
||||
|
||||
- 列表项
|
||||
- 另一个项
|
||||
- 再一个项
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
- 列表项
|
||||
- 另一个项
|
||||
- 再一个项
|
||||
```
|
||||
|
||||
#### 嵌套列表
|
||||
|
||||
- 水果
|
||||
- 苹果
|
||||
- 橙子
|
||||
- 香蕉
|
||||
- 乳制品
|
||||
- 牛奶
|
||||
- 奶酪
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
- 水果
|
||||
- 苹果
|
||||
- 橙子
|
||||
- 香蕉
|
||||
- 乳制品
|
||||
- 牛奶
|
||||
- 奶酪
|
||||
```
|
||||
|
||||
#### 任务列表
|
||||
|
||||
- [x] 编写文档
|
||||
- [ ] 代码审查
|
||||
- [ ] 部署更改
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
- [x] 编写文档
|
||||
- [ ] 代码审查
|
||||
- [ ] 部署更改
|
||||
```
|
||||
|
||||
### 图片
|
||||
|
||||
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
|
||||
```
|
||||
|
||||
带标题：
|
||||
|
||||
|
||||
|
||||
```markdown {filename=Markdown}
|
||||
|
||||
```
|
||||
|
||||
如需更高级的功能，请使用 Hugo 内置的 [Figure 短代码](https://gohugo.io/shortcodes/figure/)。
|
||||
|
||||
## 配置
|
||||
|
||||
Hugo 使用 [Goldmark](https://github.com/yuin/goldmark) 进行 Markdown 解析。
|
||||
Markdown 渲染可以在 `hugo.yaml` 中的 `markup.goldmark` 下配置。
|
||||
以下是 Hextra 的默认配置：
|
||||
|
||||
```yaml {filename="hugo.yaml"}
|
||||
markup:
|
||||
goldmark:
|
||||
renderer:
|
||||
unsafe: true
|
||||
highlight:
|
||||
noClasses: false
|
||||
```
|
||||
|
||||
更多配置选项，请参阅 Hugo 文档中的 [配置 Markup](https://gohugo.io/getting-started/configuration-markup/)。
|
||||
|
||||
## 学习资源
|
||||
|
||||
- [Markdown 指南](https://www.markdownguide.org/)
|
||||
- [Markdown 速查表](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
|
||||
- [Markdown 教程](https://www.markdowntutorial.com/)
|
||||
- [Markdown 参考](https://commonmark.org/help/)
|
||||
@@ -0,0 +1,256 @@
|
||||
---
|
||||
title: سازماندهی فایلها
|
||||
weight: 1
|
||||
prev: /docs/guide
|
||||
---
|
||||
|
||||
## ساختار دایرکتوری
|
||||
|
||||
بهطور پیشفرض، Hugo فایلهای Markdown را در دایرکتوری `content` جستجو میکند و ساختار این دایرکتوری تعیینکننده ساختار نهایی خروجی وبسایت شماست.
|
||||
این سایت را به عنوان مثال در نظر بگیرید:
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="docs" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="getting-started.md" >}}
|
||||
{{< filetree/folder name="guide" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="organize-files.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="blog" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="post-1.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
هر یک از فایلهای `_index.md` صفحه اصلی مربوط به بخش خود هستند. سایر فایلهای Markdown صفحات معمولی هستند.
|
||||
|
||||
```
|
||||
content
|
||||
├── _index.md // <- /
|
||||
├── docs
|
||||
│ ├── _index.md // <- /docs/
|
||||
│ ├── getting-started.md // <- /docs/getting-started/
|
||||
│ └── guide
|
||||
│ ├── _index.md // <- /docs/guide/
|
||||
│ └── organize-files.md // <- /docs/guide/organize-files/
|
||||
└── blog
|
||||
├── _index.md // <- /blog/
|
||||
└── post-1.md // <- /blog/post-1/
|
||||
```
|
||||
|
||||
## طرحبندیها
|
||||
|
||||
Hextra سه طرحبندی برای انواع مختلف محتوا ارائه میدهد:
|
||||
|
||||
| طرحبندی | دایرکتوری | ویژگیها |
|
||||
| :-------- | :----------------- | :----------------------------------------------------------- |
|
||||
| `docs` | `content/docs/` | مناسب برای مستندات ساختاریافته، مشابه این بخش. |
|
||||
| `blog` | `content/blog/` | برای پستهای وبلاگ، با نمایش لیست و مقالههای تفصیلی. |
|
||||
| `default` | سایر دایرکتوریها | نمایش تکصفحهای مقاله بدون نوار کناری. |
|
||||
|
||||
برای سفارشیسازی یک بخش به منظور تقلید رفتار یک طرحبندی داخلی، نوع مورد نظر را در front matter فایل `_index.md` بخش مشخص کنید.
|
||||
|
||||
```yaml {filename="content/my-docs/_index.md"}
|
||||
---
|
||||
title: مستندات من
|
||||
cascade:
|
||||
type: docs
|
||||
---
|
||||
```
|
||||
|
||||
مثال پیکربندی بالا تضمین میکند که فایلهای محتوا در `content/my-docs/` بهطور پیشفرض به عنوان مستندات (نوع `docs`) در نظر گرفته میشوند.
|
||||
|
||||
## ناوبری نوار کناری
|
||||
|
||||
ناوبری نوار کناری بهطور خودکار بر اساس سازماندهی محتوا به ترتیب الفبایی ایجاد میشود. برای پیکربندی دستی ترتیب نوار کناری، میتوانیم از پارامتر `weight` در front matter فایلهای Markdown استفاده کنیم.
|
||||
|
||||
```yaml {filename="content/docs/guide/_index.md"}
|
||||
---
|
||||
title: راهنما
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
|
||||
{{< callout type="info" >}}
|
||||
توصیه میشود نوار کناری را خیلی عمیق نگه ندارید. اگر محتوای زیادی دارید، **آنها را به چند بخش تقسیم کنید**.
|
||||
{{< /callout >}}
|
||||
|
||||
## ناوبری بخش
|
||||
|
||||
### ترتیب صفحهبندی بخش
|
||||
|
||||
ترتیب صفحات، که از طریق [`PAGE.PrevInSection`](https://gohugo.io/methods/page/previnsection/) و [`PAGE.NextInSection`](https://gohugo.io/methods/page/nextinsection/) در یک [مجموعه صفحه](https://gohugo.io/quick-reference/glossary/#page-collection) قابل دسترسی هستند، بهطور پیشفرض معکوس شده است.
|
||||
|
||||
برای غیرفعال کردن این ترتیب معکوس، میتوانید پارامتر سفارشی `reversePagination` را در front matter صفحه به `false` تنظیم کنید. بهطور پیشفرض `reversePagination` روی `true` تنظیم شده است.
|
||||
|
||||
#### مثال
|
||||
|
||||
با توجه به ساختار دایرکتوری زیر:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="blog" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="my-blog-series" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="post-a" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="post-b" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="post-c" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
و front matter زیر در پستها:
|
||||
|
||||
```yaml {filename="content/blog/my-blog-series/post-a/index.md"}
|
||||
---
|
||||
title: پست A
|
||||
weight: 1
|
||||
---
|
||||
```
|
||||
```yaml {filename="content/blog/my-blog-series/post-b/index.md"}
|
||||
---
|
||||
title: پست B
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
```yaml {filename="content/blog/my-blog-series/post-c/index.md"}
|
||||
---
|
||||
title: پست C
|
||||
weight: 3
|
||||
---
|
||||
```
|
||||
|
||||
اگر خواننده در انتهای `post-b/index.md` باشد، میبیند که صفحه بعدی `post-a` و صفحه قبلی `post-c` است. این به دلیل تنظیم `reversePagination` روی `true` بهطور پیشفرض است. این زمانی مناسب است که بخواهیم پستها به ترتیب زمانی از جدیدترین به قدیمیترین نمایش داده شوند. اما در مورد یک سری وبلاگ که چندین بخش دارد، معمولاً میخواهیم افراد ابتدا پست اول را بخوانند، سپس به پست دوم و غیره بروند. بنابراین میخواهیم ترتیب معکوس را غیرفعال کنیم.
|
||||
|
||||
میتوانیم `reversePagination` را در هر پست وبلاگ در این سری با اضافه کردن front matter زیر به `my-blog-series/_index.md` خاموش کنیم:
|
||||
|
||||
```yaml {filename="content/blog/my-blog-series/_index.md"}
|
||||
---
|
||||
title: سری وبلاگ من
|
||||
cascade:
|
||||
params:
|
||||
reversePagination: false
|
||||
---
|
||||
```
|
||||
|
||||
در اینجا از [`cascade`](https://gohugo.io/content-management/front-matter/#cascade-1) استفاده میکنیم تا این تنظیم به تمام پستهای `my-blog-series` منتقل شود و `reversePagination` برای تمام فرزندان روی `false` تنظیم شود. این اکنون تضمین میکند که وقتی خواننده در `post-b/index.md` است، صفحه بعدی `post-c` و صفحه قبلی `post-a` خواهد بود.
|
||||
|
||||
## ناوبری مسیر راهنما
|
||||
|
||||
مسیرهای راهنما بهطور خودکار بر اساس ساختار دایرکتوری `/content` ایجاد میشوند.
|
||||
|
||||
به عنوان مثال، ساختار فایل [نمایش داده شده در بالا](#directory-structure) را در نظر بگیرید. با توجه به آن ساختار، مسیرهای راهنمای بالای صفحه در `/docs/guide/organize-files/` بهصورت خودکار به این شکل نمایش داده میشوند:
|
||||
|
||||
```
|
||||
مستندات > راهنما > سازماندهی فایلها
|
||||
```
|
||||
|
||||
### سفارشیسازی عنوان لینکهای مسیر راهنما
|
||||
|
||||
بهطور پیشفرض، هر لینک مسیر راهنما بر اساس پارامتر `title` آن صفحه ایجاد میشود. میتوانید این را با مشخص کردن `linkTitle` سفارشی کنید.
|
||||
|
||||
به عنوان مثال، اگر به جای `Organize Files` میخواستیم مسیر راهنما `Foo Bar` باشد:
|
||||
|
||||
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||
---
|
||||
linkTitle: Foo Bar
|
||||
title: سازماندهی فایلها
|
||||
---
|
||||
```
|
||||
|
||||
این اکنون مسیرهای راهنمای زیر را ایجاد میکند:
|
||||
```
|
||||
مستندات > راهنما > Foo Bar
|
||||
```
|
||||
|
||||
### مخفی کردن مسیرهای راهنما
|
||||
|
||||
میتوانید مسیرهای راهنما را بهطور کامل از یک صفحه با مشخص کردن `breadcrumbs: false` در front matter آن مخفی کنید:
|
||||
|
||||
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||
---
|
||||
breadcrumbs: false
|
||||
title: سازماندهی فایلها
|
||||
---
|
||||
```
|
||||
|
||||
## پیکربندی دایرکتوری محتوا
|
||||
|
||||
بهطور پیشفرض، دایرکتوری ریشه `content/` توسط Hugo برای ساخت سایت استفاده میشود.
|
||||
اگر نیاز به استفاده از دایرکتوری دیگری برای محتوا دارید، مثلاً `docs/`، این کار را میتوان با تنظیم پارامتر [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) در پیکربندی سایت `hugo.yaml` انجام داد.
|
||||
|
||||
## اضافه کردن تصاویر
|
||||
|
||||
برای اضافه کردن تصاویر، سادهترین راه این است که فایلهای تصویر را در همان دایرکتوری فایل Markdown قرار دهید.
|
||||
به عنوان مثال، یک فایل تصویر `image.png` را در کنار فایل `my-page.md` اضافه کنید:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/file name="my-page.md" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
سپس میتوانیم از سینتکس Markdown زیر برای اضافه کردن تصویر به محتوا استفاده کنیم:
|
||||
|
||||
```markdown {filename="content/docs/my-page.md"}
|
||||
|
||||
```
|
||||
|
||||
همچنین میتوانیم از ویژگی [page bundles][page-bundles] Hugo استفاده کنیم تا فایلهای تصویر را همراه با فایل Markdown سازماندهی کنیم. برای این کار، فایل `my-page.md` را به یک دایرکتوری `my-page` تبدیل کنید و محتوا را در یک فایل به نام `index.md` قرار دهید و فایلهای تصویر را داخل دایرکتوری `my-page` قرار دهید:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/folder name="my-page" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
```markdown {filename="content/docs/my-page/index.md"}
|
||||
|
||||
```
|
||||
|
||||
بهعنوان جایگزین، میتوانیم فایلهای تصویر را در دایرکتوری `static` قرار دهیم، که تصاویر را برای تمام صفحات قابل دسترس میکند:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="static" >}}
|
||||
{{< filetree/folder name="images" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/file name="my-page.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
توجه کنید که مسیر تصویر با یک اسلش `/` شروع میشود و نسبت به دایرکتوری static است:
|
||||
|
||||
```markdown {filename="content/docs/my-page.md"}
|
||||
|
||||
```
|
||||
|
||||
[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles
|
||||
@@ -0,0 +1,256 @@
|
||||
---
|
||||
title: ファイルの整理
|
||||
weight: 1
|
||||
prev: /docs/guide
|
||||
---
|
||||
|
||||
## ディレクトリ構造
|
||||
|
||||
デフォルトでは、Hugo は `content` ディレクトリ内の Markdown ファイルを検索し、ディレクトリの構造がウェブサイトの最終的な出力構造を決定します。
|
||||
このサイトを例に挙げます：
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="docs" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="getting-started.md" >}}
|
||||
{{< filetree/folder name="guide" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="organize-files.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="blog" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="post-1.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
各 `_index.md` ファイルは、対応するセクションのインデックスページです。他の Markdown ファイルは通常のページです。
|
||||
|
||||
```
|
||||
content
|
||||
├── _index.md // <- /
|
||||
├── docs
|
||||
│ ├── _index.md // <- /docs/
|
||||
│ ├── getting-started.md // <- /docs/getting-started/
|
||||
│ └── guide
|
||||
│ ├── _index.md // <- /docs/guide/
|
||||
│ └── organize-files.md // <- /docs/guide/organize-files/
|
||||
└── blog
|
||||
├── _index.md // <- /blog/
|
||||
└── post-1.md // <- /blog/post-1/
|
||||
```
|
||||
|
||||
## レイアウト
|
||||
|
||||
Hextra は、異なるコンテンツタイプに対して3つのレイアウトを提供します：
|
||||
|
||||
| レイアウト | ディレクトリ | 特徴 |
|
||||
| :-------- | :------------------- | :------------------------------------------------------------------- |
|
||||
| `docs` | `content/docs/` | 構造化されたドキュメントに最適。このセクションと同じです。 |
|
||||
| `blog` | `content/blog/` | ブログ投稿用。リスト表示と詳細記事ビューの両方があります。 |
|
||||
| `default` | その他のディレクトリ | サイドバーなしの単一ページ記事ビュー。 |
|
||||
|
||||
セクションの動作を組み込みレイアウトと同じにするには、セクションの `_index.md` のフロントマターで希望するタイプを指定します。
|
||||
|
||||
```yaml {filename="content/my-docs/_index.md"}
|
||||
---
|
||||
title: My Docs
|
||||
cascade:
|
||||
type: docs
|
||||
---
|
||||
```
|
||||
|
||||
上記の設定例により、`content/my-docs/` 内のコンテンツファイルはデフォルトでドキュメント（`docs` タイプ）として扱われます。
|
||||
|
||||
## サイドバーナビゲーション
|
||||
|
||||
サイドバーナビゲーションは、コンテンツのアルファベット順に基づいて自動的に生成されます。サイドバーの順序を手動で設定するには、Markdown ファイルのフロントマターで `weight` パラメータを使用します。
|
||||
|
||||
```yaml {filename="content/docs/guide/_index.md"}
|
||||
---
|
||||
title: Guide
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
|
||||
{{< callout type="info" >}}
|
||||
サイドバーを深くしすぎないことをお勧めします。多くのコンテンツがある場合は、**複数のセクションに分割する**ことを検討してください。
|
||||
{{< /callout >}}
|
||||
|
||||
## セクションナビゲーション
|
||||
|
||||
### セクションページネーションの順序
|
||||
|
||||
[`PAGE.PrevInSection`](https://gohugo.io/methods/page/previnsection/) や [`PAGE.NextInSection`](https://gohugo.io/methods/page/nextinsection/) でアクセスされるページの順序は、デフォルトで逆順になっています。
|
||||
|
||||
この逆順を無効にするには、ページのフロントマターで `reversePagination` カスタムパラメータを `false` に設定します。デフォルトでは `reversePagination` は `true` に設定されています。
|
||||
|
||||
#### 例
|
||||
|
||||
次のディレクトリ構造を考えます：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="blog" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="my-blog-series" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="post-a" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="post-b" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="post-c" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
そして、投稿のフロントマターは次のようになっています：
|
||||
|
||||
```yaml {filename="content/blog/my-blog-series/post-a/index.md"}
|
||||
---
|
||||
title: Post A
|
||||
weight: 1
|
||||
---
|
||||
```
|
||||
```yaml {filename="content/blog/my-blog-series/post-b/index.md"}
|
||||
---
|
||||
title: Post B
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
```yaml {filename="content/blog/my-blog-series/post-c/index.md"}
|
||||
---
|
||||
title: Post C
|
||||
weight: 3
|
||||
---
|
||||
```
|
||||
|
||||
読者が `post-b/index.md` の下部にいる場合、次のページは `post-a`、前のページは `post-c` と表示されます。これは `reversePagination` がデフォルトで `true` に設定されているためです。これは、投稿を最新から古い順に表示したい場合に適しています。しかし、複数のパートからなるブログシリーズの場合、通常は最初の投稿を読み、次に2番目、という順序で読んでほしいものです。そのため、逆順を無効にします。
|
||||
|
||||
このシリーズのすべてのブログ投稿で `reversePagination` をオフにするには、`my-blog-series/_index.md` に次のフロントマターを追加します：
|
||||
|
||||
```yaml {filename="content/blog/my-blog-series/_index.md"}
|
||||
---
|
||||
title: My Blog Series
|
||||
cascade:
|
||||
params:
|
||||
reversePagination: false
|
||||
---
|
||||
```
|
||||
|
||||
ここでは [`cascade`](https://gohugo.io/content-management/front-matter/#cascade-1) を使用して、`my-blog-series` 内のすべての投稿に設定を伝播させ、すべての子孫で `reversePagination` が `false` に設定されるようにしています。これにより、読者が `post-b/index.md` にいる場合、次のページは `post-c`、前のページは `post-a` と表示されるようになります。
|
||||
|
||||
## パンくずリストナビゲーション
|
||||
|
||||
パンくずリストは、`/content` のディレクトリ構造に基づいて自動生成されます。
|
||||
|
||||
たとえば、[上記のディレクトリ構造](#directory-structure)を考えます。その構造に基づいて、`/docs/guide/organize-files/` のページ上部のパンくずリストは自動的に次のように表示されます：
|
||||
|
||||
```
|
||||
Documentation > Guide > Organize Files
|
||||
```
|
||||
|
||||
### パンくずリストのリンクタイトルのカスタマイズ
|
||||
|
||||
デフォルトでは、各パンくずリストのリンクはそのページの `title` パラメータに基づいて生成されます。これをカスタマイズするには、`linkTitle` を指定します。
|
||||
|
||||
たとえば、`Organize Files` の代わりにパンくずリストを `Foo Bar` にしたい場合：
|
||||
|
||||
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||
---
|
||||
linkTitle: Foo Bar
|
||||
title: Organize Files
|
||||
---
|
||||
```
|
||||
|
||||
これにより、次のパンくずリストが生成されます：
|
||||
```
|
||||
Documentation > Guide > Foo Bar
|
||||
```
|
||||
|
||||
### パンくずリストの非表示
|
||||
|
||||
ページからパンくずリストを完全に非表示にするには、フロントマターで `breadcrumbs: false` を指定します：
|
||||
|
||||
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||
---
|
||||
breadcrumbs: false
|
||||
title: Organize Files
|
||||
---
|
||||
```
|
||||
|
||||
## コンテンツディレクトリの設定
|
||||
|
||||
デフォルトでは、Hugo はサイトを構築するためにルートの `content/` ディレクトリを使用します。
|
||||
別のディレクトリ（例えば `docs/`）をコンテンツ用に使用する必要がある場合は、サイト設定 `hugo.yaml` で [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) パラメータを設定することで可能です。
|
||||
|
||||
## 画像の追加
|
||||
|
||||
画像を追加する最も簡単な方法は、画像ファイルを Markdown ファイルと同じディレクトリに置くことです。
|
||||
たとえば、`my-page.md` ファイルと同じディレクトリに `image.png` ファイルを追加します：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/file name="my-page.md" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
そして、次の Markdown 構文を使用してコンテンツに画像を追加できます：
|
||||
|
||||
```markdown {filename="content/docs/my-page.md"}
|
||||
|
||||
```
|
||||
|
||||
また、Hugo の [ページバンドル][page-bundles] 機能を利用して、画像ファイルを Markdown ファイルと一緒に整理することもできます。そのためには、`my-page.md` ファイルを `my-page` ディレクトリに変換し、コンテンツを `index.md` というファイルに置き、画像ファイルを `my-page` ディレクトリ内に配置します：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/folder name="my-page" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
```markdown {filename="content/docs/my-page/index.md"}
|
||||
|
||||
```
|
||||
|
||||
あるいは、画像ファイルを `static` ディレクトリに置くこともできます。これにより、画像はすべてのページで利用可能になります：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="static" >}}
|
||||
{{< filetree/folder name="images" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/file name="my-page.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
画像パスはスラッシュ `/` で始まり、static ディレクトリからの相対パスであることに注意してください：
|
||||
|
||||
```markdown {filename="content/docs/my-page.md"}
|
||||
|
||||
```
|
||||
|
||||
[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles
|
||||
@@ -0,0 +1,277 @@
|
||||
---
|
||||
title: Organize Files
|
||||
weight: 1
|
||||
prev: /docs/guide
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
By default, Hugo searches for Markdown files in the `content` directory, and the structure of the directory determines the final output structure of your website.
|
||||
Take this site as an example:
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="docs" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="getting-started.md" >}}
|
||||
{{< filetree/folder name="guide" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="organize-files.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="blog" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="post-1.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
Each of the `_index.md` files is the index page for the corresponding section. The other Markdown files are regular pages.
|
||||
|
||||
```
|
||||
content
|
||||
├── _index.md // <- /
|
||||
├── docs
|
||||
│ ├── _index.md // <- /docs/
|
||||
│ ├── getting-started.md // <- /docs/getting-started/
|
||||
│ └── guide
|
||||
│ ├── _index.md // <- /docs/guide/
|
||||
│ └── organize-files.md // <- /docs/guide/organize-files/
|
||||
└── blog
|
||||
├── _index.md // <- /blog/
|
||||
└── post-1.md // <- /blog/post-1/
|
||||
```
|
||||
|
||||
## Layouts
|
||||
|
||||
Hextra offers three layouts for different content types:
|
||||
|
||||
| Layout | Directory | Features |
|
||||
| :-------- | :-------------------- | :--------------------------------------------------------------- |
|
||||
| `docs` | `content/docs/` | Ideal for structured documentation, same as this section. |
|
||||
| `blog` | `content/blog/` | For blog postings, with both listing and detailed article views. |
|
||||
| `default` | All other directories | Single-page article view without sidebar. |
|
||||
|
||||
To customize a section to mirror the behavior of a built-in layout, specify the desired type in the front matter of the section's `_index.md`.
|
||||
|
||||
```yaml {filename="content/my-docs/_index.md"}
|
||||
---
|
||||
title: My Docs
|
||||
cascade:
|
||||
type: docs
|
||||
---
|
||||
```
|
||||
|
||||
The above example configuration ensures that the content files inside `content/my-docs/` will be treated as documentation (`docs` type) by default.
|
||||
|
||||
## Sidebar Navigation
|
||||
|
||||
The sidebar navigation is generated automatically based on the content organization alphabetically. To manually configure the sidebar order, we can use the `weight` parameter in the front matter of the Markdown files.
|
||||
|
||||
```yaml {filename="content/docs/guide/_index.md"}
|
||||
---
|
||||
title: Guide
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
|
||||
{{< callout type="info" >}}
|
||||
It is recommended to keep the sidebar not too deep. If you have a lot of content, consider **splitting them into multiple sections**.
|
||||
{{< /callout >}}
|
||||
|
||||
## Section Navigation
|
||||
|
||||
|
||||
### Section Pagination Order
|
||||
|
||||
The order in which pages, accessed via [`PAGE.PrevInSection`](https://gohugo.io/methods/page/previnsection/) and [`PAGE.NextInSection`](https://gohugo.io/methods/page/nextinsection/) in a [page collection](https://gohugo.io/quick-reference/glossary/#page-collection), are ordered, is reversed by default.
|
||||
|
||||
To disable this reversed ordering you can set the `reversePagination` custom parameter in the page front matter to `false`. By default `reversePagination` is set to `true`.
|
||||
|
||||
#### Example
|
||||
|
||||
Given the following directory structure:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="blog" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="my-blog-series" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="post-a" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="post-b" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="post-c" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
And the following front matter in the posts:
|
||||
|
||||
```yaml {filename="content/blog/my-blog-series/post-a/index.md"}
|
||||
---
|
||||
title: Post A
|
||||
weight: 1
|
||||
---
|
||||
```
|
||||
```yaml {filename="content/blog/my-blog-series/post-b/index.md"}
|
||||
---
|
||||
title: Post B
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
```yaml {filename="content/blog/my-blog-series/post-c/index.md"}
|
||||
---
|
||||
title: Post C
|
||||
weight: 3
|
||||
---
|
||||
```
|
||||
|
||||
If the reader is at the bottom of `post-b/index.md`, they will see that the next page is `post-a`, and the previous page is `post-c`. This is due to `reversePagination` being set to `true` by default. This is ok when we want our posts to be displayed in chronological order from latest to oldest. However, in the case of a blog series where there are multiple parts, we typically want people to read the first post, and then move to the second and so on. So we want to disable the reversed ordering.
|
||||
|
||||
We can turn off `reversePagination` in every blog post in this series by adding the following front matter to `my-blog-series/_index.md`
|
||||
|
||||
```yaml {filename="content/blog/my-blog-series/_index.md"}
|
||||
---
|
||||
title: My Blog Series
|
||||
cascade:
|
||||
params:
|
||||
reversePagination: false
|
||||
---
|
||||
```
|
||||
|
||||
We are using [`cascade`](https://gohugo.io/content-management/front-matter/#cascade-1) here to propagate the setting to all posts in the `my-blog-series` so that `reversePagination` is set to `false` for all descendents. This will now ensure that when the reader is on `post-b/index.md` they will see that the next page is `post-c` and the previous page is `post-a`.
|
||||
|
||||
## Breadcrumb Navigation
|
||||
|
||||
Breadcrumbs are auto-generated based on the directory structure of `/content`.
|
||||
|
||||
For example, consider the file structure [demonstrated above](#directory-structure). Given that structure, the breadcrumbs atop the page at `/docs/guide/organize-files/` would appear automatically as follows:
|
||||
|
||||
```
|
||||
Documentation > Guide > Organize Files
|
||||
```
|
||||
|
||||
### Customizing Breadcrumb Link Titles
|
||||
|
||||
By default, each breadcrumb link is generated based on that page's `title` parameter. You can customize this by specifying a `linkTitle`.
|
||||
|
||||
For example, if instead of `Organize Files` we wanted the breadcrumb to be `Foo Bar`:
|
||||
|
||||
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||
---
|
||||
linkTitle: Foo Bar
|
||||
title: Organize Files
|
||||
---
|
||||
```
|
||||
|
||||
This would now generate the following breadcrumbs:
|
||||
```
|
||||
Documentation > Guide > Foo Bar
|
||||
```
|
||||
|
||||
### Enabling and Disabling Breadcrumbs
|
||||
|
||||
Whether breadcrumbs are enabled, or disabled, by default for a page, is determined by its [content type](https://gohugo.io/quick-reference/glossary/#content-type) and [page kind](https://gohugo.io/quick-reference/glossary/#page-kind):
|
||||
|
||||
| Content Type | Section | Page |
|
||||
|:----------------|:--------:|:----------|
|
||||
| `docs` | Enabled | Enabled |
|
||||
| `blog` | Disabled | Enabled |
|
||||
| Any other type | Disabled | Disabled |
|
||||
|
||||
You can override these defaults on a page by setting `breadcrumbs` in its front matter:
|
||||
|
||||
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||
---
|
||||
breadcrumbs: false
|
||||
title: Organize Files
|
||||
---
|
||||
```
|
||||
|
||||
Similarly you can use [cascade](https://gohugo.io/content-management/front-matter/#cascade-1) to override the defaults on a page and its decendents:
|
||||
|
||||
```yaml {filename="content/portfolio/_index.md"}
|
||||
---
|
||||
title: "Portfolio"
|
||||
|
||||
cascade:
|
||||
params:
|
||||
breadcrumbs: true
|
||||
---
|
||||
```
|
||||
|
||||
## Configure Content Directory
|
||||
|
||||
By default, the root `content/` directory is used by Hugo to build the site.
|
||||
If you need to use a different directory for content, for example `docs/`, this can be done by setting the [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) parameter in the site configuration `hugo.yaml`.
|
||||
|
||||
## Add Images
|
||||
|
||||
To add images, the easiest way is to put the image files in the same directory as the Markdown file.
|
||||
For example, add an image file `image.png` alongside the `my-page.md` file:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/file name="my-page.md" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
Then, we can use the following Markdown syntax to add the image to the content:
|
||||
|
||||
```markdown {filename="content/docs/my-page.md"}
|
||||
|
||||
```
|
||||
|
||||
We can also utilize the [page bundles][page-bundles] feature of Hugo to organize the image files together with the Markdown file. To achieve that, turn the `my-page.md` file into a directory `my-page` and put the content into a file named `index.md`, and put the image files inside the `my-page` directory:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/folder name="my-page" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
```markdown {filename="content/docs/my-page/index.md"}
|
||||
|
||||
```
|
||||
|
||||
Alternatively, we can also put the image files in the `static` directory, which will make the images available for all pages:
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="static" >}}
|
||||
{{< filetree/folder name="images" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/file name="my-page.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
Note that the image path begins with a slash `/` and is relative to the static directory:
|
||||
|
||||
```markdown {filename="content/docs/my-page.md"}
|
||||
|
||||
```
|
||||
|
||||
[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles
|
||||
@@ -0,0 +1,256 @@
|
||||
---
|
||||
title: 文件组织
|
||||
weight: 1
|
||||
prev: /docs/guide
|
||||
---
|
||||
|
||||
## 目录结构
|
||||
|
||||
默认情况下，Hugo 会在 `content` 目录中查找 Markdown 文件，目录的结构决定了网站最终的输出结构。
|
||||
以本网站为例：
|
||||
|
||||
<!--more-->
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="docs" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="getting-started.md" >}}
|
||||
{{< filetree/folder name="guide" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="organize-files.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="blog" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/file name="post-1.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
每个 `_index.md` 文件都是对应部分的索引页。其他 Markdown 文件则是常规页面。
|
||||
|
||||
```
|
||||
content
|
||||
├── _index.md // <- /
|
||||
├── docs
|
||||
│ ├── _index.md // <- /docs/
|
||||
│ ├── getting-started.md // <- /docs/getting-started/
|
||||
│ └── guide
|
||||
│ ├── _index.md // <- /docs/guide/
|
||||
│ └── organize-files.md // <- /docs/guide/organize-files/
|
||||
└── blog
|
||||
├── _index.md // <- /blog/
|
||||
└── post-1.md // <- /blog/post-1/
|
||||
```
|
||||
|
||||
## 布局
|
||||
|
||||
Hextra 为不同类型的内容提供了三种布局：
|
||||
|
||||
| 布局 | 目录 | 特点 |
|
||||
| :-------- | :----------------- | :------------------------------------------------------------- |
|
||||
| `docs` | `content/docs/` | 适合结构化文档，与本部分相同。 |
|
||||
| `blog` | `content/blog/` | 用于博客文章，包含列表和详细文章视图。 |
|
||||
| `default` | 其他所有目录 | 单页文章视图，无侧边栏。 |
|
||||
|
||||
要自定义一个部分以模仿内置布局的行为，可以在该部分的 `_index.md` 的 front matter 中指定所需的类型。
|
||||
|
||||
```yaml {filename="content/my-docs/_index.md"}
|
||||
---
|
||||
title: 我的文档
|
||||
cascade:
|
||||
type: docs
|
||||
---
|
||||
```
|
||||
|
||||
上述示例配置确保 `content/my-docs/` 内的内容文件默认会被视为文档（`docs` 类型）。
|
||||
|
||||
## 侧边栏导航
|
||||
|
||||
侧边栏导航会根据内容组织按字母顺序自动生成。要手动配置侧边栏顺序，可以在 Markdown 文件的 front matter 中使用 `weight` 参数。
|
||||
|
||||
```yaml {filename="content/docs/guide/_index.md"}
|
||||
---
|
||||
title: 指南
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
|
||||
{{< callout type="info" >}}
|
||||
建议不要让侧边栏过深。如果有大量内容，可以考虑**将其拆分为多个部分**。
|
||||
{{< /callout >}}
|
||||
|
||||
## 部分导航
|
||||
|
||||
### 部分分页顺序
|
||||
|
||||
通过 [`PAGE.PrevInSection`](https://gohugo.io/methods/page/previnsection/) 和 [`PAGE.NextInSection`](https://gohugo.io/methods/page/nextinsection/) 访问的页面在[页面集合](https://gohugo.io/quick-reference/glossary/#page-collection)中的顺序默认是反向的。
|
||||
|
||||
要禁用这种反向排序，可以在页面的 front matter 中将 `reversePagination` 自定义参数设置为 `false`。默认情况下，`reversePagination` 设置为 `true`。
|
||||
|
||||
#### 示例
|
||||
|
||||
给定以下目录结构：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="blog" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="my-blog-series" state="open" >}}
|
||||
{{< filetree/file name="_index.md" >}}
|
||||
{{< filetree/folder name="post-a" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="post-b" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="post-c" state="open" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
并在文章的 front matter 中设置：
|
||||
|
||||
```yaml {filename="content/blog/my-blog-series/post-a/index.md"}
|
||||
---
|
||||
title: 文章 A
|
||||
weight: 1
|
||||
---
|
||||
```
|
||||
```yaml {filename="content/blog/my-blog-series/post-b/index.md"}
|
||||
---
|
||||
title: 文章 B
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
```yaml {filename="content/blog/my-blog-series/post-c/index.md"}
|
||||
---
|
||||
title: 文章 C
|
||||
weight: 3
|
||||
---
|
||||
```
|
||||
|
||||
如果读者位于 `post-b/index.md` 的底部，他们会看到下一页是 `post-a`，上一页是 `post-c`。这是由于 `reversePagination` 默认设置为 `true`。当我们希望文章按从最新到最旧的顺序显示时，这是可以的。然而，对于多部分的博客系列，我们通常希望读者先阅读第一部分，然后依次阅读后续部分。因此，我们希望禁用反向排序。
|
||||
|
||||
我们可以通过在 `my-blog-series/_index.md` 中添加以下 front matter 来关闭该系列中所有博客文章的 `reversePagination`：
|
||||
|
||||
```yaml {filename="content/blog/my-blog-series/_index.md"}
|
||||
---
|
||||
title: 我的博客系列
|
||||
cascade:
|
||||
params:
|
||||
reversePagination: false
|
||||
---
|
||||
```
|
||||
|
||||
这里我们使用 [`cascade`](https://gohugo.io/content-management/front-matter/#cascade-1) 将设置传播到 `my-blog-series` 中的所有文章，以便所有后代都将 `reversePagination` 设置为 `false`。这将确保当读者在 `post-b/index.md` 时，他们会看到下一页是 `post-c`，上一页是 `post-a`。
|
||||
|
||||
## 面包屑导航
|
||||
|
||||
面包屑会根据 `/content` 的目录结构自动生成。
|
||||
|
||||
例如，考虑[上面展示的](#directory-structure)文件结构。给定该结构，位于 `/docs/guide/organize-files/` 的页面顶部的面包屑会自动显示如下：
|
||||
|
||||
```
|
||||
文档 > 指南 > 组织文件
|
||||
```
|
||||
|
||||
### 自定义面包屑链接标题
|
||||
|
||||
默认情况下，每个面包屑链接是根据该页面的 `title` 参数生成的。可以通过指定 `linkTitle` 来自定义。
|
||||
|
||||
例如，如果我们希望面包屑显示为 `Foo Bar` 而不是 `Organize Files`：
|
||||
|
||||
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||
---
|
||||
linkTitle: Foo Bar
|
||||
title: 组织文件
|
||||
---
|
||||
```
|
||||
|
||||
现在会生成以下面包屑：
|
||||
```
|
||||
文档 > 指南 > Foo Bar
|
||||
```
|
||||
|
||||
### 隐藏面包屑
|
||||
|
||||
可以通过在页面的 front matter 中指定 `breadcrumbs: false` 来完全隐藏面包屑：
|
||||
|
||||
```yaml {filename="content/docs/guide/organize-files.md"}
|
||||
---
|
||||
breadcrumbs: false
|
||||
title: 组织文件
|
||||
---
|
||||
```
|
||||
|
||||
## 配置内容目录
|
||||
|
||||
默认情况下，Hugo 使用根目录 `content/` 来构建网站。
|
||||
如果需要使用其他目录作为内容目录，例如 `docs/`，可以在站点配置 `hugo.yaml` 中设置 [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) 参数。
|
||||
|
||||
## 添加图片
|
||||
|
||||
添加图片最简单的方法是将图片文件放在与 Markdown 文件相同的目录中。
|
||||
例如，将图片文件 `image.png` 与 `my-page.md` 文件放在一起：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/file name="my-page.md" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
然后，可以使用以下 Markdown 语法将图片添加到内容中：
|
||||
|
||||
```markdown {filename="content/docs/my-page.md"}
|
||||
|
||||
```
|
||||
|
||||
我们还可以利用 Hugo 的[页面包][page-bundles]功能将图片文件与 Markdown 文件组织在一起。为此，将 `my-page.md` 文件转换为目录 `my-page`，并将内容放入名为 `index.md` 的文件中，然后将图片文件放入 `my-page` 目录中：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/folder name="my-page" >}}
|
||||
{{< filetree/file name="index.md" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
```markdown {filename="content/docs/my-page/index.md"}
|
||||
|
||||
```
|
||||
|
||||
或者，我们也可以将图片文件放在 `static` 目录中，这样所有页面都可以访问这些图片：
|
||||
|
||||
{{< filetree/container >}}
|
||||
{{< filetree/folder name="static" >}}
|
||||
{{< filetree/folder name="images" >}}
|
||||
{{< filetree/file name="image.png" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< filetree/folder name="content" >}}
|
||||
{{< filetree/folder name="docs" >}}
|
||||
{{< filetree/file name="my-page.md" >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/folder >}}
|
||||
{{< /filetree/container >}}
|
||||
|
||||
注意，图片路径以斜杠 `/` 开头，并且相对于 static 目录：
|
||||
|
||||
```markdown {filename="content/docs/my-page.md"}
|
||||
|
||||
```
|
||||
|
||||
[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: شورتکدها
|
||||
weight: 9
|
||||
prev: /docs/guide/diagrams
|
||||
next: /docs/guide/shortcodes/callout
|
||||
---
|
||||
|
||||
[شورتکدهای Hugo](https://gohugo.io/content-management/shortcodes/) قطعهکدهای سادهای درون فایلهای محتوای شما هستند که تمپلیتهای داخلی یا سفارشی را فراخوانی میکنند.
|
||||
|
||||
Hextra مجموعهای از شورتکدهای زیبا را برای بهبود محتوای شما ارائه میدهد.
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="callout" title="کالاوت" icon="warning" >}}
|
||||
{{< card link="cards" title="کارتها" icon="card" >}}
|
||||
{{< card link="details" title="جزئیات" icon="chevron-right" >}}
|
||||
{{< card link="filetree" title="درخت فایل" icon="folder-tree" >}}
|
||||
{{< card link="icon" title="آیکون" icon="badge-check" >}}
|
||||
{{< card link="steps" title="مراحل" icon="one" >}}
|
||||
{{< card link="tabs" title="تبها" icon="collection" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
<div style="padding-top:4rem"></div>
|
||||
|
||||
شورتکدهای اضافی ارائه شده توسط Hugo و Hextra:
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="jupyter" title="نوتبوک Jupyter" icon="jupyter" tag="alpha" >}}
|
||||
{{< card link="others" title="سایر" icon="view-grid" >}}
|
||||
{{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: ショートコード
|
||||
weight: 9
|
||||
prev: /docs/guide/diagrams
|
||||
next: /docs/guide/shortcodes/callout
|
||||
---
|
||||
|
||||
[Hugo ショートコード](https://gohugo.io/content-management/shortcodes/)は、コンテンツファイル内に記述する簡潔なスニペットで、組み込みまたはカスタムテンプレートを呼び出します。
|
||||
|
||||
Hextra は、コンテンツを強化するための美しいショートコードのコレクションを提供します。
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="callout" title="Callout" icon="warning" >}}
|
||||
{{< 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="icon" title="Icon" icon="badge-check" >}}
|
||||
{{< card link="steps" title="Steps" icon="one" >}}
|
||||
{{< card link="tabs" title="Tabs" icon="collection" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
<div style="padding-top:4rem"></div>
|
||||
|
||||
Hugo と Hextra が提供する追加のショートコード:
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="jupyter" title="Jupyter Notebook" icon="jupyter" tag="alpha" >}}
|
||||
{{< card link="others" title="Others" icon="view-grid" >}}
|
||||
{{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Shortcodes
|
||||
weight: 9
|
||||
prev: /docs/guide/diagrams
|
||||
next: /docs/guide/shortcodes/callout
|
||||
---
|
||||
|
||||
[Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/) are simple snippets inside your content files calling built-in or custom templates.
|
||||
|
||||
Hextra provides a collection of beautiful shortcodes to enhance your content.
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="callout" title="Callout" icon="warning" >}}
|
||||
{{< 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" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
<div style="padding-top:4rem"></div>
|
||||
|
||||
Additional shortcodes provided by Hugo and Hextra:
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="jupyter" title="Jupyter Notebook" icon="jupyter" tag="alpha" >}}
|
||||
{{< card link="others" title="Others" icon="view-grid" >}}
|
||||
{{< card link="hextra" title="Hextra" icon="view-grid" >}}
|
||||
{{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: 短代码
|
||||
weight: 9
|
||||
prev: /docs/guide/diagrams
|
||||
next: /docs/guide/shortcodes/callout
|
||||
---
|
||||
|
||||
[Hugo 短代码](https://gohugo.io/content-management/shortcodes/)是内容文件中调用内置或自定义模板的简单片段。
|
||||
|
||||
Hextra 提供了一系列精美的短代码来增强您的内容。
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="callout" title="提示框" icon="warning" >}}
|
||||
{{< card link="cards" title="卡片" icon="card" >}}
|
||||
{{< card link="details" title="详情" icon="chevron-right" >}}
|
||||
{{< card link="filetree" title="文件树" icon="folder-tree" >}}
|
||||
{{< card link="icon" title="图标" icon="badge-check" >}}
|
||||
{{< card link="steps" title="步骤" icon="one" >}}
|
||||
{{< card link="tabs" title="标签页" icon="collection" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
<div style="padding-top:4rem"></div>
|
||||
|
||||
Hugo 和 Hextra 提供的其他短代码：
|
||||
|
||||
{{< cards >}}
|
||||
{{< card link="jupyter" title="Jupyter 笔记本" icon="jupyter" tag="alpha" >}}
|
||||
{{< card link="others" title="其他" icon="view-grid" >}}
|
||||
{{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: "Asciinema Player کامپوننت"
|
||||
linktitle: "Asciinema Player"
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
|
||||
shortcode asciinema به شما امکان میدهد تا ضبطهای ترمینال ایجاد شده با [asciinema](https://asciinema.org/) را در سایت Hugo خود جاسازی کنید. این یک پخشکننده ترمینال غنی با ویژگیهایی مانند کنترل پخش، تنظیم سرعت و سفارشیسازی تم ارائه میدهد.
|
||||
|
||||
## استفاده پایه
|
||||
|
||||
shortcode asciinema از فایلهای `.cast` محلی و URL های راه دور پشتیبانی میکند. روشهای مختلف استفاده از فایلهای محلی به شرح زیر است:
|
||||
|
||||
### فایلهای محلی
|
||||
|
||||
**روش 1: دایرکتوری Assets (توصیه شده)**
|
||||
فایلهای cast را در دایرکتوری `assets/` سایت Hugo خود قرار دهید:
|
||||
|
||||
```
|
||||
your-site/
|
||||
├── assets/
|
||||
│ └── demo.cast
|
||||
└── content/
|
||||
└── my-page.md
|
||||
```
|
||||
|
||||
در فایل markdown خود:
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
**روش 2: دایرکتوری Static**
|
||||
فایلهای cast را در دایرکتوری `static/` قرار دهید:
|
||||
|
||||
```
|
||||
your-site/
|
||||
├── static/
|
||||
│ └── demo.cast
|
||||
└── content/
|
||||
└── my-page.md
|
||||
```
|
||||
|
||||
در فایل markdown خود:
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
**روش 3: بسته صفحه**
|
||||
برای بستههای صفحه، فایلهای cast را همراه با فایل markdown قرار دهید:
|
||||
|
||||
```
|
||||
your-site/
|
||||
└── content/
|
||||
└── my-page/
|
||||
├── index.md
|
||||
└── demo.cast
|
||||
```
|
||||
|
||||
در فایل markdown خود:
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="casts/demo.cast" >}}
|
||||
|
||||
### فایلهای راه دور
|
||||
|
||||
همچنین میتوانید از فایلهای cast از هر URL راه دور استفاده کنید:
|
||||
|
||||
```markdown
|
||||
{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
|
||||
{{</* asciinema file="https://example.com/demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
|
||||
|
||||
### نحوه کارکرد جستجوی فایل
|
||||
|
||||
shortcode به ترتیب زیر فایلهای cast شما را به طور خودکار پیدا میکند:
|
||||
1. **منابع بسته صفحه** (اگر از بسته صفحه استفاده میکنید)
|
||||
2. **دایرکتوری assets جهانی** (`assets/`)
|
||||
3. **دایرکتوری Static** (`static/`)
|
||||
4. **URL های راه دور** (اگر مسیر با `http://` یا `https://` شروع شود)
|
||||
|
||||
اگر فایل پیدا نشود، Hugo پیام خطای مفیدی نمایش میدهد که به شما میگوید فایل را کجا قرار دهید.
|
||||
|
||||
## نمایش پیشرفته
|
||||
|
||||
این یک مثال پیشرفته است که تمام پارامترهای موجود را نشان میدهد:
|
||||
|
||||
```markdown
|
||||
{{</* asciinema
|
||||
file="demo.cast"
|
||||
theme="dracula"
|
||||
speed="2"
|
||||
autoplay="true"
|
||||
loop="true"
|
||||
markers="1.5:Installation,3.2:Configuration,5.8:Testing"
|
||||
*/>}}
|
||||
```
|
||||
|
||||
{{< asciinema
|
||||
file="casts/demo.cast"
|
||||
theme="dracula"
|
||||
speed="2"
|
||||
autoplay="true"
|
||||
loop="true"
|
||||
markers="1.5:Installation,3.2:Configuration,5.8:Testing"
|
||||
>}}
|
||||
|
||||
## پارامترها
|
||||
|
||||
| پارامتر | نوع | پیشفرض | توضیحات |
|
||||
|---------|-----|---------|---------|
|
||||
| `file` | string | - | مسیر فایل .cast (ضروری). از فایلهای محلی، مسیرهای مطلق و URL های راه دور پشتیبانی میکند |
|
||||
| `theme` | string | `"asciinema"` | تم پخشکننده |
|
||||
| `speed` | number | `1` | ضریب سرعت پخش |
|
||||
| `autoplay` | boolean | `false` | شروع خودکار پخش |
|
||||
| `loop` | boolean | `false` | پخش حلقهای |
|
||||
| `poster` | string | `""` | پوستر (فریم پیشنمایش) برای نمایش تا زمان شروع پخش. از نمادگذاری NPT پشتیبانی میکند (مثل "npt:1:23") |
|
||||
| `markers` | string | `""` | نشانگرهای زمانی جدا شده با کاما. فرمت: "زمان:برچسب" یا فقط "زمان" (مثل "1.5:Installation,3.2:Configuration,5.8") |
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: "Asciinema Player コンポーネント"
|
||||
linktitle: "Asciinema Player"
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
|
||||
asciinema shortcode を使用すると、[asciinema](https://asciinema.org/) で作成されたターミナル録画を Hugo サイトに埋め込むことができます。再生制御、速度調整、テーマカスタマイズなどの機能を備えたリッチなターミナルプレイヤーを提供します。
|
||||
|
||||
## 基本的な使用方法
|
||||
|
||||
asciinema shortcode はローカルの `.cast` ファイルとリモート URL の両方をサポートしています。ローカルファイルを使用する方法は以下の通りです：
|
||||
|
||||
### ローカルファイル
|
||||
|
||||
**方法 1：Assets ディレクトリ（推奨）**
|
||||
cast ファイルを Hugo サイトの `assets/` ディレクトリに配置：
|
||||
|
||||
```
|
||||
your-site/
|
||||
├── assets/
|
||||
│ └── demo.cast
|
||||
└── content/
|
||||
└── my-page.md
|
||||
```
|
||||
|
||||
markdown ファイル内：
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
**方法 2：Static ディレクトリ**
|
||||
cast ファイルを `static/` ディレクトリに配置：
|
||||
|
||||
```
|
||||
your-site/
|
||||
├── static/
|
||||
│ └── demo.cast
|
||||
└── content/
|
||||
└── my-page.md
|
||||
```
|
||||
|
||||
markdown ファイル内：
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
**方法 3：ページバンドル**
|
||||
ページバンドルの場合、cast ファイルを markdown ファイルと一緒に配置：
|
||||
|
||||
```
|
||||
your-site/
|
||||
└── content/
|
||||
└── my-page/
|
||||
├── index.md
|
||||
└── demo.cast
|
||||
```
|
||||
|
||||
markdown ファイル内：
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="casts/demo.cast" >}}
|
||||
|
||||
### リモートファイル
|
||||
|
||||
任意のリモート URL からの cast ファイルも使用できます：
|
||||
|
||||
```markdown
|
||||
{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
|
||||
{{</* asciinema file="https://example.com/demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
|
||||
|
||||
### ファイル検索の仕組み
|
||||
|
||||
shortcode は以下の順序で cast ファイルを自動的に検索します：
|
||||
1. **ページバンドルリソース**（ページバンドルを使用している場合）
|
||||
2. **グローバル assets ディレクトリ**（`assets/`）
|
||||
3. **Static ディレクトリ**（`static/`）
|
||||
4. **リモート URL**（パスが `http://` または `https://` で始まる場合）
|
||||
|
||||
ファイルが見つからない場合、Hugo はファイルをどこに配置すべきかを示す有用なエラーメッセージを表示します。
|
||||
|
||||
## 高度なデモ
|
||||
|
||||
利用可能なすべてのパラメータを紹介する高度な例：
|
||||
|
||||
```markdown
|
||||
{{</* asciinema
|
||||
file="demo.cast"
|
||||
theme="dracula"
|
||||
speed="2"
|
||||
autoplay="true"
|
||||
loop="true"
|
||||
markers="1.5:Installation,3.2:Configuration,5.8:Testing"
|
||||
*/>}}
|
||||
```
|
||||
|
||||
{{< asciinema
|
||||
file="casts/demo.cast"
|
||||
theme="dracula"
|
||||
speed="2"
|
||||
autoplay="true"
|
||||
loop="true"
|
||||
markers="1.5:Installation,3.2:Configuration,5.8:Testing"
|
||||
>}}
|
||||
|
||||
## パラメータ
|
||||
|
||||
| パラメータ | 型 | デフォルト | 説明 |
|
||||
|-----------|----|-----------|------|
|
||||
| `file` | string | - | .cast ファイルパス（必須）。ローカルファイル、絶対パス、リモート URL をサポート |
|
||||
| `theme` | string | `"asciinema"` | プレイヤーテーマ |
|
||||
| `speed` | number | `1` | 再生速度倍率 |
|
||||
| `autoplay` | boolean | `false` | 自動再生 |
|
||||
| `loop` | boolean | `false` | ループ再生 |
|
||||
| `poster` | string | `""` | 再生開始前に表示されるポスター（プレビューフレーム）。NPT表記法をサポート（例："npt:1:23"） |
|
||||
| `markers` | string | `""` | カンマ区切りの時間マーカー。形式："時間:ラベル" または "時間"のみ（例："1.5:Installation,3.2:Configuration,5.8"） |
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: "Asciinema Player Component"
|
||||
linktitle: "Asciinema Player"
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The asciinema shortcode allows you to embed terminal recordings created with [asciinema](https://asciinema.org/) in your Hugo site. It provides a rich terminal player with features like playback controls, speed adjustment, and theme customization.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
The asciinema shortcode supports both local `.cast` files and remote URLs. Here are the different ways to use local files:
|
||||
|
||||
### Local Files
|
||||
|
||||
**Method 1: Assets directory (recommended)**
|
||||
Place your cast files in the `assets/` directory of your Hugo site:
|
||||
|
||||
```
|
||||
your-site/
|
||||
├── assets/
|
||||
│ └── demo.cast
|
||||
└── content/
|
||||
└── my-page.md
|
||||
```
|
||||
|
||||
In your markdown file:
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
**Method 2: Static directory**
|
||||
Place your cast files in the `static/` directory:
|
||||
|
||||
```
|
||||
your-site/
|
||||
├── static/
|
||||
│ └── demo.cast
|
||||
└── content/
|
||||
└── my-page.md
|
||||
```
|
||||
|
||||
In your markdown file:
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
**Method 3: Page bundle**
|
||||
For page bundles, place cast files alongside your markdown file:
|
||||
|
||||
```
|
||||
your-site/
|
||||
└── content/
|
||||
└── my-page/
|
||||
├── index.md
|
||||
└── demo.cast
|
||||
```
|
||||
|
||||
In your markdown file:
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="casts/demo.cast" >}}
|
||||
|
||||
### Remote Files
|
||||
|
||||
You can also use cast files from any remote URL:
|
||||
|
||||
```markdown
|
||||
{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
|
||||
{{</* asciinema file="https://example.com/demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
|
||||
|
||||
### How File Lookup Works
|
||||
|
||||
The shortcode automatically finds your cast files by looking in this order:
|
||||
1. **Page bundle resources** (if using page bundles)
|
||||
2. **Global assets directory** (`assets/`)
|
||||
3. **Static directory** (`static/`)
|
||||
4. **Remote URLs** (if the path starts with `http://` or `https://`)
|
||||
|
||||
If a file is not found, Hugo will show a helpful error message telling you where to place the file.
|
||||
|
||||
## Advanced Demo
|
||||
|
||||
Here's a more advanced example showcasing all available parameters:
|
||||
|
||||
```markdown
|
||||
{{</* asciinema
|
||||
file="demo.cast"
|
||||
theme="dracula"
|
||||
speed="2"
|
||||
autoplay="true"
|
||||
loop="true"
|
||||
markers="1.5:Installation,3.2:Configuration,5.8:Testing"
|
||||
*/>}}
|
||||
```
|
||||
|
||||
{{< asciinema
|
||||
file="casts/demo.cast"
|
||||
theme="dracula"
|
||||
speed="2"
|
||||
autoplay="true"
|
||||
loop="true"
|
||||
markers="1.5:Installation,3.2:Configuration,5.8:Testing"
|
||||
>}}
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `file` | string | - | Path to the .cast file (required). Supports local files, absolute paths, and remote URLs |
|
||||
| `theme` | string | `"asciinema"` | Player theme |
|
||||
| `speed` | number | `1` | Playback speed multiplier |
|
||||
| `autoplay` | boolean | `false` | Start playing automatically |
|
||||
| `loop` | boolean | `false` | Loop the recording |
|
||||
| `poster` | string | `""` | Poster (a preview frame) to display until the playback is started. Supports NPT notation (e.g., "npt:1:23") |
|
||||
| `markers` | string | `""` | Comma-separated time markers. Format: "time:label" or just "time" (e.g., "1.5:Installation,3.2:Configuration,5.8") |
|
||||
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: "Asciinema Player 组件"
|
||||
linktitle: "Asciinema Player"
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
|
||||
asciinema shortcode 允许你在 Hugo 站点中嵌入使用 [asciinema](https://asciinema.org/) 创建的终端录制。它提供了一个功能丰富的终端播放器，具有播放控制、速度调整和主题自定义等功能。
|
||||
|
||||
## 基本用法
|
||||
|
||||
asciinema shortcode 支持本地 `.cast` 文件和远程 URL。以下是使用本地文件的不同方法：
|
||||
|
||||
### 本地文件
|
||||
|
||||
**方法 1：Assets 目录（推荐）**
|
||||
将你的 cast 文件放在 Hugo 站点的 `assets/` 目录中：
|
||||
|
||||
```
|
||||
your-site/
|
||||
├── assets/
|
||||
│ └── demo.cast
|
||||
└── content/
|
||||
└── my-page.md
|
||||
```
|
||||
|
||||
在你的 markdown 文件中：
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
**方法 2：Static 目录**
|
||||
将你的 cast 文件放在 `static/` 目录中：
|
||||
|
||||
```
|
||||
your-site/
|
||||
├── static/
|
||||
│ └── demo.cast
|
||||
└── content/
|
||||
└── my-page.md
|
||||
```
|
||||
|
||||
在你的 markdown 文件中：
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
**方法 3：页面包**
|
||||
对于页面包，将 cast 文件与你的 markdown 文件放在一起：
|
||||
|
||||
```
|
||||
your-site/
|
||||
└── content/
|
||||
└── my-page/
|
||||
├── index.md
|
||||
└── demo.cast
|
||||
```
|
||||
|
||||
在你的 markdown 文件中：
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="casts/demo.cast" >}}
|
||||
|
||||
### 远程文件
|
||||
|
||||
你也可以使用来自任何远程 URL 的 cast 文件：
|
||||
|
||||
```markdown
|
||||
{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
|
||||
{{</* asciinema file="https://example.com/demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
|
||||
|
||||
### 文件查找机制
|
||||
|
||||
shortcode 会按以下顺序自动查找你的 cast 文件：
|
||||
1. **页面包资源**（如果使用页面包）
|
||||
2. **全局 assets 目录**（`assets/`）
|
||||
3. **Static 目录**（`static/`）
|
||||
4. **远程 URL**（如果路径以 `http://` 或 `https://` 开头）
|
||||
|
||||
如果找不到文件，Hugo 会显示有用的错误信息，告诉你应该将文件放在哪里。
|
||||
|
||||
## 高级演示
|
||||
|
||||
这是一个展示所有可用参数的高级示例：
|
||||
|
||||
```markdown
|
||||
{{</* asciinema
|
||||
file="demo.cast"
|
||||
theme="dracula"
|
||||
speed="2"
|
||||
autoplay="true"
|
||||
loop="true"
|
||||
markers="1.5:Installation,3.2:Configuration,5.8:Testing"
|
||||
*/>}}
|
||||
```
|
||||
|
||||
{{< asciinema
|
||||
file="casts/demo.cast"
|
||||
theme="dracula"
|
||||
speed="2"
|
||||
autoplay="true"
|
||||
loop="true"
|
||||
markers="1.5:Installation,3.2:Configuration,5.8:Testing"
|
||||
>}}
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 类型 | 默认值 | 描述 |
|
||||
|------|------|--------|------|
|
||||
| `file` | string | - | .cast 文件路径（必需）。支持本地文件、绝对路径和远程 URL |
|
||||
| `theme` | string | `"asciinema"` | 播放器主题 |
|
||||
| `speed` | number | `1` | 播放速度倍数 |
|
||||
| `autoplay` | boolean | `false` | 自动开始播放 |
|
||||
| `loop` | boolean | `false` | 循环播放 |
|
||||
| `poster` | string | `""` | 播放开始前显示的海报（预览帧）。支持 NPT 表示法（如 "npt:1:23"） |
|
||||
| `markers` | string | `""` | 逗号分隔的时间标记。格式："时间:标签" 或仅 "时间"（如 "1.5:Installation,3.2:Configuration,5.8"） |
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
title: کامپوننت Callout
|
||||
linkTitle: Callout
|
||||
aliases:
|
||||
- callouts
|
||||
prev: /docs/guide/shortcodes
|
||||
---
|
||||
|
||||
یک کامپوننت داخلی برای نمایش اطلاعات مهم به خواننده.
|
||||
|
||||
<!--more-->
|
||||
|
||||
> [!NOTE]
|
||||
> [هشدارهای سبک GitHub](../../markdown#alerts) از [نسخه 0.9.0](https://github.com/imfing/hextra/releases/tag/v0.9.0) پشتیبانی میشوند.
|
||||
> این ویژگی از سینتکس Markdown برای رندر کردن callout استفاده میکند که باعث بهبود قابلیت حمل و خوانایی محتوا میشود.
|
||||
|
||||
## أمثلة
|
||||
|
||||
{{< callout >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
{{< callout type="info" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
{{< callout type="warning" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
{{< callout type="error" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
{{< callout type="important" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
### تقصير
|
||||
|
||||
{{< callout >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout */>}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### Info
|
||||
|
||||
{{< callout type="info" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="info" */>}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### Warning
|
||||
|
||||
{{< callout type="warning" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="warning" */>}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### Error
|
||||
|
||||
{{< callout type="error" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="error" */>}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### Important
|
||||
|
||||
{{< callout type="important" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="important" */>}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### أيقونة مخصصة
|
||||
|
||||
{{< callout icon="sparkles" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout icon="sparkles" */>}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
{{< callout type="important" icon="sparkles" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="important" icon="sparkles" */>}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### الرموز التعبيرية
|
||||
|
||||
{{< callout emoji="🌐" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout emoji="🌐" */>}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
{{< callout type="info" emoji="ℹ️" >}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="info" emoji="ℹ️" */>}}
|
||||
**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
## خيارات
|
||||
|
||||
| المعلمة | وصف |
|
||||
|---------|---------------------------------------------------------------------|
|
||||
| `type` | نوع الاستدعاء. (افتراضي، `info`، `warning`، `error`) |
|
||||
| `emoji` | الرمز التعبيري الذي يظهر قبل المكالمة. |
|
||||
| `icon` | رمز تعبيري للنداء (مرتبط بالنوع أو يمكن أن يكون رمز تعبيري مخصصًا). |
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
title: コールアウトコンポーネント
|
||||
linkTitle: コールアウト
|
||||
aliases:
|
||||
- callouts
|
||||
prev: /docs/guide/shortcodes
|
||||
---
|
||||
|
||||
読者に重要な情報を表示するための組み込みコンポーネントです。
|
||||
|
||||
<!--more-->
|
||||
|
||||
> [!NOTE]
|
||||
> [GitHubスタイルのアラート](../../markdown#alerts)は[v0.9.0](https://github.com/imfing/hextra/releases/tag/v0.9.0)以降でサポートされています。
|
||||
> これはMarkdown構文を活用してコールアウトをレンダリングするため、コンテンツの移植性と可読性が向上します。
|
||||
|
||||
## 例
|
||||
|
||||
{{< callout >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
{{< callout type="info" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
{{< callout type="warning" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
{{< callout type="error" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
{{< callout type="important" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
### デフォルト
|
||||
|
||||
{{< callout >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout */>}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### Info
|
||||
|
||||
{{< callout type="info" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="info" */>}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### Warning
|
||||
|
||||
{{< callout type="warning" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="warning" */>}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### Error
|
||||
|
||||
{{< callout type="error" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="error" */>}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### Important
|
||||
|
||||
{{< callout type="important" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="important" */>}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### カスタムアイコン
|
||||
|
||||
{{< callout icon="sparkles" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout icon="sparkles" */>}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
{{< callout type="important" icon="sparkles" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="important" icon="sparkles" */>}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
### 絵文字
|
||||
|
||||
{{< callout emoji="🌐" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout emoji="🌐" */>}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
{{< callout type="info" emoji="ℹ️" >}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{< /callout >}}
|
||||
|
||||
```markdown
|
||||
{{</* callout type="info" emoji="ℹ️" */>}}
|
||||
**コールアウト** は注目を集めることを目的とした短いテキストです。
|
||||
{{</* /callout */>}}
|
||||
```
|
||||
|
||||
## オプション
|
||||
|
||||
| パラメータ | 説明 |
|
||||
|---------|---------------------------------------------|
|
||||
| `type` | コールアウトのタイプ。(デフォルト、`info`、`warning`、`error`) |
|
||||
| `emoji` | コールアウトの前に表示される絵文字。 |
|
||||
| `icon` | コールアウトの絵文字 (タイプに関連、またはカスタム絵文字にすることもできます)。 |
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user