From e6ea1ddda09214e8b5b3b685dc8219fb02eb5f19 Mon Sep 17 00:00:00 2001 From: Brooke Date: Fri, 3 May 2024 19:04:48 -0400 Subject: [PATCH] init example content --- .gitignore | 154 ++++++++++ .prettierrc | 0 README.md | 21 +- content/_index.md | 76 +++++ content/about/index.fa.md | 22 ++ content/about/index.md | 20 ++ content/about/index.zh-cn.md | 20 ++ content/blog/_index.fa.md | 10 + content/blog/_index.md | 10 + content/blog/_index.zh-cn.md | 10 + content/blog/markdown.fa.md | 166 +++++++++++ content/blog/markdown.md | 157 ++++++++++ content/blog/markdown.zh-cn.md | 137 +++++++++ content/docs/_index.fa.md | 41 +++ content/docs/_index.md | 41 +++ content/docs/_index.zh-cn.md | 40 +++ content/docs/advanced/_index.fa.md | 16 ++ content/docs/advanced/_index.md | 16 ++ content/docs/advanced/_index.zh-cn.md | 15 + content/docs/advanced/comments.fa.md | 39 +++ content/docs/advanced/comments.md | 39 +++ content/docs/advanced/comments.zh-cn.md | 39 +++ content/docs/advanced/customization.fa.md | 73 +++++ content/docs/advanced/customization.md | 73 +++++ content/docs/advanced/customization.zh-cn.md | 58 ++++ content/docs/advanced/multi-language.fa.md | 83 ++++++ content/docs/advanced/multi-language.md | 83 ++++++ content/docs/advanced/multi-language.zh-cn.md | 74 +++++ content/docs/getting-started.fa.md | 190 ++++++++++++ content/docs/getting-started.md | 192 +++++++++++++ content/docs/getting-started.zh-cn.md | 142 +++++++++ content/docs/guide/_index.fa.md | 23 ++ content/docs/guide/_index.md | 23 ++ content/docs/guide/_index.zh-cn.md | 22 ++ content/docs/guide/configuration.fa.md | 271 ++++++++++++++++++ content/docs/guide/configuration.md | 271 ++++++++++++++++++ content/docs/guide/configuration.zh-cn.md | 239 +++++++++++++++ content/docs/guide/deploy-site.fa.md | 162 +++++++++++ content/docs/guide/deploy-site.md | 164 +++++++++++ content/docs/guide/deploy-site.zh-cn.md | 164 +++++++++++ content/docs/guide/diagrams.fa.md | 53 ++++ content/docs/guide/diagrams.md | 53 ++++ content/docs/guide/diagrams.zh-cn.md | 53 ++++ content/docs/guide/latex.fa.md | 60 ++++ content/docs/guide/latex.md | 60 ++++ content/docs/guide/latex.zh-cn.md | 59 ++++ content/docs/guide/markdown.fa.md | 106 +++++++ content/docs/guide/markdown.md | 106 +++++++ content/docs/guide/markdown.zh-cn.md | 105 +++++++ content/docs/guide/organize-files.fa.md | 147 ++++++++++ content/docs/guide/organize-files.md | 148 ++++++++++ content/docs/guide/organize-files.zh-cn.md | 65 +++++ content/docs/guide/shortcodes/_index.fa.md | 21 ++ content/docs/guide/shortcodes/_index.md | 21 ++ content/docs/guide/shortcodes/_index.zh-cn.md | 19 ++ content/docs/guide/shortcodes/callout.fa.md | 78 +++++ content/docs/guide/shortcodes/callout.md | 79 +++++ .../docs/guide/shortcodes/callout.zh-cn.md | 78 +++++ content/docs/guide/shortcodes/cards.fa.md | 64 +++++ content/docs/guide/shortcodes/cards.md | 64 +++++ content/docs/guide/shortcodes/cards.zh-cn.md | 65 +++++ content/docs/guide/shortcodes/details.fa.md | 43 +++ content/docs/guide/shortcodes/details.md | 43 +++ .../docs/guide/shortcodes/details.zh-cn.md | 43 +++ content/docs/guide/shortcodes/filetree.fa.md | 36 +++ content/docs/guide/shortcodes/filetree.md | 34 +++ .../docs/guide/shortcodes/filetree.zh-cn.md | 33 +++ content/docs/guide/shortcodes/icon.fa.md | 47 +++ content/docs/guide/shortcodes/icon.md | 46 +++ content/docs/guide/shortcodes/icon.zh-cn.md | 46 +++ content/docs/guide/shortcodes/steps.fa.md | 42 +++ content/docs/guide/shortcodes/steps.md | 42 +++ content/docs/guide/shortcodes/steps.zh-cn.md | 42 +++ content/docs/guide/shortcodes/tabs.fa.md | 92 ++++++ content/docs/guide/shortcodes/tabs.md | 93 ++++++ content/docs/guide/shortcodes/tabs.zh-cn.md | 93 ++++++ content/docs/guide/syntax-highlighting.fa.md | 89 ++++++ content/docs/guide/syntax-highlighting.md | 89 ++++++ .../docs/guide/syntax-highlighting.zh-cn.md | 89 ++++++ content/showcase/index.fa.md | 20 ++ content/showcase/index.md | 77 +++++ content/showcase/index.zh-cn.md | 77 +++++ hugo.yaml | 4 +- 83 files changed, 6117 insertions(+), 3 deletions(-) create mode 100644 .prettierrc create mode 100644 content/_index.md create mode 100644 content/about/index.fa.md create mode 100644 content/about/index.md create mode 100644 content/about/index.zh-cn.md create mode 100644 content/blog/_index.fa.md create mode 100644 content/blog/_index.md create mode 100644 content/blog/_index.zh-cn.md create mode 100644 content/blog/markdown.fa.md create mode 100644 content/blog/markdown.md create mode 100644 content/blog/markdown.zh-cn.md create mode 100644 content/docs/_index.fa.md create mode 100644 content/docs/_index.md create mode 100644 content/docs/_index.zh-cn.md create mode 100644 content/docs/advanced/_index.fa.md create mode 100644 content/docs/advanced/_index.md create mode 100644 content/docs/advanced/_index.zh-cn.md create mode 100644 content/docs/advanced/comments.fa.md create mode 100644 content/docs/advanced/comments.md create mode 100644 content/docs/advanced/comments.zh-cn.md create mode 100644 content/docs/advanced/customization.fa.md create mode 100644 content/docs/advanced/customization.md create mode 100644 content/docs/advanced/customization.zh-cn.md create mode 100644 content/docs/advanced/multi-language.fa.md create mode 100644 content/docs/advanced/multi-language.md create mode 100644 content/docs/advanced/multi-language.zh-cn.md create mode 100644 content/docs/getting-started.fa.md create mode 100644 content/docs/getting-started.md create mode 100644 content/docs/getting-started.zh-cn.md create mode 100644 content/docs/guide/_index.fa.md create mode 100644 content/docs/guide/_index.md create mode 100644 content/docs/guide/_index.zh-cn.md create mode 100644 content/docs/guide/configuration.fa.md create mode 100644 content/docs/guide/configuration.md create mode 100644 content/docs/guide/configuration.zh-cn.md create mode 100644 content/docs/guide/deploy-site.fa.md create mode 100644 content/docs/guide/deploy-site.md create mode 100644 content/docs/guide/deploy-site.zh-cn.md create mode 100644 content/docs/guide/diagrams.fa.md create mode 100644 content/docs/guide/diagrams.md create mode 100644 content/docs/guide/diagrams.zh-cn.md create mode 100644 content/docs/guide/latex.fa.md create mode 100644 content/docs/guide/latex.md create mode 100644 content/docs/guide/latex.zh-cn.md create mode 100644 content/docs/guide/markdown.fa.md create mode 100644 content/docs/guide/markdown.md create mode 100644 content/docs/guide/markdown.zh-cn.md create mode 100644 content/docs/guide/organize-files.fa.md create mode 100644 content/docs/guide/organize-files.md create mode 100644 content/docs/guide/organize-files.zh-cn.md create mode 100644 content/docs/guide/shortcodes/_index.fa.md create mode 100644 content/docs/guide/shortcodes/_index.md create mode 100644 content/docs/guide/shortcodes/_index.zh-cn.md create mode 100644 content/docs/guide/shortcodes/callout.fa.md create mode 100644 content/docs/guide/shortcodes/callout.md create mode 100644 content/docs/guide/shortcodes/callout.zh-cn.md create mode 100644 content/docs/guide/shortcodes/cards.fa.md create mode 100644 content/docs/guide/shortcodes/cards.md create mode 100644 content/docs/guide/shortcodes/cards.zh-cn.md create mode 100644 content/docs/guide/shortcodes/details.fa.md create mode 100644 content/docs/guide/shortcodes/details.md create mode 100644 content/docs/guide/shortcodes/details.zh-cn.md create mode 100644 content/docs/guide/shortcodes/filetree.fa.md create mode 100644 content/docs/guide/shortcodes/filetree.md create mode 100644 content/docs/guide/shortcodes/filetree.zh-cn.md create mode 100644 content/docs/guide/shortcodes/icon.fa.md create mode 100644 content/docs/guide/shortcodes/icon.md create mode 100644 content/docs/guide/shortcodes/icon.zh-cn.md create mode 100644 content/docs/guide/shortcodes/steps.fa.md create mode 100644 content/docs/guide/shortcodes/steps.md create mode 100644 content/docs/guide/shortcodes/steps.zh-cn.md create mode 100644 content/docs/guide/shortcodes/tabs.fa.md create mode 100644 content/docs/guide/shortcodes/tabs.md create mode 100644 content/docs/guide/shortcodes/tabs.zh-cn.md create mode 100644 content/docs/guide/syntax-highlighting.fa.md create mode 100644 content/docs/guide/syntax-highlighting.md create mode 100644 content/docs/guide/syntax-highlighting.zh-cn.md create mode 100644 content/showcase/index.fa.md create mode 100644 content/showcase/index.md create mode 100644 content/showcase/index.zh-cn.md diff --git a/.gitignore b/.gitignore index e69de29..0c765b3 100644 --- a/.gitignore +++ b/.gitignore @@ -0,0 +1,154 @@ +### Hugo ### +# Generated files by hugo +/public/ +/resources/_gen/ +/assets/jsconfig.json +hugo_stats.json + +# Executable may be added to repository +hugo.exe +hugo.darwin +hugo.linux + +# Temporary lock file while building +/.hugo_build.lock + +### Node ### +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* +.pnpm-debug.log* + +# Diagnostic reports (https://nodejs.org/api/report.html) +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage +*.lcov + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules/ +jspm_packages/ + +# Snowpack dependency directory (https://snowpack.dev/) +web_modules/ + +# TypeScript cache +*.tsbuildinfo + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Optional stylelint cache +.stylelintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variable files +.env +.env.development.local +.env.test.local +.env.production.local +.env.local + +# parcel-bundler cache (https://parceljs.org/) +.cache +.parcel-cache + +# Next.js build output +.next +out + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and not Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# vuepress build output +.vuepress/dist + +# vuepress v2.x temp and cache directory +.temp + +# Docusaurus cache and generated files +.docusaurus + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port + +# Stores VSCode versions used for testing VSCode extensions +.vscode-test + +# yarn v2 +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* + +### Node Patch ### +# Serverless Webpack directories +.webpack/ + +# Optional stylelint cache + +# SvelteKit build / generate output +.svelte-kit diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..e69de29 diff --git a/README.md b/README.md index 07a2279..f130fe0 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,22 @@ # midtowndrafting.com -midtowndrafting.com \ No newline at end of file +### Start developing + +``` +git clone https://git.myco.systems/mycosystems/web.myco.systems.git +``` +``` +git fetch +``` +``` +git submodule update --init --recursive +``` + +Optionally we recommend installing prettier, the prettierrc file is preconfigured to use the go template plugin. + +``` +npm install --save-dev prettier prettier-plugin-go-template +``` + +# License: +[MIT](https://git.myco.systems/mycosystems/midtowndrafting.com/src/branch/main/LICENSE) \ No newline at end of file diff --git a/content/_index.md b/content/_index.md new file mode 100644 index 0000000..7c53d38 --- /dev/null +++ b/content/_index.md @@ -0,0 +1,76 @@ +--- +title: Hextra Theme +layout: hextra-home +--- + +{{< hextra/hero-badge >}} +
+ Free, open source + {{< icon name="arrow-circle-right" attributes="height=14" >}} +{{< /hextra/hero-badge >}} + +
+{{< hextra/hero-headline >}} + Build modern websites 
with Markdown and Hugo +{{< /hextra/hero-headline >}} +
+ +
+{{< hextra/hero-subtitle >}} + Fast, batteries-included Hugo theme 
for creating beautiful static websites +{{< /hextra/hero-subtitle >}} +
+ +
+{{< hextra/hero-button text="Get Started" link="docs" >}} +
+ +
+ +{{< 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 md:hx-aspect-[1.1/1] max-md:hx-min-h-[340px]" + image="images/hextra-doc.webp" + imageClass="hx-top-[40%] hx-left-[24px] hx-w-[180%] sm:hx-w-[110%] dark:hx-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 md:hx-aspect-[1.1/1] max-lg:hx-min-h-[340px]" + image="images/hextra-markdown.webp" + imageClass="hx-top-[40%] hx-left-[36px] hx-w-[180%] sm:hx-w-[110%] dark:hx-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 md:hx-aspect-[1.1/1] max-md:hx-min-h-[340px]" + image="images/hextra-search.webp" + imageClass="hx-top-[40%] hx-left-[36px] hx-w-[110%] sm:hx-w-[110%] dark:hx-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 >}} diff --git a/content/about/index.fa.md b/content/about/index.fa.md new file mode 100644 index 0000000..ceb6b83 --- /dev/null +++ b/content/about/index.fa.md @@ -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/) diff --git a/content/about/index.md b/content/about/index.md new file mode 100644 index 0000000..440a14e --- /dev/null +++ b/content/about/index.md @@ -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/) diff --git a/content/about/index.zh-cn.md b/content/about/index.zh-cn.md new file mode 100644 index 0000000..196fbce --- /dev/null +++ b/content/about/index.zh-cn.md @@ -0,0 +1,20 @@ +--- +title: 关于 +toc: false +--- + +Hextra 是一款简洁、快速、灵活的主题，适用于构建现代化静态站点。Hextra 特别适用于文档网站，但也可用于构建博客、个人网站等各种类型的网站。 + +Hugo 和 Jekyll 类似，是一个静态网站生成器。但与其他生成器不同，Hugo 只有单个可执行文件，这使得它可以轻松地在各种平台上安装和运行。Hugo 的运行速度非常快且可靠性高，能够在几毫秒内渲染数千页的网站。 + +Hextra 被设计为轻量级，具有最小化的内存占用。使用 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/) diff --git a/content/blog/_index.fa.md b/content/blog/_index.fa.md new file mode 100644 index 0000000..daf2cf6 --- /dev/null +++ b/content/blog/_index.fa.md @@ -0,0 +1,10 @@ +--- +title: "وبلاگ" +--- + +
+{{< hextra/hero-badge link="index.xml" >}} + خوراک RSS + {{< icon name="rss" attributes="height=14" >}} +{{< /hextra/hero-badge >}} +
diff --git a/content/blog/_index.md b/content/blog/_index.md new file mode 100644 index 0000000..b990665 --- /dev/null +++ b/content/blog/_index.md @@ -0,0 +1,10 @@ +--- +title: "Blog" +--- + +
+{{< hextra/hero-badge link="index.xml" >}} + RSS Feed + {{< icon name="rss" attributes="height=14" >}} +{{< /hextra/hero-badge >}} +
diff --git a/content/blog/_index.zh-cn.md b/content/blog/_index.zh-cn.md new file mode 100644 index 0000000..3389c28 --- /dev/null +++ b/content/blog/_index.zh-cn.md @@ -0,0 +1,10 @@ +--- +title: "博客" +--- + +
+{{< hextra/hero-badge link="index.xml" >}} + RSS 订阅 + {{< icon name="rss" attributes="height=14" >}} +{{< /hextra/hero-badge >}} +
diff --git a/content/blog/markdown.fa.md b/content/blog/markdown.fa.md new file mode 100644 index 0000000..7eb0697 --- /dev/null +++ b/content/blog/markdown.fa.md @@ -0,0 +1,166 @@ +--- +title: راهنمای استفاده سینتکس مارک‌داون +date: 2024-03-03 +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 +--- + +این مقاله نمونه‌ای از سینتکس ابتدایی مارک‌داون را آموزش می‌دهد، که می‌توانید در پرونده‌های محتوای Hugo استفاده کنید. + + +## سینتکس ابتدایی + +### سرتیترها + +``` +# سرتیتر ۱ +## سرتیتر ۲ +### سرتیتر ۳ +#### سرتیتر ۴ +##### سرتیتر ۵ +###### سرتیتر ۶ +``` + +## سرتیتر ۲ +### سرتیتر ۳ +#### سرتیتر ۴ +##### سرتیتر ۵ +###### سرتیتر ۶ + +### تاکید + +```text +*این متن کج خواهد بود* +_این متن هم کج خواهد بود_ + +**این متن توپر خواهد بود** +__این متن هم توپر خواهد بود__ + +_شما **می‌توانید** آنها را ترکیب کنید_ +``` + +*این متن کج خواهد بود* + +_این متن هم کج خواهد بود_ + +**این متن توپر خواهد بود** + +__این متن هم توپر خواهد بود__ + +_شما **می‌توانید** آنها را ترکیب کنید_ + +### فهرست‌ها + +#### مرتب نشده + +``` +* مورد ۱ +* مورد ۲ + * مورد ۱الف + * مورد ۲ب +``` + +* مورد ۱ +* مورد ۲ + * مورد ۱الف + * مورد ۲ب + +#### مرتب شده + +``` +1. مورد ۱ +2. مورد ۲ +3. مورد ۳ + 1. مورد ۳الف + 2. مورد ۳ب +``` + +1. مورد ۱ +2. مورد ۲ +3. مورد ۳ + 1. مورد ۳الف + 2. مورد ۳ب + +### عکس‌ها + +```markdown +![آرم گیت‌هاب](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png) +``` + +![آرم گیت‌هاب](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png) + +### پیوندها + +```markdown +[هیوگو](https://gohugo.io) +``` + +[هیوگو](https://gohugo.io) + +### بلوک نقل‌قول + +```markdown +همانطور که نیوتن گفت: + +> اگر فاصله دورتری را دیده‌ام با ایستادن بر شانه‌های غول‌ها بوده است. +``` + +> اگر فاصله دورتری را دیده‌ام با ایستادن بر شانه‌های غول‌ها بوده است. + +### کد درون‌خطی + +```markdown +`کد` درون‌خطی دارای `بک‌-تیک در اطراف` خود است. +``` + +`کد` درون‌خطی دارای `بک‌-تیک در اطراف` خود است. + +### بلوک‌های کد + +#### برجسته‌کردن سینتکس(Syntax) + +````markdown +```go +func main() { + fmt.Println("Hello World") +} +``` +```` + +```go +func main() { + fmt.Println("Hello World") +} +``` + +### جدول‌ها + +```markdown +| عنوان | توضیحات | +| --------- | ----------- | +| سرتیتر | عنوان | +| پاراگراف | متن | +``` + +| عنوان | توضیحات | +| --------- | ----------- | +| سرتیتر | عنوان | +| پاراگراف | متن | + +## منابع + +- [سینتکس مارک‌داون](https://www.markdownguide.org/basic-syntax/) +- [مارک‌داون هیوگو](https://gohugo.io/content-management/formats/#markdown) diff --git a/content/blog/markdown.md b/content/blog/markdown.md new file mode 100644 index 0000000..9831fa7 --- /dev/null +++ b/content/blog/markdown.md @@ -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. + + +## 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 +![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png) +``` + +![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png) + +### 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) diff --git a/content/blog/markdown.zh-cn.md b/content/blog/markdown.zh-cn.md new file mode 100644 index 0000000..ad414c8 --- /dev/null +++ b/content/blog/markdown.zh-cn.md @@ -0,0 +1,137 @@ +--- +title: Markdown 语法指南 +date: 2020-01-01 +authors: + - name: John Doe + link: https://example.com/johndoe +excludeSearch: true +--- + +这篇文章提供了一些基础的 Markdown 语法样例，这些可以在 Hugo 的内容文件中使用。 + + + +## 基础语法 + +### 标题 + +``` +# 一级标题 +## 二级标题 +### 三级标题 +#### 四级标题 +##### 五级标题 +###### 六级标题 +``` + +## 二级标题 +### 三级标题 +#### 四级标题 +##### 五级标题 +###### 六级标题 + +```text +*这段文字将是斜体* +_这也将是斜体_ + +**这段文字将是粗体** +__这也将是粗体__ + +_你 **可以** 组合它们_ +``` + +*这段文字将是斜体* +_这也将是斜体_ + +**这段文字将是粗体** +__这也将是粗体__ + +_你 **可以** 组合它们_ + +### 列表 + +#### 无序列表 + +* 项目 1 +* 项目 2 + * 项目 2a + * 项目 2b + +#### 有序列表 + +1. 项目 1 +2. 项目 2 +3. 项目 3 + 1. 项目 3a + 2. 项目 3b + +### 图片 + +```markdown +![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png) +``` + +![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png) + +### 链接 + +```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 +| Syntax | Description | +| --------- | ----------- | +| Header | Title | +| Paragraph | Text | +``` + +| Syntax | Description | +| --------- | ----------- | +| Header | Title | +| Paragraph | Text | + +## 参考 + +- [Markdown Syntax](https://www.markdownguide.org/basic-syntax/) +- [Hugo Markdown](https://gohugo.io/content-management/formats/#markdown) diff --git a/content/docs/_index.fa.md b/content/docs/_index.fa.md new file mode 100644 index 0000000..7e6483b --- /dev/null +++ b/content/docs/_index.fa.md @@ -0,0 +1,41 @@ +--- +linkTitle: "مستندات" +title: معرفی +--- + +👋 سلام! به مستندات هگزترا خوش آمدید! + + + +## هگزترا چیه؟ + +هگزترا یک تم [Hugo][hugo] مدرن و سریع است که با [Tailwind CSS][tailwind-css] ساخته شده است. + طراحی شده برای ساخت وب‌سایت‌های زیبا برای مستندات، وبلاگ‌ها و وب‌سایت‌ها، ویژگی‌های خارج از جعبه و انعطاف‌پذیری را برای پاسخگویی نیازهای مختلف فراهم می‌کند. + +## ویژگی‌ها + +- **طراحی زیبا** - با الهام از Nextra، هگزترا از Tailwind CSS برای ارائه یک طراحی مدرن که سایت شما را برجسته می‌کند، استفاده می‌کند. +- **طراحی واکنش‌گرا و حالت تیره** - در تمام دستگاه‌ها، از تلفن همراه، تبلت تا دسکتاپ، عالی به نظر می‌رسد. حالت تیره نیز برای انطباق با شرایط مختلف روشنایی پشتیبانی می‌شود. +- **سریع و سبک** - طراحی شده توسط Hugo، یک ایجادکننده سایت استاتیک سریع مثل رعد و برق که در یک فایل باینری قرار گرفته است، هگزترا ردپای خود را به حداقل می‌رساند. برای استفاده از آن به جاوااسکریپت یا Node.js نیازی ندارید. +- **جستجوی متن کامل** - جستجوی متن کاملا آفلاین داخلی طراحی شده توسط FlexSearch، بدون نیاز به پیکربندی اضافی. +- **امکانات کامل** - برای بهتر کردن محتوای شما مارک‌داون، برجسته‌کردن سینتکس، فرمول‌های ریاضی LaTeX، نمودارها و عناصر Shortcodeها را شامل میشه. فهرست مطالب، بردکرامب، صفحه‌بندی، پیمایش نوار کناری و موارد دیگر همه به صورت خودکار تولید می‌شوند. +- **چند زبانه و سئو آماده** - سایت‌های چند زبانه با حالت چند زبانه Hugo راحت ساخته می‌شوند. پشتیبانی خارج از جعبه برای برچسب‌های سئو، Open Graph و کارت‌های توییتر گنجانده شده است. + +## سوال یا بازخورد؟ + +{{< callout emoji="❓" >}} + هگزترا هنوز در حال توسعه است. + سوال یا بازخوردی دارید؟ با خیال راحت [یک موضوع را باز کنید](https://github.com/imfing/hextra/issues)! +{{< /callout >}} + +## بعدی + +برای شروع کردن به بخش زیر مراجعه کنید: + +{{< cards >}} + {{< card link="getting-started" title="شروع کنید" icon="document-text" subtitle="یادگیری نحوه ایجاد وب‌سایت با استفاده از هگزترا" >}} +{{< /cards >}} + +[hugo]: https://gohugo.io/ +[flex-search]: https://github.com/nextapps-de/flexsearch +[tailwind-css]: https://tailwindcss.com/ diff --git a/content/docs/_index.md b/content/docs/_index.md new file mode 100644 index 0000000..2e12fc5 --- /dev/null +++ b/content/docs/_index.md @@ -0,0 +1,41 @@ +--- +linkTitle: "Documentation" +title: Introduction +--- + +👋 Hello! Welcome to the Hextra documentation! + + + +## 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. + +## 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/ diff --git a/content/docs/_index.zh-cn.md b/content/docs/_index.zh-cn.md new file mode 100644 index 0000000..7915eac --- /dev/null +++ b/content/docs/_index.zh-cn.md @@ -0,0 +1,40 @@ +--- +linkTitle: "文档" +title: 介绍 +--- + +👋 你好！欢迎来到 Hextra 文档！ + + + +## Hextra 是什么？ + +Hextra 是一款现代、快速且内置丰富功能的 [Hugo][hugo] 主题，它是用 [Tailwind CSS][tailwind-css] 构建的。该主题旨在创建美观的文档、博客和网站，提供了开箱即用的功能和灵活性以满足各种需求。 + +## 功能特点 + +- **优美的设计** - 受到 Nextra 的启发，Hextra 利用 Tailwind CSS 提供了一种现代设计，使您的网站看起来出色。 +- **响应式布局和深色模式** - 无论是在移动设备、平板还是桌面上，都表现出色。同时支持深色模式以适应各种光线条件。 +- **快速和轻量级** - 由 Hugo 驱动，一个轻量级且超快的静态网站生成器，封装在一个单一的二进制文件中，Hextra 保持其占用极小。使用它不需要 Javascript 或 Node.js。 +- **全文搜索** - 内置的离线全文搜索由 FlexSearch 提供支持，无需额外配置。 +- **功能全面** - 支持 Markdown、语法高亮、LaTeX 数学公式、图表以及 Shortcodes 元素以增强您的内容。目录、面包屑、分页、侧边栏导航等都会自动生成。 +- **多语言和 SEO 支持** - Hugo 的多语言模式轻松支持多语言网站。对于 SEO 标签、Open Graph 和 Twitter 卡片，也提供了开箱即用的支持。 + +## 有问题或反馈？ + +{{< callout emoji="❓" >}} + Hextra 仍在积极开发中。 + 有问题或反馈？请随时[提出问题](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/ diff --git a/content/docs/advanced/_index.fa.md b/content/docs/advanced/_index.fa.md new file mode 100644 index 0000000..9bd6991 --- /dev/null +++ b/content/docs/advanced/_index.fa.md @@ -0,0 +1,16 @@ +--- +linkTitle: پیشرفته +title: موضوعات پیشرفته +prev: /docs/guide/shortcodes/steps +next: /docs/advanced/multi-language +--- + +این بخش برخی از موضوعات پیشرفته تم را پوشش می‌دهد. + + + +{{< cards >}} + {{< card link="multi-language" title="چند زبانه" icon="translate" >}} + {{< card link="customization" title="سفارشی‌سازی" icon="pencil" >}} + {{< card link="comments" title="سیستم نظردهی" icon="chat-alt" >}} +{{< /cards >}} diff --git a/content/docs/advanced/_index.md b/content/docs/advanced/_index.md new file mode 100644 index 0000000..cdcaed2 --- /dev/null +++ b/content/docs/advanced/_index.md @@ -0,0 +1,16 @@ +--- +linkTitle: Advanced +title: Advanced Topics +prev: /docs/guide/shortcodes/tabs +next: /docs/advanced/multi-language +--- + +This section covers some advanced topics of the theme. + + + +{{< 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" >}} +{{< /cards >}} diff --git a/content/docs/advanced/_index.zh-cn.md b/content/docs/advanced/_index.zh-cn.md new file mode 100644 index 0000000..f6f2061 --- /dev/null +++ b/content/docs/advanced/_index.zh-cn.md @@ -0,0 +1,15 @@ +--- +linkTitle: 高级配置 +title: 高级配置 +prev: /docs/guide/shortcodes/tabs +next: /docs/advanced/multi-language +--- + +此部分提供了 Hextra 的一些高级配置。 + + + +{{< cards >}} + {{< card link="multi-language" title="多语言" icon="translate" >}} + {{< card link="customization" title="定制化" icon="pencil" >}} +{{< /cards >}} diff --git a/content/docs/advanced/comments.fa.md b/content/docs/advanced/comments.fa.md new file mode 100644 index 0000000..852f402 --- /dev/null +++ b/content/docs/advanced/comments.fa.md @@ -0,0 +1,39 @@ +--- +title: سیستم نظردهی +linkTitle: نظردهی +--- + +هگزترا از افزودن سیستم نظردهی به سایت شما پشتیبانی می‌کند. + در حال حاضر [giscus](https://giscus.app/) پشتیبانی می‌شود. + + + +## 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: + category: + categoryId: +``` + +تنظیمات giscus را می توانید از وب‌سایت [giscus.app](https://giscus.app/) ساخت. جزئیات بیشتر را نیز می‌توانید در آنجا ببینید. + +دیدگاه‌ها را می‌توانید برای یک صفحه خاص در بالای همان صفحه فعال یا غیرفعال کرد: + +```yaml {filename="content/docs/about.md"} +--- +title: درباره ما +comments: true +--- +``` diff --git a/content/docs/advanced/comments.md b/content/docs/advanced/comments.md new file mode 100644 index 0000000..3327ee7 --- /dev/null +++ b/content/docs/advanced/comments.md @@ -0,0 +1,39 @@ +--- +title: Comments System +linkTitle: Comments +--- + +Hextra supports adding comments system to your site. +Currently [giscus](https://giscus.app/) is supported. + + + +## 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: + repoId: + category: + categoryId: +``` + +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 +--- +``` diff --git a/content/docs/advanced/comments.zh-cn.md b/content/docs/advanced/comments.zh-cn.md new file mode 100644 index 0000000..9a50658 --- /dev/null +++ b/content/docs/advanced/comments.zh-cn.md @@ -0,0 +1,39 @@ +--- +title: 评论系统 +linkTitle: Comments +--- + +Hextra 支持在你的网站中添加评论系统。 +目前已经支持 [giscus](https://giscus.app/). + + + +## giscus + +[giscus](https://giscus.app/) 是由 [GitHub Discussions](https://docs.github.com/en/discussions)驱动的评论系统。Giscus 免费并且开源。 + +如需启用 Giscus, 你需要在配置文件中添加以下内容： + +```yaml {filename="hugo.yaml"} +params: + comments: + enable: false + type: giscus + + giscus: + repo: + repoId: + category: + categoryId: +``` + +Giscus 配置可以参考 [giscus.app](https://giscus.app/)，还可以在那里找到更多详细信息。 + +可以在 front matter 中启用或禁用特定页面的评论： + +```yaml {filename="content/docs/about.md"} +--- +title: About +comments: true +--- +``` diff --git a/content/docs/advanced/customization.fa.md b/content/docs/advanced/customization.fa.md new file mode 100644 index 0000000..8c53065 --- /dev/null +++ b/content/docs/advanced/customization.fa.md @@ -0,0 +1,73 @@ +--- +title: سفارشی‌سازی هگزترا +linkTitle: سفارشی‌سازی +--- + +هگزترا برخی از گزینه‌های سفارشی‌سازی پیش‌فرض را در پرونده `hugo.yaml` برای پیکربندی تم ارائه می‌کند. + این صفحه گزینه‌های موجود و نحوه سفارشی‌سازی بیشتر تم را توضیح می‌دهد. + + + +## CSS سفارشی + +برای افزودن CSS سفارشی، باید یک پرونده `assets/css/custom.css` در سایت خود ایجاد کنیم. هگزترا به طور خودکار این پرونده را بارگیری خواهد کرد. + +### خانواده فونت + +خانواده فونت برای محتوا را می‌توانید با استفاده از این سفارشی کنید: + +```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` سفارشی کرد: + +```css {filename="assets/css/custom.css"} +:root { + --primary-hue: 100deg; + --primary-saturation: 90%; +} +``` + +### برجسته‌کردن سینتکس + +فهرست تم‌های برجسته‌کردن سینتکس در دسترس [گالری Chroma Styles](https://xyproto.github.io/splash/docs/all.html) موجود است. شیوه‌نامه را می‌توانید با استفاده از دستور زیر تولید کرد: + +```shell +hugo gen chromastyles --style=github +``` + +برای نادیده گرفتن طرح زمینه برجسته‌کردن سینتکس پیش‌فرض، می‌توانید استایل‌های تولید شده را به پرونده CSS سفارشی اضافه کنیم. + +## اسکریپت‌های سفارشی + +با افزودن پرونده زیر می‌توانید اسکریپت‌های سفارشی را برای هر صفحه به انتهای اون اضافه کنید: + +``` +layouts/partials/custom/head-end.html +``` + +## طرح‌بندی‌های سفارشی + +با ایجاد پرونده‌ای با همین نام در دایرکتوری `layouts` سایت خود، می‌توانید طرح‌های تم را نادیده بگیرید. + به عنوان مثال، برای لغو طرح‌بندی `single.html` برای مستندات، یک پرونده`layouts/docs/single.html` در سایت خود ایجاد کنید. + +برای اطلاعات بیشتر، به [Templateهای هیوگو](https://gohugo.io/templates/) مراجعه کنید. + +## سفارشی‌سازی بیشتر + +چیزی را که دنبالش بودید پیدا نکردید؟ با خیال راحت [بحثی را باز کنید](https://github.com/imfing/hextra/discussions) یا به موضوع کمک کنید! diff --git a/content/docs/advanced/customization.md b/content/docs/advanced/customization.md new file mode 100644 index 0000000..8821967 --- /dev/null +++ b/content/docs/advanced/customization.md @@ -0,0 +1,73 @@ +--- +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. + + + +## 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` and `--primary-saturation` variables: + +```css {filename="assets/css/custom.css"} +:root { + --primary-hue: 100deg; + --primary-saturation: 90%; +} +``` + +### 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 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](https://gohugo.io/templates/). + +## 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! diff --git a/content/docs/advanced/customization.zh-cn.md b/content/docs/advanced/customization.zh-cn.md new file mode 100644 index 0000000..bb3f9d7 --- /dev/null +++ b/content/docs/advanced/customization.zh-cn.md @@ -0,0 +1,58 @@ +--- +title: 自定义 Hextra +linkTitle: 自定义 +--- + +Hextra 在 `hugo.yaml` 中提供了一些自定义选项来配置主题。 +本页介绍了可用选项以及如何进一步自定义主题。 + + + +## 自定义 CSS + +要添加自定义 CSS，我们需要在站点中创建一个文件 `assets/css/custom.css`。Hextra 将自动加载该文件，比如自定义字体： + +```css {filename="assets/css/custom.css"} +.content { + font-family: "Times New Roman", Times, serif; +} +``` + +### 主题色 + +主题色可以通过设置 `--primary-hue` 变量来自定义： + +```css {filename="assets/css/custom.css"} +:root { + --primary-hue: 100deg; +} +``` + +### 代码高亮 + +代码高亮风格的详细信息可在 [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html) 中找到。可以使用以下命令生成样式表： + +```shell +hugo gen chromastyles --style=github +``` + +可将生成的样式添加到自定义 CSS 文件中以覆盖默认代码高亮样式。 + +## 自定义 Script + +你可以添加以下文件以自定义 `script` 添加到每页的 `head` 最后： + +``` +layouts/partials/custom/head-end.html +``` + +## 自定义布局 + +可以在站点的 `layouts` 目录中创建同名文件来覆盖主题的默认布局。 +例如，要覆盖文档的 `single.html` 布局，在站点中创建文件 `layouts/docs/single.html`。 + +如需或许更多信息，转至 [Hugo Templates](https://gohugo.io/templates/)。 + +## 进一步定制 Hextra + +没有找到你想修改的内容？在 GitHub 上[创建 Discussion](https://github.com/imfing/hextra/discussions) 或为 Hextra 贡献你的智慧！ diff --git a/content/docs/advanced/multi-language.fa.md b/content/docs/advanced/multi-language.fa.md new file mode 100644 index 0000000..37957a5 --- /dev/null +++ b/content/docs/advanced/multi-language.fa.md @@ -0,0 +1,83 @@ +--- +title: "چند زبانه" +weight: 1 +prev: /docs/advanced +--- + +هگزترا از ایجاد سایت با چندین زبان با استفاده از [حالت چند زبانه](https://gohugo.io/content-management/multilingual/) Hugo پشتیبانی می‌کند. + + + +## فعال‌سازی چند زبانه + +برای اینکه سایت ما چند زبانه شود، باید زبان‌های پشتیبانی شده را به Hugo بگوییم. باید به پرونده پیکربندی سایت اضافه کنیم: + +```yaml {filename="hugo.yaml"} +defaultContentLanguage: en +languages: + en: + languageName: English + weight: 1 + fa: + languageName: فارسی + weight: 2 + ja: + languageName: 日本語 + weight: 3 +``` + +## مدیریت ترجمه‌ها بر اساس نام پرونده + +Hugo از مدیریت ترجمه با نام پرونده پشتیبانی می‌کند. به عنوان مثال، اگر یک پرونده `content/docs/_index.md` به زبان انگلیسی داشته باشیم، می توانیم یک پرونده `content/docs/_index.fa.md` برای ترجمه فارسی ایجاد کنیم. + +{{< filetree/container >}} + {{< filetree/folder name="content" >}} + {{< filetree/folder name="docs" state="open" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/file name="_index.fa.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/fa.yaml"} +documentation: مستندات +blog: وبلاگ +``` + +## ترجمه رشته‌ها + +برای ترجمه رشته‌ها در مکان‌های دیگر، باید ترجمه را به پرونده i18n مربوطه اضافه کنیم: + +```yaml {filename="i18n/fa.yaml"} +readMore: ادامه مطلب +``` + +فهرستی از رشته‌های استفاده شده در تم را می‌توان در پرونده `i18n/en.yaml` پیدا کرد. + +## بیشتر بخوانید + +- [حالت چند زبانه هیوگو](https://gohugo.io/content-management/multilingual/) +- [هیوگو چند زبانه قسمت ۱: ترجمه محتوا](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/) +- [هیوگو چند زبانه قسمت ۲: بومی‌سازی رشته‌ها](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-2-i18n-string-localization/) diff --git a/content/docs/advanced/multi-language.md b/content/docs/advanced/multi-language.md new file mode 100644 index 0000000..963ee95 --- /dev/null +++ b/content/docs/advanced/multi-language.md @@ -0,0 +1,83 @@ +--- +title: "Multi-language" +weight: 1 +prev: /docs/advanced +--- + +Hextra supports creating site with multiple languages using Hugo's [multilingual mode](https://gohugo.io/content-management/multilingual/). + + + +## 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: + languageName: English + weight: 1 + fr: + languageName: Français + weight: 2 + ja: + languageName: 日本語 + weight: 3 +``` + +## 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/) diff --git a/content/docs/advanced/multi-language.zh-cn.md b/content/docs/advanced/multi-language.zh-cn.md new file mode 100644 index 0000000..ccf0246 --- /dev/null +++ b/content/docs/advanced/multi-language.zh-cn.md @@ -0,0 +1,74 @@ +--- +title: "多语言" +weight: 1 +prev: /docs/advanced +--- + +Hextra 支持使用 Hugo 的[多语言模式](https://gohugo.io/content-management/multilingual/) 创建多语言的网站。 + + + +## 启用多语言支持 + +为了使我们的网站支持多语言，我们需要告诉 Hugo 需要支持的语言。 在站点配置文件中添加： + +```yaml {filename="hugo.yaml"} +defaultContentLanguage: en +languages: + en: + languageName: English + weight: 1 + fr: + languageName: Français + weight: 2 + ja: + languageName: 日本語 + weight: 3 +``` + +## 按文件名管理翻译 + +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"} +readMore: Lire la suite +``` + +## 更多参考 + +- [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/) diff --git a/content/docs/getting-started.fa.md b/content/docs/getting-started.fa.md new file mode 100644 index 0000000..e2cc26a --- /dev/null +++ b/content/docs/getting-started.fa.md @@ -0,0 +1,190 @@ +--- +title: شروع کنید +weight: 1 +next: /docs/guide +prev: /docs +--- + +## شروع سریع از طریق Template + +{{< icon "github" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template) + +با استفاده از 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) ارائه کرده‌ایم که می‌تواند به ساخت و به‌کاراندازی خودکار سایت شما در گیت‌هاب Pages، برای میزبانی رایگان کمک کند. برای گزینه‌های بیشتر، [به‌کاراندازی سایت](../guide/deploy-site) را بررسی کنید. + +[🌐 نسخه‌ي نمایشی ↖](https://imfing.github.io/hextra-starter-template/) + +## شروع به عنوان پروژه جدید + +دو راه اصلی برای اضافه کردن تم هگزترا به پروژه Hugo وجود دارد: + +1. **ماژول‌های Hugo (توصیه می‌شود)**: ساده‌ترین و توصیه شده‌ترین. [ماژول‌های Hugo](https://gohugo.io/hugo-modules/) به شما امکان می‌دهند تم را مستقیما از منبع آنلاین آن وارد کنید. تم به صورت خودکار دانلود و توسط Hugo مدیریت می‌شود. +2. **ساب‌ماژول گیت**: در عوض، هگزترا را به عنوان یک [ساب‌ماژول گیت](https://git-scm.com/book/en/v2/Git-Tools-Submodules) اضافه کنید. تم توسط گیت دانلود شده و در پوشه `themes` پروژه شما ذخیره می‌شود. + +### هگزترا را به عنوان ماژول Hugo راه‌اندازی کنید + +#### پیش‌نیازها + +قبل از شروع، باید این نرم‌افزارها را نصب کنید: + +- [Hugo (extended version)](https://gohugo.io/installation/) +- [Git](https://git-scm.com/) +- [Go](https://go.dev/) + +#### مراحل + +{{% steps %}} + +### راه‌انداختن یک سایت جدید Hugo + +```shell +hugo new site my-site --format=yaml +``` + +### پیکربندی تم هگزترا از طریق ‌ماژول + +```shell +# مقداردهی اولیه ماژول هیوگو +cd my-site +hugo mod init github.com/username/my-site + +# افزودن تم هگزترا +hugo mod get github.com/imfing/hextra +``` + +با افزودن موارد زیر، `hugo.yaml` را برای استفاده از تم هگزترا پیکربندی کنید: + +```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 +``` + +برای به‌روزرسانی هگزترا به [آخرین نسخه منتشر شده](https://github.com/imfing/hextra/releases)، دستور زیر را اجرا کنید: + +```shell +hugo mod get -u github.com/imfing/hextra +``` + +برای جزئیات بیشتر به [ماژول‌های هیوگو](https://gohugo.io/hugo-modules/use-modules/#update-all-modules) مراجعه کنید. + +{{% /details %}} + +### هگزترا را به عنوان ساب‌ماژول Git راه‌اندازی کنید + +#### پیش‌نیازها + +قبل از شروع، باید این نرم‌افزارها را نصب کنید: + +- [Hugo (extended version)](https://gohugo.io/installation/) +- [Git](https://git-scm.com/) + +#### مراحل + +{{% steps %}} + +### راه‌انداختن یک سایت جدید Hugo + +```shell +hugo new site my-site --format=yaml +``` + +### افزودن تم هگزترا به عنوان یک ساب‌ماژول Git + +```shell +git submodule add https://github.com/imfing/hextra.git themes/hextra +``` + +با افزودن موارد زیر، `hugo.yaml` را برای استفاده از تم هگزترا پیکربندی کنید: + +```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 +``` + +اجرا نشدن این دستور باعث می‌شود که پوشه تم با پرونده‌های تم هگزترا پر نشود و منجر به خرابی ساخت شود. + + +{{% details title="چگونه تم را به‌روز کنیم؟" %}} + +برای به‌روزرسانی تمام ساب‌ماژول‌های در مخزن خود به آخرین commitها که موجود هست، دستور زیر را اجرا کنید: + +```shell +git submodule update --remote +``` + +برای به‌روزرسانی هگزترا به آخرین commit، دستور زیر را اجرا کنید: + +```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="مارک‌داون" icon="markdown" >}} +{{< /cards >}} diff --git a/content/docs/getting-started.md b/content/docs/getting-started.md new file mode 100644 index 0000000..e25ca5c --- /dev/null +++ b/content/docs/getting-started.md @@ -0,0 +1,192 @@ +--- +title: Getting Started +weight: 1 +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. + + + +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 +``` + +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 + +```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 >}} diff --git a/content/docs/getting-started.zh-cn.md b/content/docs/getting-started.zh-cn.md new file mode 100644 index 0000000..1e4c813 --- /dev/null +++ b/content/docs/getting-started.zh-cn.md @@ -0,0 +1,142 @@ +--- +title: 快速开始 +weight: 1 +next: /docs/guide +prev: /docs +--- + +## 使用模板快速开始 + +{{< icon "github" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template) + +通过使用上面的模板仓库，您将能够快速地开始。 + + + +我们提供了一个 [GitHub Actions 工作流](https://docs.github.com/cn/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)，它可以帮助您自动构建并部署您的网站到 GitHub Pages，并免费托管。 + +[🌐 演示 ↗](https://imfing.github.io/hextra-starter-template/) + +## 作为新项目开始 + +### 前提条件 + +在开始之前，请确保我们已经安装了 [Hugo](https://gohugo.io/)。 +请参考 Hugo 的[官方安装指南](https://gohugo.io/installation/)以获取更多详情。 + +[Hugo 模块](https://gohugo.io/hugo-modules/)是管理 Hugo 主题的推荐方式。要使用 Hugo 模块，我们需要安装 [Git](https://git-scm.com/) 和 [Go](https://go.dev/)。 + +### 初始化 Hugo 站点 + +```shell +hugo new site my-site --format=yaml +``` + +### 通过 Hugo Module 安装 + +```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 +``` + +### 通过 Git Submodule 安装 + +#### 先决条件 + +在我们开始之前，你必须先确保以下软件已经安装： + +- [Hugo (extended version)](https://gohugo.io/installation/) +- [Git](https://git-scm.com/) + +#### 步骤 + +{{% steps %}} + +### 初始化 Hugo 站点 + +```shell +hugo new site my-site --format=yaml +``` + +### 将 Hextra 添加为 Git Submodule + +```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` 命令之前执行以下命令。 + +```shell +git submodule update --init +``` + +如果不运行此命令，theme 中将不会存在 Hextra 文件，进而导致构建失败。 + + +{{% details title="如何更新主题？" %}} + +如需把项目中所有的 Hugo Modules 都升级到最新，在终端中运行此命令： + +```shell +hugo mod get -u +``` + +如需把 Hextra 升级到[最新的发行版本](https://github.com/imfing/hextra/releases), 在终端中运行此命令： + +```shell +hugo mod get -u github.com/imfing/hextra +``` + +如果你需要获得更多信息，参见 [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/#update-all-modules). + +{{% /details %}} + +## 接下来 + +探索这些文档以便添加更多内容： + +{{< 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 >}} diff --git a/content/docs/guide/_index.fa.md b/content/docs/guide/_index.fa.md new file mode 100644 index 0000000..f85d763 --- /dev/null +++ b/content/docs/guide/_index.fa.md @@ -0,0 +1,23 @@ +--- +title: راهنما +weight: 2 +prev: /docs/getting-started +next: /docs/guide/organize-files +sidebar: + open: true +--- + +برای یادگیری نحوه استفاده از هگزترا، بخش‌های زیر را کاوش کنید: + + + +{{< cards >}} + {{< card link="organize-files" title="سازماندهی پرونده‌ها" icon="document-duplicate" >}} + {{< card link="configuration" title="پیکربندی" icon="adjustments" >}} + {{< card link="markdown" title="مارک‌داون" 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 >}} diff --git a/content/docs/guide/_index.md b/content/docs/guide/_index.md new file mode 100644 index 0000000..2fd2a3f --- /dev/null +++ b/content/docs/guide/_index.md @@ -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: + + + +{{< 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 >}} diff --git a/content/docs/guide/_index.zh-cn.md b/content/docs/guide/_index.zh-cn.md new file mode 100644 index 0000000..c388146 --- /dev/null +++ b/content/docs/guide/_index.zh-cn.md @@ -0,0 +1,22 @@ +--- +title: 指南 +weight: 2 +prev: /docs/getting-started +next: /docs/guide/organize-files +sidebar: + open: true +--- + +探索以下各节以学习如何使用 Hextra 编写内容： + + + +{{< 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" >}} +{{< /cards >}} diff --git a/content/docs/guide/configuration.fa.md b/content/docs/guide/configuration.fa.md new file mode 100644 index 0000000..4b5ce34 --- /dev/null +++ b/content/docs/guide/configuration.fa.md @@ -0,0 +1,271 @@ +--- +title: پیکربندی +weight: 2 +--- + +Hugo پیکربندی خود را از `hugo.yaml` در ریشه سایت Hugo شما می‌خواند. + پرونده پیکربندی جایی است که می‌توانید تمام جنبه‌های سایت خود را پیکربندی کنید. + پرونده پیکربندی این سایت [`exampleSite/hugo.yaml`](https://github.com/imfing/hextra/blob/main/exampleSite/hugo.yaml) را در گیت‌هاب بررسی کنید تا ایده‌ای جامع از تنظیمات موجود و بهترین شیوه‌ها بدست آورید. + + + +## ناوبری + +### منو + +منوی سمت چپ بالا در قسمت `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: گیت‌هاب + weight: 5 + url: "https://github.com/imfing/hextra" + params: + icon: github +``` + +انواع مختلفی از آیتم‌های منو وجود دارد: + +1. پیوند به صفحه‌ای در سایت با `pageRef` + ```yaml + - name: مستندات + pageRef: /docs + ``` +2. پیوند به یک نشانی اینترنتی با `url` + ```yaml + - name: گیت‌هاب + url: "https://github.com" + ``` +3. نوار جستجو با `type: search` + ```yaml + - name: جستجو + params: + type: search + ``` +4. آیکون + ```yaml + - name: گیت‌هاب + params: + icon: github + ``` + +این آیتم‌های منو را می‌توانید با تنظیم پارامتر `weight` مرتب کنید. + +### آرم و عنوان + +برای تغییر آرم پیش‌فرض، `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 +``` + +## نوار کناری + +### نوار کناری اصلی + +برای نوار کناری اصلی، به طور خودکار از ساختار دایرکتوری محتوا تولید می‌شود. + برای جزئیات بیشتر به صفحه [سازماندهی پرونده‌ها](/fa/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: "مستندات هیوگو ↖" + 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" +``` + +پیوندهای ویرایش به طور خودکار برای هر صفحه براساس نشانی اینترنتی ارائه شده به عنوان دایرکتوری ریشه ایجاد می‌شود. + اگر می‌خواهید پیوند ویرایش را برای یک صفحه خاص تنظیم کنید، می‌توانید پارامتر `editURL` را در قسمت بالای صفحه تنظیم کنید: + +```yaml {filename="content/docs/guide/configuration.md"} +--- +title: پیکربندی +editURL: "https://example.com/edit/this/page" +--- +``` + +## پاورقی + +### کپی‌رایت + +برای تغییر متن کپی‌رایت نمایش داده شده در پاورقی وب‌سایت خود، باید پرونده‌ای به نام `i18n/fa.yaml` ایجاد کنید. + در این پرونده متن کپی‌رایت جدید خود را مطابق شکل زیر مشخص کنید: + +```yaml {filename="i18n/fa.yaml"} +copyright: "© ۲۰۲۴ متن شما در اینجا" +``` + +برای مرجع شما، یک مثال [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) را می‌توانید در مخزن گیت‌هاب پیدا کنید. علاوه بر این، می‌توانید از فرمت مارک‌داون در متن کپی‌رایت استفاده کنید. + +## سایر موارد + +### Favicon + +برای سفارشی کردن [favicon](https://en.wikipedia.org/wiki/Favicon) برای سایت خود، پرونده‌های آیکون را درون پوشه `static` قرار دهید تا [faviconهای پیش‌فرض در تم](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.ico` و `favicon.svg` را در پروژه خود قرار دهید، تا از نمایش صحیح faviconهای سایت خود مطمئن شوید. + +در حالی که `favicon.ico` به طور کلی برای مرورگرهای قدیمی‌تر است، `favicon.svg` توسط مرورگرهای مدرن پشتیبانی می‌شود. favicon`favicon-dark.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.page.width` در پرونده پیکربندی سفارشی کرد: + +```yaml {filename="hugo.yaml"} +params: + page: + # full (100%), wide (90rem), normal (1280px) + width: wide +``` + +سه گزینه در دسترس وجود دارد: `full`، `wide` و normal`. به طور پیش‌فرض، عرض صفحه روی normal` تنظیم شده است. + +به طور مشابه، عرض نوار ناوبری و پاورقی را می‌توان با پارامترهای `params.navbar.width` و `params.footer.width` سفارشی کرد. + +### فهرست جستجو + +جستجوی متن کامل توسط [FlexSearch](https://github.com/nextapps-de/flexsearch) پیاده‌سازی شده و به طور پیش‌فرض فعال است. + برای سفارشی کردن فهرست جستجو، پارامتر `params.search.flexsearch.index` را در پرونده پیکربندی تنظیم کنید: + +```yaml {filename="hugo.yaml"} +params: + # Search + search: + enable: true + type: flexsearch + + flexsearch: + # index page by: content | summary | heading | title + index: content +``` + +گزینه‌های `flexsearch.index`: + +- `content` - محتوای کامل صفحه (پیش‌فرض) +- `summary` - خلاصه صفحه، برای جزئیات بیشتر به [خلاصه مطالب Hugo](https://gohugo.io/content-management/summaries/) مراجعه کنید +- `heading` - سرتیترهای سطح ۱ و سطح ۲ +- `title` - فقط شامل عنوان صفحه است + +برای حذف یک صفحه از فهرست جستجو، `excludeSearch: true` را در قسمت بالای صفحه تنظیم کنید: + +```yaml {filename="content/docs/guide/configuration.md"} +--- +title: پیکربندی +excludeSearch: true +--- +``` + +### گوگل آنالیتیکس + +برای فعال کردن [گوگل آنالیتیکس](https://marketingplatform.google.com/about/analytics/)، پرچم `services.googleAnalytics.ID` را در `hugo.yaml` تنظیم کنید: + +```yaml {filename="hugo.yaml"} +services: + googleAnalytics: + ID: G-MEASUREMENT_ID +``` diff --git a/content/docs/guide/configuration.md b/content/docs/guide/configuration.md new file mode 100644 index 0000000..587d659 --- /dev/null +++ b/content/docs/guide/configuration.md @@ -0,0 +1,271 @@ +--- +title: Configuration +weight: 2 +--- + +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 [`exampleSite/hugo.yaml`](https://github.com/imfing/hextra/blob/main/exampleSite/hugo.yaml) on GitHub to get a comprehensive idea of available settings and best practices. + + + +## 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 + ```yaml + - name: GitHub + params: + icon: github + ``` + +These menu items can be sorted by setting the `weight` parameter. + +### 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 +``` + +## 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 +``` + +## 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 >}} + +Include both `favicon.ico` and `favicon.svg` files in your project to ensure your site's favicons display correctly. + +While `favicon.ico` is generally for older browsers, `favicon.svg` is supported by modern ones. The optional `favicon-dark.svg` can be included for a tailored experience in dark mode. +Feel free to use tools like [favicon.io](https://favicon.io/) or [favycon](https://github.com/ruisaraiva19/favycon) to generate these icons. + +### 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 Width + +The width of the page 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 +``` + +There are three available options: `full`, `wide`, and `normal`. By default, the page width is set to `normal`. + +Similarly, the width of the navbar and footer can be customized by the `params.navbar.width` and `params.footer.width` parameters. + +### Search 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 +``` + +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 exclude a page from the 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 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 +``` diff --git a/content/docs/guide/configuration.zh-cn.md b/content/docs/guide/configuration.zh-cn.md new file mode 100644 index 0000000..8ae2fd6 --- /dev/null +++ b/content/docs/guide/configuration.zh-cn.md @@ -0,0 +1,239 @@ +--- +title: 配置文件 +weight: 2 +--- + +Hugo 从 Hugo 网站根目录下的 `hugo.yaml` 读取配置。 +在配置文件中，您可以配置站点的所有选项。 +你可以在 `exampleSite/hugo.yaml` 中找到此站点的配置文件作为开始。 + + + +## 导航栏 + +### 菜单 + +右上角的菜单在配置文件的 `menu.main` 中配置： + +```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 +``` + +有几种不同类型的菜单项： + +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 + ```yaml + - name: GitHub + params: + icon: github + ``` + +这些菜单项可以通过设置 `weight` 进行排序。 + +## 侧边栏 + +### 主侧边栏 + +主侧边栏是自动从 `content` 目录结构生成的。 +有关更多详细信息，转至 [目录结构](/docs/guide/organize-files)。 + +### 额外链接 + +侧边栏的额外链接在配置文件的 `menu.sidebar` 部分中配置： + +```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 +``` + +## 右侧边栏 + +### 目录 + +目录是根据内容文件中的标题自动生成的，可以在 `front matter` 设置 `toc：false` 来禁用它。 + +```yaml {filename="content/docs/guide/configuration.md"} +--- +title: Configuration +toc: false +--- +``` + +### 编辑此页链接 + +要配置编辑此页链接，我们可以在配置文件中设置 `params.editURL.base`： +```yaml {filename="hugo.yaml"} +params: + editURL: + base: "https://github.com/your-username/your-repo/edit/main" +``` + +将为每个页面自动生成编辑链接。 +如需为特定页面设置编辑链接，可以在页面的 `front matter` 中设置 `editURL`： + +```yaml {filename="content/docs/guide/configuration.md"} +--- +title: Configuration +editURL: "https://example.com/edit/this/page" +--- +``` +## Footer + +### 版权声明 + +如需修改网站页脚中显示的版权文本，您需要创建一个名为“i18n/en.yaml”的文件。 +在此文件中，填写新的版权文本，像这样： + +```yaml {filename="i18n/en.yaml"} +copyright: "© 2024 YOUR TEXT HERE" +``` +你可以在 GitHub 存储库中找到示例 [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) 文件。另外，你可以在版权文本中使用 Markdown 格式。 + +## 其他 + +### Favicon + +如需自定义 [favicon](https://en.wikipedia.org/wiki/Favicon)，请将图标文件放在 `static` 文件夹下以覆盖 [主题中的默认 favicon](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.ico` 和 `favicon.svg` 文件，以确保网站的网站图标正确显示。 + +虽然 `favicon.ico` 通常适用于较旧的浏览器，但 `favicon.svg` 受到现代浏览器的支持，所以更现代的做法是添加 `favicon-dark.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.page.width`参数来调整： + +```yaml {filename="hugo.yaml"} +params: + page: + # full (100%), wide (90rem), normal (1280px) + width: wide +``` + +有三个可选项：`full`, `wide`, and `normal`. 默认的页宽模式是 `normal`. + +同样的，导航栏和 `footer` 的宽度也可通过 `params.navbar.width` 和 `params.footer.width` 调整。 + +### 搜索 + +默认情况下启用由 [FlexSearch](https://github.com/nextapps-de/flexsearch) 提供全文搜索。 +要自定义搜索索引，请在配置文件中设置 `params.search.flexsearch.index` ： + +```yaml {filename="hugo.yaml"} +params: + # Search + search: + enable: true + type: flexsearch + + flexsearch: + # index page by: content | summary | heading | title + index: content +``` +`flexsearch.index` 的可选项： + +- `content` - 全内容搜索 +- `summary` - 概述 [Hugo Content Summaries](https://gohugo.io/content-management/summaries/) +- `heading` - 一级和二级标题 +- `title` - 仅搜索标题 + +要从搜索索引中排除页面，更改 front matter 中的 `excludeSearch: true`: + +```yaml {filename="content/docs/guide/configuration.md"} +--- +title: Configuration +excludeSearch: true +--- +``` + +### Google Analytics + +要启用 [Google Analytics](https://marketingplatform.google.com/about/analytics/)，设置 `services.googleAnalytics.ID`: + +```yaml {filename="hugo.yaml"} +services: + googleAnalytics: + ID: G-MEASUREMENT_ID +``` diff --git a/content/docs/guide/deploy-site.fa.md b/content/docs/guide/deploy-site.fa.md new file mode 100644 index 0000000..4635993 --- /dev/null +++ b/content/docs/guide/deploy-site.fa.md @@ -0,0 +1,162 @@ +--- +title: به‌کاراندازی سایت +prev: /docs/guide/shortcodes +next: /docs/advanced +--- + +Hugo وب‌سایت‌های استاتیک را ایجاد می‌کند و امکان گزینه‌های میزبانی انعطاف‌پذیر را فراهم می‌کند. + این صفحه راهنماهایی برای به‌کاراندازی سایت هگزترا شما در پلتفرم‌های مختلف ارائه می‌کند. + + + + + +## گیت‌هاب Pages + +[گیت‌هاب Pages](https://docs.github.com/pages) روشی توصیه شده برای به‌کاراندازی و میزبانی وب‌سایت شما به صورت رایگان است. + +اگر سایت را با استفاده از [hextra-starter-template](https://github.com/imfing/hextra-starter-template) راه‌اندازی سریع پیاده‌سازی می‌کنید، گردش کار گیت‌هاب Actions را به صورت خارج از جعبه ارائه کرده‌ایم که به‌کاراندازی خودکار در گیت‌هاب Pages به شما کمک می‌کند. + +{{% details title="پیکربندی گیت‌هاب Actions" closed="true" %}} + +در زیر یک پیکربندی مثال از [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.117.0 + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + - name: Setup Go + uses: actions/setup-go@v4 + with: + go-version: '1.21' + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: '0.117.0' + extended: true + - name: Build with Hugo + env: + # For maximum backward compatibility with Hugo modules + HUGO_ENVIRONMENT: production + HUGO_ENV: production + run: | + hugo \ + --gc --minify \ + --baseURL "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/" + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + 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@v2 +``` + +{{% /details %}} + + +{{< callout >}} + در تنظیمات مخزن خود، **Pages** > **Build and deployment** > **Source** را روی **GitHub Actions** تنظیم کنید: + ![](https://user-images.githubusercontent.com/5097752/266784808-99676430-884e-42ab-b901-f6534a0d6eee.png) +{{< /callout >}} + +به‌طور پیش‌فرض، گردش کار گیت‌هاب 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` را بر این اساس تغییر دهید. + + +## کلودفلر Pages + +1. کد منبع سایت خود را در یک مخزن Git (به عنوان مثال گیت‌هاب) قرار دهید +2. وارد [پیشخوان کلودفلر](https://dash.cloudflare.com/) شوید و حساب خود را انتخاب کنید +3. در صفحه اصلی حساب‌کاربری، **Workers & Pages** > **Create application** > **Pages** > **Connect to Git** را انتخاب کنید +4. مخزن را انتخاب کنید و در بخش Set up builds and Deployments اطلاعات زیر را وارد کنید: + +| Configuration | Value | +| ----------------- | -------------------- | +| Production branch | `main` | +| Build command | `hugo --gc --minify` | +| Build directory | `public` | + +برای جزئیات بیشتر، بررسی کنید: +- [یک سایت هیوگو راه‌اندازی کنید.](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 خود (گیت‌هاب، گیت‌لب و غیره) ارسال کنید. +2. [وارد کردن پروژه](https://app.netlify.com/start) به Netlify +3. اگر از [hextra-starter-template][hextra-starter-template] استفاده نمی‌کنید، موارد زیر را به صورت دستی پیکربندی کنید: + - دستور Build را روی `hugo --gc --minify` پیکربندی کنید + - دایرکتوری Publish را برای `public` مشخص کنید + - `HUGO_VERSION` متغیر محیط استقرار را اضافه کنید و روی `0.119.0` تنظیم کنید +4. استقرار! + +برای جزئیات بیشتر [Hugo را در Netlify](https://docs.netlify.com/integrations/frameworks/hugo/) بررسی کنید. + + +## Vercel + +1. کد خود را به مخزن Git خود (گیت‌هاب، گیت‌لب و غیره) ارسال کنید. +2. به [پیشخوان Vercel](https://vercel.com/dashboard) بروید و پروژه Hugo خود را وارد کنید +3. پروژه را پیکربندی کنید، Hugo را به‌ عنوان چارچوب Preset انتخاب کنید +4. دستور Build و Install را لغو کنید: + 1. دستور Build را روی `hugo --gc --minify` تنظیم کنید + 2. دستور Install را روی `yum install golang` تنظیم کنید + +![پیکربندی استقرار Vercel](https://github.com/imfing/hextra/assets/5097752/887d949b-8d05-413f-a2b4-7ab92192d0b3) diff --git a/content/docs/guide/deploy-site.md b/content/docs/guide/deploy-site.md new file mode 100644 index 0000000..79d2079 --- /dev/null +++ b/content/docs/guide/deploy-site.md @@ -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. + + + + +## 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.121.2 + 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.21' + - 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 >}} + In your repository settings, set the **Pages** > **Build and deployment** > **Source** to **GitHub Actions**: + ![](https://user-images.githubusercontent.com/5097752/266784808-99676430-884e-42ab-b901-f6534a0d6eee.png) +{{< /callout >}} + +By default, the above GitHub Actions workflow `.github/workflows/pages.yaml` assumes that the site is deploying to `https://.github.io//`. + +If you are deploying to `https://.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.119.0` +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` + +![Vercel Deployment Configuration](https://github.com/imfing/hextra/assets/5097752/887d949b-8d05-413f-a2b4-7ab92192d0b3) diff --git a/content/docs/guide/deploy-site.zh-cn.md b/content/docs/guide/deploy-site.zh-cn.md new file mode 100644 index 0000000..590ee07 --- /dev/null +++ b/content/docs/guide/deploy-site.zh-cn.md @@ -0,0 +1,164 @@ +--- +title: 部署站点 +prev: /docs/guide/shortcodes +next: /docs/advanced +--- + +Hugo 生成静态站点，允许多种托管方式，你可以自由选择 +本页将给出部署你的 Hextra 站点的方法 + + + + +## 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 Configuration" closed="true" %}} + +以下是配置来自 [hextra-starter-template](https://github.com/imfing/hextra-starter-template) 的 Workflow 的示例： + +```yaml {filename=".github/workflows/pages.yaml"} +# 用于构建 Hugo 站点并将其部署到 GitHub Pages 的示例工作流程 +name: Deploy Hugo site to Pages + +on: + # 由默认分支触发 + push: + branches: ["main"] + + # 允许手动运行 + 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.121.2 + 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.21' + - 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 >}} + 在仓库设置中将 **Pages** > **Build and deployment** > **Source** 调整为 **GitHub Actions**: + ![](https://user-images.githubusercontent.com/5097752/266784808-99676430-884e-42ab-b901-f6534a0d6eee.png) +{{< /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 dashboard](https://dash.cloudflare.com/) 并选择你的账户 +3. 转至在账户主页面中 **Workers & Pages** > **Create application** > **Pages** > **Connect to Git** +4. 选择你的仓库 **Set up builds and deployments** 提供以下信息： + +| Configuration | Value | +| ----------------- | -------------------- | +| 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. [导入项目](https://app.netlify.com/start) +3. 如果您不使用[hextra-starter-template][hextra-starter-template], 手动配置以下内容： + - C 将构建命令配置为 `hugo --gc --minify` + - 指定发布目录为 `public` + - 添加环境变量 `HUGO_VERSION` 并设定为 `0.119.0` +4. 部署 + +转至 [Hugo on Netlify](https://docs.netlify.com/integrations/frameworks/hugo/) 获得更多信息 + + +## Vercel + +1. 将代码推送到 Git 存储库（GitHub、GitLab 等） +2. 转至 [Vercel Dashboard](https://vercel.com/dashboard) 并导入你的 Hugo 项目 +3. 配置项目，选择 Hugo 作为 Framework Preset +4. 覆盖构建命令和安装命令： + 1. 设置构建命令为 `hugo --gc --minify` + 2. 将安装命令设置为 `yum install golang` + +![Vercel Deployment Configuration](https://github.com/imfing/hextra/assets/5097752/887d949b-8d05-413f-a2b4-7ab92192d0b3) diff --git a/content/docs/guide/diagrams.fa.md b/content/docs/guide/diagrams.fa.md new file mode 100644 index 0000000..83fff71 --- /dev/null +++ b/content/docs/guide/diagrams.fa.md @@ -0,0 +1,53 @@ +--- +title: نمودارها +weight: 6 +next: /docs/guide/shortcodes +--- + +در حال حاضر، هگزترا از [Mermaid](#mermaid) برای نمودارها پشتیبانی می‌کند. + + + +## Mermaid + +[Mermaid](https://github.com/mermaid-js/mermaid#readme) یک ابزار نمودار و نمودار مبتنی بر جاوااسکریپت است که تعاریف متنی الهام گرفته از مارک‌داون را دریافت می‌کند و نمودارها را به صورت پویا در مرورگر ایجاد می‌کند. به عنوان مثال، Mermaid می‌تواند نمودارهای فلوچارت، نمودارهای توالی، نمودارهای دایره‌ای و موارد دیگر را رندر کند. + +استفاده از 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
prevail! + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! +``` + +برای اطلاعات بیشتر، لطفا به [مستندات Mermaid](https://mermaid-js.github.io/mermaid/#/) مراجعه کنید. diff --git a/content/docs/guide/diagrams.md b/content/docs/guide/diagrams.md new file mode 100644 index 0000000..2c54354 --- /dev/null +++ b/content/docs/guide/diagrams.md @@ -0,0 +1,53 @@ +--- +title: Diagrams +weight: 6 +next: /docs/guide/shortcodes +--- + +Currently, Hextra supports [Mermaid](#mermaid) for diagrams. + + + +## 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
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/#/). diff --git a/content/docs/guide/diagrams.zh-cn.md b/content/docs/guide/diagrams.zh-cn.md new file mode 100644 index 0000000..4f7e6af --- /dev/null +++ b/content/docs/guide/diagrams.zh-cn.md @@ -0,0 +1,53 @@ +--- +title: 图表 +weight: 6 +next: /docs/guide/shortcodes +--- + +目前，Hextra 支持 [Mermaid](#mermaid) 的图表。 + + + +## Mermaid + +[Mermaid](https://github.com/mermaid-js/mermaid#readme) 是一个基于 JavaScript 的图表绘制工具，它的文本定义和 Markdown 类似，可在浏览器中动态创建图表。例如：流程图、序列图、饼图等。 + +在 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; +``` + +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
prevail! + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! +``` + +如需获取更多信息，转至 [Mermaid Documentation](https://mermaid-js.github.io/mermaid/#/)。 diff --git a/content/docs/guide/latex.fa.md b/content/docs/guide/latex.fa.md new file mode 100644 index 0000000..e91d52e --- /dev/null +++ b/content/docs/guide/latex.fa.md @@ -0,0 +1,60 @@ +--- +title: "LaTeX" +weight: 4 +math: true +--- + +$\KaTeX$ برای رندر کردن عبارت‌های ریاضی LaTeX استفاده می‌شود. می‌توان آن را در هر صفحه با تنظیم `math` روی `true` در قسمت بالای صفحه فعال کرد. + + + +```yaml {filename="Markdown"} +--- +title: "صفحه من با LaTeX" +math: true +--- + +``` + +وقتی فعال باشد، اسکریپت‌ها، شیوه‌نامه‌ها و فونت‌های KaTeX به طور خودکار در سایت شما قرار می‌گیرند. می‌توانید از عبارت‌های ریاضی LaTeX در محتوای مارک‌داون خود استفاده کنید. + +## مثال + +هر دو عبارت‌های ریاضی درون‌خطی و پاراگراف جداگانه 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$$ + + +## توابع پشتیبانی شده + +برای مشاهده فهرست توابع پشتیبانی شده، به [توابع پشتیبانی شده KaTeX](https://katex.org/docs/supported.html) مراجعه کنید. + +## شیمی + +عبارت‌های شیمی از طریق افزونه [mhchem](https://mhchem.github.io/MathJax-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-}$$ diff --git a/content/docs/guide/latex.md b/content/docs/guide/latex.md new file mode 100644 index 0000000..2faef00 --- /dev/null +++ b/content/docs/guide/latex.md @@ -0,0 +1,60 @@ +--- +title: "LaTeX" +weight: 4 +math: true +--- + +$\KaTeX$ is used for rendering LaTeX math expressions. It can be enabled per page by setting `math` to `true` in the page front matter. + + + +```yaml {filename="Markdown"} +--- +title: "My Page with LaTeX" +math: true +--- + +``` + +When enabled, the scripts, stylesheets and fonts from KaTeX will be included automatically in your site. You can start using LaTeX math expressions in your Markdown content. + +## Example + +Both inline and separate paragraph LaTeX math expressions are supported in the Markdown content. + +### Inline + +```markdown {filename="page.md"} +This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline. +``` + +This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline. + +### Separate Paragraph + +```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$$ + + +## Supported Functions + +For a list of supported functions, see [KaTeX supported functions](https://katex.org/docs/supported.html). + +## Chemistry + +Chemistry expressions are supported via [mhchem](https://mhchem.github.io/MathJax-mhchem/) extension. + +Inline: $\ce{H2O}$ is water. + +Separate paragraph: + +```markdown {filename="page.md"} +$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$ +``` + +$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$ diff --git a/content/docs/guide/latex.zh-cn.md b/content/docs/guide/latex.zh-cn.md new file mode 100644 index 0000000..3f9441a --- /dev/null +++ b/content/docs/guide/latex.zh-cn.md @@ -0,0 +1,59 @@ +--- +title: "LaTeX 公式" +weight: 4 +math: true +--- + +$\KaTeX$ 用于呈现 LaTeX 数学表达式。可在 `frontmatter` 将 `math` 设置为 `true` 来启用。 + + + +```yaml {filename="Markdown"} +--- +title: "My Page with LaTeX" +math: true +--- +``` + +启用后，KaTeX 中的脚本，样式表和字体将自动包含在你的网站中。这样就可以在 Markdown 内容中使用 LaTeX 数学表达式。 + +## 示例 + +Markdown 内容支持行内和独立段落的 LaTeX 数学表达式。 + +### 行内 + +```markdown {filename="page.md"} +This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline. +``` + +This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline. + +### 独立段落 + +```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$$ + + +## 支持的功能 + +有关支持的符号列表，转至 [KaTeX 支持的公式](https://katex.org/docs/supported.html)。 + +## 化学表达式 + +通过 [mhchem](https://mhchem.github.io/MathJax-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-}$$ diff --git a/content/docs/guide/markdown.fa.md b/content/docs/guide/markdown.fa.md new file mode 100644 index 0000000..84e39ce --- /dev/null +++ b/content/docs/guide/markdown.fa.md @@ -0,0 +1,106 @@ +--- +title: مارک‌داون +weight: 2 +--- + +Hugo از سینتکس [مارک‌داون](https://en.wikipedia.org/wiki/Markdown) برای قالب‌بندی متن، ایجاد فهرست و موارد دیگر پشتیبانی می‌کند. این صفحه برخی از رایج‌ترین نمونه‌های سینتکس مارک‌داون را به شما نشان می‌دهد. + + + +## مثال‌های مارک‌داون + +### ظاهر طراحی دادن به متن + +| سبک | سینتکس | مثال | خروجی | +| -------- | -------- | ------ | ------ | +| توپر | `**متن توپر**` | `**متن توپر**` | **متن توپر** | +| کج | `*متن کج*` | `*متن کج*` | *متن کج* | +| خط خورده | `~~متن خط خورده~~` | `~~متن خط خورده~~` | ~~متن خط خورده~~ | +| پایین‌نویس | `` | `این یک متن پایین‌نویس است` | این یک متن پایین‌نویس است | +| بالانویس | `` | `این یک متن بالانویس است` | این یک متن بالانویس است | + +### بلوک نقل‌قول + +بلوک نقل‌قول با ذکر منبع + +> با اشتراک‌گذاری حافظه ارتباط برقرار نکنید، حافظه را با برقراری ارتباط به اشتراک بگذارید.
+> — راب پایک[^1] + +[^1]: نقل‌قول بالا گزیده‌ای از [سخنرانی](https://www.youtube.com/watch?v=PAAkCSZUG1c) راب پایک در Gopherfest، در تاریخ ۲۷ آبان ۱۳۹۴ است. + +### جدول‌ها + +جدول‌ها بخشی از مشخصات اصلی مارک‌داون نیستند، اما Hugo از آنها در خارج از جعبه پشتیبانی می‌کند. + + نام | سن +--------|------ + گودرز | ۳۰ + آصف | ۳۴ + +#### مارک‌داون درون‌خطی درون جدول‌ها + +| کج | توپر | کد | +| -------- | -------- | ------ | +| *کج* | **توپر** | `کد` | + +### بلوک‌های کد + +{{< cards >}} + {{< card link="../../guide/syntax-highlighting" title="برجسته‌کردن سینتکس" icon="sparkles" >}} +{{< /cards >}} + +### فهرست‌ها + +#### فهرست مرتب‌شده + +1. اولین آیتم +2. دومین آیتم +3. سومین آیتم + +#### فهرست مرتب‌نشده + +* فهرست آیتم +* یک آیتم دیگه +* و یک آیتم دیگه + +#### فهرست تو در تو + +* میوه + * سیب + * پرتقال + * موز +* لبنیات + * شیر + * پنیر + +### عکس‌ها + +![](https://source.unsplash.com/featured/800x600?landscape) + +با توضیحات: + +![](https://source.unsplash.com/featured/800x600?landscape "یک چشم‌انداز Unsplash") + +## پیکربندی + +Hugo از [Goldmark](https://github.com/yuin/goldmark) برای تجزیه مارک‌داون استفاده می‌کند. + رندر مارک‌داون را می‌توان در `hugo.yaml` تحت `markup.goldmark` پیکربندی کنید. + در زیر پیکربندی پیش‌فرض هگزترا را می‌توانید ببینید: + +```yaml {filename="hugo.yaml"} +markup: + goldmark: + renderer: + unsafe: true + highlight: + noClasses: false +``` + +برای گزینه‌های پیکربندی بیشتر، به مستندات Hugo در [پیکربندی نشانه‌گذاری](https://gohugo.io/getting-started/configuration-markup/) مراجعه کنید. + +## منابع یادگیری + +* [راهنمای مارک‌داون](https://www.markdownguide.org/) +* [برگه تقلب مارک‌داون](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) +* [آموزش مارک‌داون](https://www.markdowntutorial.com/) +* [مرجع مارک‌داون](https://commonmark.org/help/) diff --git a/content/docs/guide/markdown.md b/content/docs/guide/markdown.md new file mode 100644 index 0000000..740a3a2 --- /dev/null +++ b/content/docs/guide/markdown.md @@ -0,0 +1,106 @@ +--- +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. + + + +## 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 | `` | `This is a subscript text` | This is a subscript text | +| Superscript | `` | `This is a superscript text` | This is a superscript text | + +### Blockquotes + +Blockquote with attribution + +> Don't communicate by sharing memory, share memory by communicating.
+> — Rob Pike[^1] + +[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015. + +### Tables + +Tables aren't part of the core Markdown spec, but Hugo supports them out-of-the-box. + + Name | Age +--------|------ + Bob | 27 + Alice | 23 + +#### Inline Markdown within tables + +| 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 + +#### Unordered List + +* List item +* Another item +* And another item + +#### Nested list + +* Fruit + * Apple + * Orange + * Banana +* Dairy + * Milk + * Cheese + +### Images + +![](https://source.unsplash.com/featured/800x600?landscape) + +With caption: + +![](https://source.unsplash.com/featured/800x600?landscape "Unsplash Landscape") + +## 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/) diff --git a/content/docs/guide/markdown.zh-cn.md b/content/docs/guide/markdown.zh-cn.md new file mode 100644 index 0000000..5913a03 --- /dev/null +++ b/content/docs/guide/markdown.zh-cn.md @@ -0,0 +1,105 @@ +--- +title: Markdown +weight: 2 +--- + +Hugo 支持 [Markdown](https://en.wikipedia.org/wiki/Markdown) 来书写内容，创建列表等。本页将向你展示一些最常见的 Markdown 语法示例。 + + + +## Markdown 示例 + +### 文本样式 + +| 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 | `` | `This is a subscript text` | This is a subscript text | +| Superscript | `` | `This is a superscript text` | This is a superscript text | + +### 引用 + +带角标的块引用： + +> Don't communicate by sharing memory, share memory by communicating.
+> — Rob Pike[^1] + +[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015. + +### 表格 + +表格并非核心 Markdown 规范，但 Hugo 支持开箱即用的表格： + + Name | Age +--------|------ + Bob | 27 + Alice | 23 + +#### Markdown 表格中的内联 + +| Italics | Bold | Code | +| -------- | -------- | ------ | +| *italics* | **bold** | `code` | + +### 代码块 + +{{< cards >}} + {{< card link="../../guide/syntax-highlighting" title="Syntax Highlighting" icon="sparkles" >}} +{{< /cards >}} + +### 列表 + +#### 有序列表 + +1. First item +2. Second item +3. Third item + +#### 无序列表 + +* List item +* Another item +* And another item + +#### 嵌套列表 + +* Fruit + * Apple + * Orange + * Banana +* Dairy + * Milk + * Cheese + +### 图片 + +![](https://source.unsplash.com/featured/800x600?landscape) + +带有标题： + +![](https://source.unsplash.com/featured/800x600?landscape "Unsplash Landscape") + +## 配置 + +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 +``` + +如需了解更多选项，转至 [Configure Markup](https://gohugo.io/getting-started/configuration-markup/)。 + +## 参考资料 + +* [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/) diff --git a/content/docs/guide/organize-files.fa.md b/content/docs/guide/organize-files.fa.md new file mode 100644 index 0000000..e6eb50f --- /dev/null +++ b/content/docs/guide/organize-files.fa.md @@ -0,0 +1,147 @@ +--- +title: سازماندهی پرونده‌ها +weight: 1 +prev: /docs/guide +--- + +## ساختار دایرکتوری + +به طور پیش‌فرض، Hugo پرونده‌های مارک‌داون را در فهرست `content` جستجو می‌کند و ساختار فهرست، ساختار خروجی نهایی وب‌سایت شما را تعیین می‌کند. همین سایت را به عنوان مثال در نظر بگیرید: + + + +{{< 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` صفحه اصلی هر بخش هستند که برای هر بخش مجزا است. سایر پرونده‌های مارک‌داون صفحه‌های معمولی دیگه‌ای هستند. + +``` +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/ +``` + +## طرح‌بندی‌ها + +هگزترا سه طرح‌بندی برای انواع مختلف محتوا ارائه می‌کند: + +| طرح‌بندی | دایرکتوری | ویژگی‌ها | +| :-------- | :-------------------- | :--------------------------------------------------------------- | +| `docs` | `content/docs/` | ایده‌آل برای مستندات ساختار یافته، مانند این بخش. | +| `blog` | `content/blog/` | برای نوشته‌های وبلاگ، با هر فهرست‌بندی و هم نمایش جزئیات مقاله. | +| `default` | همه دایرکتوری‌های دیگر | مشاهده مقاله تک صفحه‌ای بدون نوار کناری. | + +برای سفارشی کردن یک بخش برای منعکس کردن رفتار یک طرح داخلی، نوع طرح‌بندی مورد نظر را در قسمت بالایی قسمت _index.md` مشخص کنید. + +```yaml {filename="content/my-docs/_index.md"} +--- +title: مستندات من +cascade: + type: docs +--- +``` + +پیکربندی مثال بالا تضمین می‌کند که پرونده‌های محتوای در داخل `content/my-docs/` به‌طور پیش‌فرض به عنوان مستندات (نوع `docs`) مورد استفاده قرار می‌گیرند. + +## ناوبری نوار کناری + +ناوبری نوار کناری به طور خودکار براساس حروف الفبا ایجاد می‌شود. برای پیکربندی دستی ترتیب نوار کناری، می‌توانید از پارامتر `weight` در قسمت بالایی پرونده‌های مارک‌داون استفاده کنید. + +```yaml {filename="content/docs/guide/_index.md"} +--- +title: راهنما +weight: 2 +--- +``` + +{{< callout emoji="ℹ️">}} + توصیه می‌کنیم نوار کناری خیلی عمیق نباشد. اگر محتوای زیادی دارید، آنها را **به چند بخش تقسیم کنید**. +{{< /callout >}} + +## پیکربندی دایرکتوری محتوا + +به طور پیش‌فرض، دایرکتوری ریشه `content/` توسط Hugo برای ساخت سایت استفاده می‌شود. + اگر نیاز به استفاده از دایرکتوری متفاوتی برای محتوا دارید، برای مثال `docs/`، این کار را می‌توانید با تنظیم پارامتر [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) در پیکربندی سایت `hugo.yaml` انجام دهید. + +## افزودن تصاویر + +برای افزودن تصاویر، ساده‌ترین راه این است که پرونده‌های عکس‌ها را در همان دایرکتوری پرونده مارک‌داون قرار دهید. +برای مثال، یک پرونده عکس `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 {filename="content/docs/my-page.md"} +![](image.png) +``` + +همچنین می‌توانید از ویژگی [بسته‌های صفحه][page-bundles] Hugo برای سازماندهی پرونده‌های عکس‌ها همراه با پرونده مارک‌داون استفاده کنید. برای رسیدن به این هدف، پرونده `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"} +![](image.png) +``` + +همچنین می‌توانید پرونده‌های عکس‌ها را در دایرکتوری `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 >}} + +توجه داشته باشید که مسیر عکس با یک اسلش `/` شروع می‌شود و نسبت به دایرکتوری استاتیک است: + +```markdown {filename="content/docs/my-page.md"} +![](/images/image.png) +``` + +[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles diff --git a/content/docs/guide/organize-files.md b/content/docs/guide/organize-files.md new file mode 100644 index 0000000..8c343ab --- /dev/null +++ b/content/docs/guide/organize-files.md @@ -0,0 +1,148 @@ +--- +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: + + + +{{< 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 emoji="ℹ️">}} + It is recommended to keep the sidebar not too deep. If you have a lot of content, consider **splitting them into multiple sections**. +{{< /callout >}} + +## 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"} +![](image.png) +``` + +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"} +![](image.png) +``` + +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"} +![](/images/image.png) +``` + +[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles diff --git a/content/docs/guide/organize-files.zh-cn.md b/content/docs/guide/organize-files.zh-cn.md new file mode 100644 index 0000000..d9d2c2d --- /dev/null +++ b/content/docs/guide/organize-files.zh-cn.md @@ -0,0 +1,65 @@ +--- +title: 目录结构 +weight: 1 +prev: /docs/guide +--- + +## 目录结构 + +默认情况下，Hugo 在 `context` 目录中搜索 Markdown 文件，目录的结构决定了网站的最终输出结构。 +以示例网站为例： + + + +{{< 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/ +``` + +## 侧边栏导航 + +侧边栏导航是根据内容组织的字母顺序自动生成的。要手动配置侧边栏顺序，可以在 Markdown 文件的 `frontmatter ` 中使用 `weight` 配置。 + +```yaml {filename="content/docs/guide/_index.md"} +--- +title: Guide +weight: 2 +--- +``` + +{{< callout emoji="ℹ️">}} + 建议侧边栏不要太深。如果内容太多，请考虑 **将它们分成多个部分**。 +{{< /callout >}} + +## 配置内容目录 + +如果需要为的内容使用不同的目录，可以在站点配置文件中设置 [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) 来实现。 diff --git a/content/docs/guide/shortcodes/_index.fa.md b/content/docs/guide/shortcodes/_index.fa.md new file mode 100644 index 0000000..9c335d1 --- /dev/null +++ b/content/docs/guide/shortcodes/_index.fa.md @@ -0,0 +1,21 @@ +--- +title: کدهای کوتاه +weight: 9 +prev: /docs/guide/diagrams +next: /docs/guide/shortcodes/filetree +--- + +[کدهای کوتاه Hugo](https://gohugo.io/content-management/shortcodes/) قطعه‌های ساده‌ای در داخل پرونده‌های محتوای شما هستند که قالب‌های داخلی یا سفارشی را فراخوانی می‌کنند. + +هگزترا مجموعه‌ای از کدهای کوتاه زیبا را برای بهبود محتوای شما ارائه می‌کند. + + +{{< cards >}} + {{< card link="filetree" title="FileTree" icon="folder-tree" >}} + {{< card link="icon" title="آیکون" icon="badge-check" >}} + {{< card link="details" title="جزئیات" icon="chevron-right" >}} + {{< card link="tabs" title="زبانه‌ها" icon="collection" >}} + {{< card link="callout" title="فراخوانی" icon="warning" >}} + {{< card link="cards" title="کارت‌ها" icon="card" >}} + {{< card link="steps" title="مراحل" icon="one" >}} +{{< /cards >}} diff --git a/content/docs/guide/shortcodes/_index.md b/content/docs/guide/shortcodes/_index.md new file mode 100644 index 0000000..bc909f1 --- /dev/null +++ b/content/docs/guide/shortcodes/_index.md @@ -0,0 +1,21 @@ +--- +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="icon" title="Icon" icon="badge-check" >}} + {{< card link="steps" title="Steps" icon="one" >}} + {{< card link="tabs" title="Tabs" icon="collection" >}} +{{< /cards >}} diff --git a/content/docs/guide/shortcodes/_index.zh-cn.md b/content/docs/guide/shortcodes/_index.zh-cn.md new file mode 100644 index 0000000..79ab159 --- /dev/null +++ b/content/docs/guide/shortcodes/_index.zh-cn.md @@ -0,0 +1,19 @@ +--- +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="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 >}} diff --git a/content/docs/guide/shortcodes/callout.fa.md b/content/docs/guide/shortcodes/callout.fa.md new file mode 100644 index 0000000..96a6a83 --- /dev/null +++ b/content/docs/guide/shortcodes/callout.fa.md @@ -0,0 +1,78 @@ +--- +title: کامپوننت فراخوانی +linkTitle: فراخوانی +aliases: +- فراخوانی‌ها +--- + +یک کامپوننت داخلی برای نشان دادن اطلاعات مهم به خواننده. + + + +## مثال + +{{< callout emoji="👾">}} + **فراخوانی** یک متن کوتاه است که برای جلب توجه در نظر گرفته شده است. +{{< /callout >}} + +{{< callout type="info" >}} + **فراخوانی** یک متن کوتاه است که برای جلب توجه در نظر گرفته شده است. +{{< /callout >}} + +{{< callout type="warning" >}} + **فراخوانی** یک متن کوتاه است که برای جلب توجه در نظر گرفته شده است. +{{< /callout >}} + +{{< callout type="error" >}} + **فراخوانی** یک متن کوتاه است که برای جلب توجه در نظر گرفته شده است. +{{< /callout >}} + +## استفاده + +### پیش‌فرض + +{{< callout emoji="🌐">}} + Hugo را می‌توانید برای ایجاد طیف گسترده‌ای از وب‌سایت‌ها، از جمله وبلاگ‌ها، نمونه‌کارها، سایت‌های مستندسازی و غیره استفاده کرد. +{{< /callout >}} + +```markdown +{{}} + Hugo را می‌توانید برای ایجاد طیف گسترده‌ای از وب‌سایت‌ها، از جمله وبلاگ‌ها، نمونه‌کارها، سایت‌های مستندسازی و غیره استفاده کرد. +{{}} +``` + +### اطلاعات + +{{< callout type="info" >}} + لطفا برای مشاهده آخرین نسخه‌ها به گیت‌هاب مراجعه کنید. +{{< /callout >}} + +```markdown +{{}} + لطفا برای مشاهده آخرین نسخه‌ها به گیت‌هاب مراجعه کنید. +{{}} +``` + +### هشدار + +{{< callout type="warning" >}} + این API در نسخه بعدی منسوخ خواهد شد. +{{< /callout >}} + +```markdown +{{}} + این API در نسخه بعدی منسوخ خواهد شد. +{{}} +``` + +### خطا + +{{< callout type="error" >}} + مشکلی پیش آمد و اتفاقی رخ خواهد شد. +{{< /callout >}} + +```markdown +{{}} + مشکلی پیش آمد و اتفاقی رخ خواهد شد. +{{}} +``` diff --git a/content/docs/guide/shortcodes/callout.md b/content/docs/guide/shortcodes/callout.md new file mode 100644 index 0000000..3bd3513 --- /dev/null +++ b/content/docs/guide/shortcodes/callout.md @@ -0,0 +1,79 @@ +--- +title: Callout Component +linkTitle: Callout +aliases: +- callouts +prev: /docs/guide/shortcodes +--- + +A built-in component to show important information to the reader. + + + +## Example + +{{< callout emoji="👾">}} + A **callout** is a short piece of text intended to attract attention. +{{< /callout >}} + +{{< callout type="info" >}} + A **callout** is a short piece of text intended to attract attention. +{{< /callout >}} + +{{< callout type="warning" >}} + A **callout** is a short piece of text intended to attract attention. +{{< /callout >}} + +{{< callout type="error" >}} + A **callout** is a short piece of text intended to attract attention. +{{< /callout >}} + +## Usage + +### Default + +{{< callout emoji="🌐">}} + Hugo can be used to create a wide variety of websites, including blogs, portfolios, documentation sites, and more. +{{< /callout >}} + +```markdown +{{}} + Hugo can be used to create a wide variety of websites, including blogs, portfolios, documentation sites, and more. +{{}} +``` + +### Info + +{{< callout type="info" >}} + Please visit GitHub to see the latest releases. +{{< /callout >}} + +```markdown +{{}} + Please visit GitHub to see the latest releases. +{{}} +``` + +### Warning + +{{< callout type="warning" >}} + This API will be deprecated in the next version. +{{< /callout >}} + +```markdown +{{}} + A **callout** is a short piece of text intended to attract attention. +{{}} +``` + +### Error + +{{< callout type="error" >}} + Something went wrong and it's going to explode. +{{< /callout >}} + +```markdown +{{}} + Something went wrong and it's going to explode. +{{}} +``` diff --git a/content/docs/guide/shortcodes/callout.zh-cn.md b/content/docs/guide/shortcodes/callout.zh-cn.md new file mode 100644 index 0000000..74cf41d --- /dev/null +++ b/content/docs/guide/shortcodes/callout.zh-cn.md @@ -0,0 +1,78 @@ +--- +title: 标注 +aliases: +- callouts +prev: /docs/guide/shortcodes +--- + +向读者显示重要信息的内置组件。 + + + +## Example + +{{< callout emoji="👾">}} + **标注**是一段旨在吸引注意力的短文本 +{{< /callout >}} + +{{< callout type="info" >}} + **标注**是一段旨在吸引注意力的短文本。 +{{< /callout >}} + +{{< callout type="warning" >}} + **标注**是一段旨在吸引注意力的短文本。 +{{< /callout >}} + +{{< callout type="error" >}} + **标注**是一段旨在吸引注意力的短文本。 +{{< /callout >}} + +## Usage + +### Default + +{{< callout emoji="🌐">}} + Hugo 可用于创建各种网站，包括博客、作品集、文档网站等 +{{< /callout >}} + +```markdown +{{}} + Hugo 可用于创建各种网站，包括博客、作品集、文档网站等 +{{}} +``` + +### Info + +{{< callout type="info" >}} + 请访问 GitHub 查看最新版本 +{{< /callout >}} + +```markdown +{{}} + 请访问 GitHub 查看最新版本 +{{}} +``` + +### Warning + +{{< callout type="warning" >}} + 该 API 将在下一版本中弃用 +{{< /callout >}} + +```markdown +{{}} + **标注**是一段旨在吸引注意力的简短文字 +{{}} +``` + +### Error + +{{< callout type="error" >}} + 出问题了，要爆炸了 +{{< /callout >}} + +```markdown +{{}} + 出问题了，要爆炸了 +{{}} +``` diff --git a/content/docs/guide/shortcodes/cards.fa.md b/content/docs/guide/shortcodes/cards.fa.md new file mode 100644 index 0000000..6810bfa --- /dev/null +++ b/content/docs/guide/shortcodes/cards.fa.md @@ -0,0 +1,64 @@ +--- +title: کامپوننت کارت‌ها +linkTitle: کارت‌ها +--- + +## مثال + +{{< cards >}} + {{< card link="../callout" title="فراخوانی" icon="warning" >}} + {{< card link="/fa" title="بدون آیکون" >}} +{{< /cards >}} + +{{< cards >}} + {{< card link="/" title="کارت تصویر" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="یک چشم‌انداز Unsplash" >}} + {{< card link="/" title="تصویر محلی" image="/images/card-image-unprocessed.jpg" subtitle="تصویر خام در دایرکتوری استاتیک است." >}} + {{< card link="/" title="تصویر محلی" image="images/space.jpg" subtitle="تصویر در دایرکتوری assets می‌باشد و پردازش توسط Hugo شده است." method="Resize" options="600x q80 webp" >}} +{{< /cards >}} + +## استفاده + +``` +{{}} + {{}} + {{}} +{{}} +``` + +``` +{{}} + {{}} + {{}} + {{}} +{{}} +``` + +## پارامترهای کارت + +| پارامتر | توضیحات | +|----------- |---------------------------------------| +| `link` | نشانی اینترنتی (داخلی یا خارجی). | +| `title` | عنوان برای کارت. | +| `subtitle` | عنوان زیرنویس (از مارک‌داون پشتیبانی می‌کند).. | +| `icon` | نام آیکون. | + +## کارت تصویر + +علاوه بر این، کارت از افزودن تصویر و پردازش از طریق این پارامترها پشتیبانی می‌کند: + +| پارامتر | توضیحات | +|----------- |---------------------------------------------| +| `image` | نشانی اینترنتی تصویر کارت را مشخص می‌کند. | +| `method` | روش پردازش تصویر Hugo را تنظیم می‌کند. | +| `options` | گزینه‌های پردازش تصویر Hugo را پیکربندی می‌کند. | + +کارت از سه نوع تصویر پشتیبانی می‌کند: + +1. تصویر از راه دور: نشانی اینترنتی کامل در پارامتر `image`. +2. تصویر استاتیک: از مسیر نسبی در دایرکتوری `static/` Hugo استفاده کنید. +3. تصویر پردازش شده: از مسیر نسبی در دایرکتوری `assets/` Hugo استفاده کنید. + +هگزترا در صورت نیاز به پردازش تصویر در حین ساخت، به طور خودکار تشخیص می‌دهد و پارامتر `options` یا تنظیمات پیش‌فرض را اعمال می‌کند (تغییر اندازه، 800x، کیفیت 80، فرمت WebP). + در حال حاضر این `method` را پشتیبانی می‌کند: `Resize`، `Fit`، `Fill` و `Crop`. + +برای اطلاعات بیشتر در مورد دستورات، روش‌ها و گزینه‌های پردازش تصویر داخلی Hugo به [مستندات پردازش تصویر](https://gohugo.io/content-management/image-processing/) آن‌ها مراجعه کنید. diff --git a/content/docs/guide/shortcodes/cards.md b/content/docs/guide/shortcodes/cards.md new file mode 100644 index 0000000..9833ebf --- /dev/null +++ b/content/docs/guide/shortcodes/cards.md @@ -0,0 +1,64 @@ +--- +title: Cards Component +linkTitle: Cards +--- + +## Example + +{{< cards >}} + {{< card link="../callout" title="Callout" icon="warning" >}} + {{< card link="/" title="No Icon" >}} +{{< /cards >}} + +{{< cards >}} + {{< card link="/" title="Image Card" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash Landscape" >}} + {{< card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." >}} + {{< card link="/" title="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" >}} +{{< /cards >}} + +## Usage + +``` +{{}} + {{}} + {{}} +{{}} +``` + +``` +{{}} + {{}} + {{}} + {{}} +{{}} +``` + +## Card Parameters + +| Parameter | Description | +|----------- |---------------------------------------| +| `link` | URL (internal or external). | +| `title` | Title heading for the card. | +| `subtitle` | Subtitle heading (supports Markdown). | +| `icon` | Name of the icon. | + +## Image Card + +Additionally, the card supports adding image and processing through these parameters: + +| Parameter | Description | +|----------- |---------------------------------------------| +| `image` | Specifies the image URL for the card. | +| `method` | Sets Hugo's image processing method. | +| `options` | Configures Hugo's image processing options. | + +Card supports three kinds of images: + +1. Remote image: the full URL in the `image` parameter. +2. Static image: use the relative path in Hugo's `static/` directory. +3. Processed image: use the relative path in Hugo's `assets/` directory. + +Hextra auto-detects if image processing is needed during build and applies the `options` parameter or default settings (Resize, 800x, Quality 80, WebP Format). +It currently supports these `method`: `Resize`, `Fit`, `Fill` and `Crop`. + +For more on Hugo's built in image processing commands, methods, and options see their [Image Processing Documentation](https://gohugo.io/content-management/image-processing/). diff --git a/content/docs/guide/shortcodes/cards.zh-cn.md b/content/docs/guide/shortcodes/cards.zh-cn.md new file mode 100644 index 0000000..8a88be1 --- /dev/null +++ b/content/docs/guide/shortcodes/cards.zh-cn.md @@ -0,0 +1,65 @@ +--- +title: 卡片 +linkTitle: Cards +--- + +## 示例 + +{{< cards >}} + {{< card link="../callout" title="Callout" icon="warning" >}} + {{< card link="/" title="No Icon" >}} +{{< /cards >}} + +{{< cards >}} + {{< card link="/" title="Image Card" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash Landscape" >}} + {{< card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." >}} + {{< card link="/" title="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" >}} +{{< /cards >}} + +## 使用 + +``` +{{}} + {{}} + {{}} +{{}} +``` + +``` +{{}} + {{}} + {{}} + {{}} +{{}} +``` + +## 卡片参数 + +| Parameter | Description | +|----------- |---------------------------------------| +| `link` | URL（内部或外部） | +| `title` | 卡片的标题 | +| `subtitle` | 字幕标题（支持 Markdown） | +| `icon` | 图标的名称 | + +## Image Card + +此外，该卡还支持通过以下参数添加图像和处理： + +| Parameter | Description | +|----------- |---------------------------------------------| +| `image` | 指定卡片的图像 URL. | +| `method` | 设置 Hugo 的图像处理方法。 | +| `options` | 配置 Hugo 的图像处理选项。| + +卡片支持三种图像： + +1. 远程图片：完整网址应放置在 image 参数中 +2. 静态图片：使用 Hugo 的 static/ 目录中的相对路径 +3. 处理过的图片：使用 Hugo 的 assets/ 目录中的相对路径 + +Hextra 在构建过程中会自动检测图片是否需要处理，并根据需要应用 options 参数或默认设置（缩放，800x，质量 80，WebP 格式）。 + +它目前支持以下处理方法：Resize（缩放）、Fit（适应）、Fill（填充）和 Crop（裁剪）。 + +有关 Hugo 内置图像处理命令、方法和选项的更多信息，请参阅他们的 [Image Processing Documentation](https://gohugo.io/content-management/image-processing/). diff --git a/content/docs/guide/shortcodes/details.fa.md b/content/docs/guide/shortcodes/details.fa.md new file mode 100644 index 0000000..f3b9882 --- /dev/null +++ b/content/docs/guide/shortcodes/details.fa.md @@ -0,0 +1,43 @@ +--- +title: جزئیات +--- + +یک کامپوننت داخلی برای نمایش محتوای قابل باز و بسته شدن. + + + +## مثال + +{{% details title="جزئیات" %}} + +این محتوای جزئیات است. + +مارک‌داون **پشتیبانی می‌شود**. + +{{% /details %}} + +{{% details title="برای نمایش روی من کلیک کنید" closed="true" %}} + +این به طور پیش‌فرض پنهان می‌شود. + +{{% /details %}} + +## استفاده + +````markdown +{{%/* details title="جزئیات" */%}} + +این محتوای جزئیات است. + +مارک‌داون **پشتیبانی می‌شود**. + +{{%/* /details */%}} +```` + +````markdown +{{%/* details title="برای نمایش روی من کلیک کنید"closed="true" */%}} + +این به طور پیش‌فرض پنهان می‌شود. + +{{%/* /details */%}} +```` diff --git a/content/docs/guide/shortcodes/details.md b/content/docs/guide/shortcodes/details.md new file mode 100644 index 0000000..e5031de --- /dev/null +++ b/content/docs/guide/shortcodes/details.md @@ -0,0 +1,43 @@ +--- +title: Details +--- + +A built-in component to display a collapsible content. + + + +## Example + +{{% details title="Details" %}} + +This is the content of the details. + +Markdown is **supported**. + +{{% /details %}} + +{{% details title="Click me to reveal" closed="true" %}} + +This will be hidden by default. + +{{% /details %}} + +## Usage + +````markdown +{{%/* details title="Details" */%}} + +This is the content of the details. + +Markdown is **supported**. + +{{%/* /details */%}} +```` + +````markdown +{{%/* details title="Click me to reveal" closed="true" */%}} + +This will be hidden by default. + +{{%/* /details */%}} +```` diff --git a/content/docs/guide/shortcodes/details.zh-cn.md b/content/docs/guide/shortcodes/details.zh-cn.md new file mode 100644 index 0000000..395c276 --- /dev/null +++ b/content/docs/guide/shortcodes/details.zh-cn.md @@ -0,0 +1,43 @@ +--- +title: 详情 +--- + +用于显示可折叠内容的内置组件。 + + + +## 示例 + +{{% details title="Details" %}} + +这是细节的内容 + +Markdown is **supported**. + +{{% /details %}} + +{{% details title="Click me to reveal" closed="true" %}} + +默认情况下这将被隐藏 + +{{% /details %}} + +## Usage + +````markdown +{{%/* details title="Details" */%}} + +这是细节的内容 + +**支持** Markdown + +{{%/* /details */%}} +```` + +````markdown +{{%/* details title="Click me to reveal" closed="true" */%}} + +默认情况下这将被隐藏 + +{{%/* /details */%}} +```` diff --git a/content/docs/guide/shortcodes/filetree.fa.md b/content/docs/guide/shortcodes/filetree.fa.md new file mode 100644 index 0000000..e1c8c40 --- /dev/null +++ b/content/docs/guide/shortcodes/filetree.fa.md @@ -0,0 +1,36 @@ +--- +title: کامپوننت FileTree +linkTitle: FileTree +prev: /docs/guide/shortcodes +next: /docs/guide/shortcodes/icon +--- + +## مثال + +{{< filetree/container >}} + {{< filetree/folder name="content" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/folder name="docs" state="closed" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/file name="introduction.md" >}} + {{< filetree/file name="introduction.fa.md" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< filetree/file name="hugo.toml" >}} +{{< /filetree/container >}} + +## استفاده + +```text {filename="Markdown"} +{{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} +{{}} +``` diff --git a/content/docs/guide/shortcodes/filetree.md b/content/docs/guide/shortcodes/filetree.md new file mode 100644 index 0000000..1978c34 --- /dev/null +++ b/content/docs/guide/shortcodes/filetree.md @@ -0,0 +1,34 @@ +--- +title: FileTree Component +linkTitle: FileTree +--- + +## Example + +{{< filetree/container >}} + {{< filetree/folder name="content" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/folder name="docs" state="closed" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/file name="introduction.md" >}} + {{< filetree/file name="introduction.fr.md" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< filetree/file name="hugo.toml" >}} +{{< /filetree/container >}} + +## Usage + +```text {filename="Markdown"} +{{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} +{{}} +``` diff --git a/content/docs/guide/shortcodes/filetree.zh-cn.md b/content/docs/guide/shortcodes/filetree.zh-cn.md new file mode 100644 index 0000000..c467031 --- /dev/null +++ b/content/docs/guide/shortcodes/filetree.zh-cn.md @@ -0,0 +1,33 @@ +--- +title: 文件树 +--- + +## 示例 + +{{< filetree/container >}} + {{< filetree/folder name="content" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/folder name="docs" state="closed" >}} + {{< filetree/file name="_index.md" >}} + {{< filetree/file name="introduction.md" >}} + {{< filetree/file name="introduction.fr.md" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< filetree/file name="hugo.toml" >}} +{{< /filetree/container >}} + +## 用法 + +```text {filename="Markdown"} +{{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} +{{}} +``` diff --git a/content/docs/guide/shortcodes/icon.fa.md b/content/docs/guide/shortcodes/icon.fa.md new file mode 100644 index 0000000..392c688 --- /dev/null +++ b/content/docs/guide/shortcodes/icon.fa.md @@ -0,0 +1,47 @@ +--- +title: آیکون + +--- + +برای استفاده از این کد کوتاه درون‌خطی، باید آن را در پیکربندی فعال کنید: + +```yaml {filename="hugo.yaml"} +enableInlineShortcodes: true +``` + +فهرست آیکون‌های موجود را می‌توانید در [`data/icons.yaml`](https://github.com/imfing/hextra/blob/main/data/icons.yaml) پیدا کنید. + + + +## مثال + +{{< icon "academic-cap" >}} +{{< icon "cake" >}} +{{< icon "gift" >}} +{{< icon "sparkles" >}} + +## استفاده + +``` +{{}} +``` + +آیکون‌های با طرح‌های متفاوت در [Heroicons](https://v1.heroicons.com/) نسخه ۱ خارج از جعبه در دسترس هستند. + +### چجوری آیکون‌های خودمان را اضافه کنیم + +پرونده `data/icons.yaml` را ایجاد کنید، سپس آیکون‌های SVG خود را در فرمت زیر اضافه کنید: + +```yaml {filename="data/icons.yaml"} +your-icon: your icon svg content +``` + +سپس می‌توان آن را در کد کوتاه مانند زیر استفاده کرد: + +``` +{{}} + +{{}} +``` + +نکته: [Iconify Design](https://iconify.design/) مکانی عالی برای پیدا کردن آیکون‌های SVG برای سایت شما است. diff --git a/content/docs/guide/shortcodes/icon.md b/content/docs/guide/shortcodes/icon.md new file mode 100644 index 0000000..dc93cd0 --- /dev/null +++ b/content/docs/guide/shortcodes/icon.md @@ -0,0 +1,46 @@ +--- +title: Icon +--- + +To use this shortcode inline, inline shortcode needs to be enabled in the config: + +```yaml {filename="hugo.yaml"} +enableInlineShortcodes: true +``` + +List of available icons can be found in [`data/icons.yaml`](https://github.com/imfing/hextra/blob/main/data/icons.yaml). + + + +## Example + +{{< icon "academic-cap" >}} +{{< icon "cake" >}} +{{< icon "gift" >}} +{{< icon "sparkles" >}} + +## Usage + +``` +{{}} +``` + +[Heroicons](https://v1.heroicons.com/) v1 outline icons are available out of the box. + +### How to add your own icons + +Create `data/icons.yaml` file, then add your own SVG icons in the following format: + +```yaml {filename="data/icons.yaml"} +your-icon: your icon svg content +``` + +It then can be used in the shortcode like this: + +``` +{{}} + +{{}} +``` + +Tip: [Iconify Design](https://iconify.design/) is a great place to find SVG icons for your site. diff --git a/content/docs/guide/shortcodes/icon.zh-cn.md b/content/docs/guide/shortcodes/icon.zh-cn.md new file mode 100644 index 0000000..196a4f1 --- /dev/null +++ b/content/docs/guide/shortcodes/icon.zh-cn.md @@ -0,0 +1,46 @@ +--- +title: 图标 +--- + +要内联使用此短代码，需要在配置中启用内联短代码： + +```yaml {filename="hugo.yaml"} +enableInlineShortcodes: true +``` + +可用图标列表可以在以下位置找到 [`data/icons.yaml`](https://github.com/imfing/hextra/blob/main/data/icons.yaml). + + + +## 示例 + +{{< icon "academic-cap" >}} +{{< icon "cake" >}} +{{< icon "gift" >}} +{{< icon "sparkles" >}} + +## 用法 + +``` +{{}} +``` + +[Heroicons](https://v1.heroicons.com/) v1 轮廓图标开箱即用 + +### 如何添加自己的图标 + +创建 `data/icons.yaml` 文件，然后按以下格式添加您自己的 SVG 图标： + +```yaml {filename="data/icons.yaml"} +your-icon: your icon svg content +``` + +然后可以在短代码中使用它，如下所示： + +``` +{{}} + +{{}} +``` + +提示：[Iconify Design](https://iconify.design/) 是为您的网站查找 SVG 图标的好地方 diff --git a/content/docs/guide/shortcodes/steps.fa.md b/content/docs/guide/shortcodes/steps.fa.md new file mode 100644 index 0000000..c726882 --- /dev/null +++ b/content/docs/guide/shortcodes/steps.fa.md @@ -0,0 +1,42 @@ +--- +title: مراحل +next: /docs/guide/deploy-site +--- + +یک کامپوننت داخلی برای نمایش یک سری مراحل. + +## مثال + +{{% steps %}} + +### مرحله ۱ +این اولین مرحله است. + +### مرحله ۲ + +این دومین مرحله است. + +### مرحله ۳ + +این سومین مرحله است. + +{{% /steps %}} + + +## استفاده + +سرتیتر مارک‌داون h3 را در کد کوتاه `steps` قرار دهید. + +``` +{{%/* steps */%}} + +### مرحله ۱ + +این اولین مرحله است. + +### مرحله ۲ + +این دومین مرحله است. + +{{%/* /steps */%}} +``` diff --git a/content/docs/guide/shortcodes/steps.md b/content/docs/guide/shortcodes/steps.md new file mode 100644 index 0000000..584f081 --- /dev/null +++ b/content/docs/guide/shortcodes/steps.md @@ -0,0 +1,42 @@ +--- +title: Steps +--- + +A built-in component to display a series of steps. + +## Example + +{{% steps %}} + +### Step 1 + +This is the first step. + +### Step 2 + +This is the second step. + +### Step 3 + +This is the third step. + +{{% /steps %}} + + +## Usage + +Put Markdown h3 header within `steps` shortcode. + +``` +{{%/* steps */%}} + +### Step 1 + +This is the first step. + +### Step 2 + +This is the second step. + +{{%/* /steps */%}} +``` diff --git a/content/docs/guide/shortcodes/steps.zh-cn.md b/content/docs/guide/shortcodes/steps.zh-cn.md new file mode 100644 index 0000000..59d8f05 --- /dev/null +++ b/content/docs/guide/shortcodes/steps.zh-cn.md @@ -0,0 +1,42 @@ +--- +title: 步骤 +--- + +A built-in component to display a series of steps. + +## 示例 + +{{% steps %}} + +### 第一步 + +这是第一步。 + +### 第二步 + +这是第二步。 + +### 第三步 + +这是第三步。 + +{{% /steps %}} + + +## 使用 + +将 Markdown h3 标题放入 `steps` 短代码中。 + +``` +{{%/* steps */%}} + +### Step 1 + +This is the first step. + +### Step 2 + +This is the second step. + +{{%/* /steps */%}} +``` diff --git a/content/docs/guide/shortcodes/tabs.fa.md b/content/docs/guide/shortcodes/tabs.fa.md new file mode 100644 index 0000000..6d01166 --- /dev/null +++ b/content/docs/guide/shortcodes/tabs.fa.md @@ -0,0 +1,92 @@ +--- +title: زبانه‌ها +--- + +## مثال + +{{< tabs items="JSON,YAML,TOML" >}} + +{{< tab >}}**JSON**: جیسون معادل اختصاری عبارت JavaScript Object Notation به معنی «نمادگذاری اشیا در جاوا اسکریپت» است. جیسون یک قالب استاندارد باز است که امکان تبادل داده‌ها در وب با استفاده از جفت‌های خصوصیت-کلید را ممکن ساخته است.{{< /tab >}} +{{< tab >}}**YAML**: یک زبان برای سریال‌سازی داده قابل-خواندن-برای-انسان است.{{< /tab >}} +{{< tab >}}**TOML**: یک قالب پرونده پیکربندی که به هدف سادگی در خوانایی به کمک داشتن معانی مشخص با هدف «کمینه» و مینیمال بودن ارائه شده است.{{< /tab >}} + +{{< /tabs >}} + +## استفاده + +### پیش‌فرض + +``` +{{}} + + {{}}**JSON**: جیسون معادل اختصاری عبارت JavaScript Object Notation به معنی «نمادگذاری اشیا در جاوا اسکریپت» است. جیسون یک قالب استاندارد باز است که امکان تبادل داده‌ها در وب با استفاده از جفت‌های خصوصیت-کلید را ممکن ساخته است.{{}} + {{}}**YAML**: یک زبان برای سریال‌سازی داده قابل-خواندن-برای-انسان است.{{}} + {{}}**TOML**: یک قالب پرونده پیکربندی که به هدف سادگی در خوانایی به کمک داشتن معانی مشخص با هدف «کمینه» و مینیمال بودن ارائه شده است.{{}} + +{{}} +``` + +### مشخص کردن زبانه‌ پیش‌فرض + +از ویژگی `defaultIndex` برای مشخص کردن زبانه‌ پیش‌فرض استفاده کنید. این شاخص از 0 شروع می‌شود. + +``` +{{}} + + {{}}**JSON**: جیسون معادل اختصاری عبارت JavaScript Object Notation به معنی «نمادگذاری اشیا در جاوا اسکریپت» است. جیسون یک قالب استاندارد باز است که امکان تبادل داده‌ها در وب با استفاده از جفت‌های خصوصیت-کلید را ممکن ساخته است.{{}} + {{}}**YAML**: یک زبان برای سریال‌سازی داده قابل-خواندن-برای-انسان است.{{}} + {{}}**TOML**: یک قالب پرونده پیکربندی که به هدف سادگی در خوانایی به کمک داشتن معانی مشخص با هدف «کمینه» و مینیمال بودن ارائه شده است.{{}} + +{{}} +``` + +زبانه‌ `YAML` به طور پیش‌فرض انتخاب می‌شود. + +{{< tabs items="JSON,YAML,TOML" defaultIndex="1" >}} + +{{< tab >}}**JSON**: جیسون معادل اختصاری عبارت JavaScript Object Notation به معنی «نمادگذاری اشیا در جاوا اسکریپت» است. جیسون یک قالب استاندارد باز است که امکان تبادل داده‌ها در وب با استفاده از جفت‌های خصوصیت-کلید را ممکن ساخته است.{{< /tab >}} +{{< tab >}}**YAML**: یک زبان برای سریال‌سازی داده قابل-خواندن-برای-انسان است.{{< /tab >}} +{{< tab >}}**TOML**: یک قالب پرونده پیکربندی که به هدف سادگی در خوانایی به کمک داشتن معانی مشخص با هدف «کمینه» و مینیمال بودن ارائه شده است.{{< /tab >}} + +{{< /tabs >}} + + +### استفاده از مارک‌داون + +سینتکس مارک‌داون از جمله بلوک کد نیز پشتیبانی می‌شود: + +```` +{{}} + + {{}} + ```json + { "سلام": "دنیا" } + ``` + {{}} + + ... زبانه‌های دیگر را به همین ترتیب اضافه کنید + +{{}} +```` + +{{< tabs items="JSON,YAML,TOML" >}} + + {{< tab >}} + ```json + { "سلام": "دنیا" } + ``` + {{< /tab >}} + + {{< tab >}} + ```yaml + سلام: دنیا + ``` + {{< /tab >}} + + {{< tab >}} + ```toml + سلام = "دنیا" + ``` + {{< /tab >}} + +{{< /tabs >}} diff --git a/content/docs/guide/shortcodes/tabs.md b/content/docs/guide/shortcodes/tabs.md new file mode 100644 index 0000000..c63547a --- /dev/null +++ b/content/docs/guide/shortcodes/tabs.md @@ -0,0 +1,93 @@ +--- +title: Tabs +next: /docs/guide/deploy-site +--- + +## Example + +{{< tabs items="JSON,YAML,TOML" >}} + +{{< tab >}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{< /tab >}} +{{< tab >}}**YAML**: YAML is a human-readable data serialization language.{{< /tab >}} +{{< tab >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}} + +{{< /tabs >}} + +## Usage + +### Default + +``` +{{}} + + {{}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{}} + {{}}**YAML**: YAML is a human-readable data serialization language.{{}} + {{}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{}} + +{{}} +``` + +### Specify Selected Index + +Use `defaultIndex` property to specify the selected tab. The index starts from 0. + +``` +{{}} + + {{}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{}} + {{}}**YAML**: YAML is a human-readable data serialization language.{{}} + {{}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{}} + +{{}} +``` + +The `YAML` tab will be selected by default. + +{{< tabs items="JSON,YAML,TOML" defaultIndex="1" >}} + +{{< tab >}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{< /tab >}} +{{< tab >}}**YAML**: YAML is a human-readable data serialization language.{{< /tab >}} +{{< tab >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}} + +{{< /tabs >}} + + +### Use Markdown + +Markdown syntax including code block is also supported: + +```` +{{}} + + {{}} + ```json + { "hello": "world" } + ``` + {{}} + + ... add other tabs similarly + +{{}} +```` + +{{< tabs items="JSON,YAML,TOML" >}} + + {{< tab >}} + ```json + { "hello": "world" } + ``` + {{< /tab >}} + + {{< tab >}} + ```yaml + hello: world + ``` + {{< /tab >}} + + {{< tab >}} + ```toml + hello = "world" + ``` + {{< /tab >}} + +{{< /tabs >}} diff --git a/content/docs/guide/shortcodes/tabs.zh-cn.md b/content/docs/guide/shortcodes/tabs.zh-cn.md new file mode 100644 index 0000000..8e3b3ae --- /dev/null +++ b/content/docs/guide/shortcodes/tabs.zh-cn.md @@ -0,0 +1,93 @@ +--- +title: 标签页 +next: /docs/guide/deploy-site +--- + +## 示例 + +{{< tabs items="JSON,YAML,TOML" >}} + +{{< tab >}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{< /tab >}} +{{< tab >}}**YAML**: YAML is a human-readable data serialization language.{{< /tab >}} +{{< tab >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}} + +{{< /tabs >}} + +## 使用 + +### 默认情况下 + +``` +{{}} + + {{}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{}} + {{}}**YAML**: YAML is a human-readable data serialization language.{{}} + {{}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{}} + +{{}} +``` + +### 指定索引 + +使用 `defaultIndex` 属性指定选定的选项卡。索引从 0 开始。 + +``` +{{}} + + {{}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{}} + {{}}**YAML**: YAML is a human-readable data serialization language.{{}} + {{}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{}} + +{{}} +``` + +默认为 `YAML` + +{{< tabs items="JSON,YAML,TOML" defaultIndex="1" >}} + +{{< tab >}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{< /tab >}} +{{< tab >}}**YAML**: YAML is a human-readable data serialization language.{{< /tab >}} +{{< tab >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}} + +{{< /tabs >}} + + +### 使用 Markdown + +还支持包括代码块的 Markdown 语法： + +```` +{{}} + + {{}} + ```json + { "hello": "world" } + ``` + {{}} + + ... add other tabs similarly + +{{}} +```` + +{{< tabs items="JSON,YAML,TOML" >}} + + {{< tab >}} + ```json + { "hello": "world" } + ``` + {{< /tab >}} + + {{< tab >}} + ```yaml + hello: world + ``` + {{< /tab >}} + + {{< tab >}} + ```toml + hello = "world" + ``` + {{< /tab >}} + +{{< /tabs >}} diff --git a/content/docs/guide/syntax-highlighting.fa.md b/content/docs/guide/syntax-highlighting.fa.md new file mode 100644 index 0000000..cb7a49e --- /dev/null +++ b/content/docs/guide/syntax-highlighting.fa.md @@ -0,0 +1,89 @@ +--- +title: "برجسته‌کردن سینتکس" +weight: 3 +--- + +هیوگو از [Chroma](https://github.com/alecthomas/chroma)، یک برجسته‌کننده سینتکس عمومی در Go خالص، برای برجسته‌سازی کردن سینتکس استفاده می‌کند. + توصیه می‌شود از بک‌تیک برای بلوک‌های کد در محتوای مارک‌داون استفاده کنید. مثلا: + + + +````markdown {filename="Markdown"} +```python +def say_hello(): + print("سلام!") +``` +```` + +به صورت زیر رندر خواهد شد: + +```python +def say_hello(): + print("سلام!") +``` + +## ویژگی‌ها + +### Filename + +برای افزودن نام پرونده یا عنوان به بلوک کد، `filename` را مشخص کنید: + +````markdown {filename="Markdown"} +```python {filename="hello.py"} +def say_hello(): + print("سلام!") +``` +```` + +```python {filename="hello.py"} +def say_hello(): + print("سلام!") +``` + +### شماره خطوط + +برای تنظیم شماره خطوط، ویژگی `linenos` را روی `table` قرار دهید و به صورت اختیاری `linenostart` را روی شماره‌ای که خط شروع می‌شود تنظیم کنید: + +````markdown {filename="Markdown"} +```python {linenos=table,linenostart=42} +def say_hello(): + print("سلام!") +``` +```` + +```python {linenos=table,linenostart=42} +def say_hello(): + print("سلام!") +``` + +### برجسته کردن خطوط + +برای برجسته کردن خطوط، ویژگی `hl_lines` را به فهرستی از شماره خطوط تنظیم کنید: + +````markdown {filename="Markdown"} +```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"} +def say_hello(): + print("سلام!") + +def main(): + say_hello() +``` +```` + +```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"} +def say_hello(): + print("سلام!") + +def main(): + say_hello() +``` + + +### دکمه کپی + +به طور پیش‌فرض، دکمه کپی برای بلوک‌های کد فعال است. + + +## زبان‌های پشتیبانی شده + +برای مشاهده فهرست زبان‌های پشتیبانی شده، لطفا به [مستندات Chroma](https://github.com/alecthomas/chroma#supported-languages) مراجعه کنید. diff --git a/content/docs/guide/syntax-highlighting.md b/content/docs/guide/syntax-highlighting.md new file mode 100644 index 0000000..799c5ec --- /dev/null +++ b/content/docs/guide/syntax-highlighting.md @@ -0,0 +1,89 @@ +--- +title: "Syntax Highlighting" +weight: 3 +--- + +Hugo uses [Chroma](https://github.com/alecthomas/chroma), a general purpose syntax highlighter in pure Go, for syntax highlighting. +It is recommended to use backticks for code blocks in Markdown content. For example: + + + +````markdown {filename="Markdown"} +```python +def say_hello(): + print("Hello!") +``` +```` + +will be rendered as: + +```python +def say_hello(): + print("Hello!") +``` + +## Features + +### Filename + +To add a filename or title to the code block, set attribute `filename`: + +````markdown {filename="Markdown"} +```python {filename="hello.py"} +def say_hello(): + print("Hello!") +``` +```` + +```python {filename="hello.py"} +def say_hello(): + print("Hello!") +``` + +### Line Numbers + +To set line numbers, set attribute `linenos` to `table` and optionally set `linenostart` to the starting line number: + +````markdown {filename="Markdown"} +```python {linenos=table,linenostart=42} +def say_hello(): + print("Hello!") +``` +```` + +```python {linenos=table,linenostart=42} +def say_hello(): + print("Hello!") +``` + +### Highlighting Lines + +To highlight lines, set attribute `hl_lines` to a list of line numbers: + +````markdown {filename="Markdown"} +```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"} +def say_hello(): + print("Hello!") + +def main(): + say_hello() +``` +```` + +```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"} +def say_hello(): + print("Hello!") + +def main(): + say_hello() +``` + + +### Copy Button + +By default, copy button is enabled for code blocks. + + +## Supported Languages + +For a list of supported languages, please see the [Chroma documentation](https://github.com/alecthomas/chroma#supported-languages). diff --git a/content/docs/guide/syntax-highlighting.zh-cn.md b/content/docs/guide/syntax-highlighting.zh-cn.md new file mode 100644 index 0000000..798f0be --- /dev/null +++ b/content/docs/guide/syntax-highlighting.zh-cn.md @@ -0,0 +1,89 @@ +--- +title: "代码高亮" +weight: 3 +--- + +Hugo 使用 [Chroma](https://github.com/alecthomas/chroma)，一种纯 Golang 实现的代码高亮渲染器。 +建议对 Markdown 内容中的代码块使用反引号，例如： + + + +````markdown {filename="Markdown"} +```python +def say_hello(): + print("Hello!") +``` +```` + +将呈现为： + +```python +def say_hello(): + print("Hello!") +``` + +## 特性 + +### 文件名 + +要向代码块添加文件名或标题，请设置 `filename`： + +````markdown {filename="Markdown"} +```python {filename="hello.py"} +def say_hello(): + print("Hello!") +``` +```` + +```python {filename="hello.py"} +def say_hello(): + print("Hello!") +``` + +### 行号 + +如需设置行号，将 `linenos` 设置为 `table`，并将 `linenostart` 设置为起始行号： + +````markdown {filename="Markdown"} +```python {linenos=table,linenostart=42} +def say_hello(): + print("Hello!") +``` +```` + +```python {linenos=table,linenostart=42} +def say_hello(): + print("Hello!") +``` + +### 高亮行 + +显示高亮行，设置 `hl_lines` 为行号： + +````markdown {filename="Markdown"} +```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"} +def say_hello(): + print("Hello!") + +def main(): + say_hello() +``` +```` + +```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"} +def say_hello(): + print("Hello!") + +def main(): + say_hello() +``` + + +### 复制按钮 + +默认情况下，代码块复制按钮已自动启用。 + + +## 支持的编程语言 + +如需了解支持的编程语言，转至 [Chroma's documentation](https://github.com/alecthomas/chroma#supported-languages)。 diff --git a/content/showcase/index.fa.md b/content/showcase/index.fa.md new file mode 100644 index 0000000..3e24c84 --- /dev/null +++ b/content/showcase/index.fa.md @@ -0,0 +1,20 @@ +--- +title: ویترین +description: "پروژه‌های متن‌باز که توسط هگزترا طراحی شده‌اند." +toc: false +layout: wide +--- + +
+ +

+پروژه‌های متن‌باز که توسط هگزترا طراحی شده‌اند. +

+ +{{< cards >}} + {{< card link="https://developers.osuny.org" title="Osuny" image="https://raw.githubusercontent.com/noesya/osuny-developers/main/static/images/showcase-hextra/screenshot.png" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}} + {{< card link="https://porter.sh/" title="Porter" image="https://repository-images.githubusercontent.com/155893691/aa249c80-fcf3-11ea-93b0-30079e8d7de4" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}} + {{< card link="https://lutheranconfessions.org/" title="LutheranConfessions" image="https://github.com/imfing/hextra/assets/5097752/ad6625e4-88cd-4cad-b102-5399997d0359" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}} + {{< card link="https://github.com/imfing/hextra-starter-template/" title="Hextra Starter Template" image="https://user-images.githubusercontent.com/5097752/263551418-c403b9a9-a76c-47a6-8466-513d772ef0b7.jpg" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}} + {{< card link="https://developers.clever-cloud.com/" title="Clever Cloud Documentation" image="https://cellar-c2.services.clever-cloud.com/documentation/doc-screenshot.png" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}} +{{< /cards >}} diff --git a/content/showcase/index.md b/content/showcase/index.md new file mode 100644 index 0000000..972301f --- /dev/null +++ b/content/showcase/index.md @@ -0,0 +1,77 @@ +--- +title: Showcase +description: "Open source projects powered by Hextra" +toc: false +layout: wide +--- + +
+ +

+Open source projects powered by Hextra +

+ +{{< cards >}} + + {{< card + link="https://github.com/infracourse/web" + title="Stanford CS 40" + image="https://github.com/imfing/hextra/assets/5097752/8c29470b-3994-41c8-be9a-5b41476e6f3c" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://github.com/helixml/docs" + title="Helix Docs" + image="https://github.com/imfing/hextra/assets/5097752/78045af0-4922-4358-ae73-624770909db6" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://developers.clever-cloud.com/" + title="Clever Cloud Documentation" + image="https://cellar-c2.services.clever-cloud.com/documentation/doc-screenshot.png" imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://owaspai.org/" + title="OWASP AI Security and Privacy Guide" + image="https://github.com/imfing/hextra/assets/5097752/fbb1d3a5-a0e8-4cfc-88cf-3523b0176c89" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://developers.osuny.org" + title="Osuny" + image="https://raw.githubusercontent.com/noesya/osuny-developers/main/static/images/showcase-hextra/screenshot.png" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card link="https://porter.sh/" + title="Porter" + image="https://github.com/imfing/hextra/assets/5097752/401abc3a-b4c3-4336-b95a-a6dd9afbc1de" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://hoa.moe/" + title="HITSZ OpenAuto" + image="https://raw.githubusercontent.com/HITSZ-OpenAuto/hoa.moe/main/static/images/showcase-new.png" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://lutheranconfessions.org/" + title="LutheranConfessions" + image="https://github.com/imfing/hextra/assets/5097752/ad6625e4-88cd-4cad-b102-5399997d0359" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://github.com/imfing/hextra-starter-template/" + title="Hextra Starter Template" + image="https://user-images.githubusercontent.com/5097752/263551418-c403b9a9-a76c-47a6-8466-513d772ef0b7.jpg" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + +{{< /cards >}} diff --git a/content/showcase/index.zh-cn.md b/content/showcase/index.zh-cn.md new file mode 100644 index 0000000..3626c4f --- /dev/null +++ b/content/showcase/index.zh-cn.md @@ -0,0 +1,77 @@ +--- +title: 项目展示 +description: "由 Hextra 驱动的开源网站和项目。" +toc: false +layout: wide +--- + +
+ +

+由 Hextra 驱动的开源网站和项目。 +

+ +{{< cards >}} + + {{< card + link="https://github.com/infracourse/web" + title="Stanford CS 40" + image="https://github.com/imfing/hextra/assets/5097752/8c29470b-3994-41c8-be9a-5b41476e6f3c" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://github.com/helixml/docs" + title="Helix Docs" + image="https://github.com/imfing/hextra/assets/5097752/78045af0-4922-4358-ae73-624770909db6" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://developers.clever-cloud.com/" + title="Clever Cloud Documentation" + image="https://cellar-c2.services.clever-cloud.com/documentation/doc-screenshot.png" imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://owaspai.org/" + title="OWASP AI Security and Privacy Guide" + image="https://github.com/imfing/hextra/assets/5097752/fbb1d3a5-a0e8-4cfc-88cf-3523b0176c89" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://developers.osuny.org" + title="Osuny" + image="https://raw.githubusercontent.com/noesya/osuny-developers/main/static/images/showcase-hextra/screenshot.png" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card link="https://porter.sh/" + title="Porter" + image="https://github.com/imfing/hextra/assets/5097752/401abc3a-b4c3-4336-b95a-a6dd9afbc1de" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://hoa.moe/" + title="HITSZ OpenAuto" + image="https://raw.githubusercontent.com/HITSZ-OpenAuto/hoa.moe/main/static/images/showcase-new.png" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://lutheranconfessions.org/" + title="LutheranConfessions" + image="https://github.com/imfing/hextra/assets/5097752/ad6625e4-88cd-4cad-b102-5399997d0359" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + + {{< card + link="https://github.com/imfing/hextra-starter-template/" + title="Hextra Starter Template" + image="https://user-images.githubusercontent.com/5097752/263551418-c403b9a9-a76c-47a6-8466-513d772ef0b7.jpg" + imageStyle="object-fit:cover; aspect-ratio:16/9;" + >}} + +{{< /cards >}} diff --git a/hugo.yaml b/hugo.yaml index 1c0836b..6558e1f 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -1,6 +1,6 @@ -# Configuration baseURL: "https://midtowndrafting.com/" title: "Midtown Drafting & Design" +theme: hextra enableRobotsTXT: true enableGitInfo: true @@ -21,7 +21,7 @@ languages: en: languageName: English weight: 1 - title: Hextra + title: Midtown Drafting & Design markup: goldmark: