diff --git a/exampleSite/content/docs/guide/deploy-site.zh.cn.md b/exampleSite/content/docs/guide/deploy-site.zh.cn.md new file mode 100644 index 00000000..4d694d5f --- /dev/null +++ b/exampleSite/content/docs/guide/deploy-site.zh.cn.md @@ -0,0 +1,163 @@ +--- +title: Deploy Site +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/exampleSite/content/docs/guide/shortcodes/callout.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/callout.zh-cn.md new file mode 100644 index 00000000..feb79312 --- /dev/null +++ b/exampleSite/content/docs/guide/shortcodes/callout.zh-cn.md @@ -0,0 +1,79 @@ +--- +title: 标注 +linkTitle: Callout +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/exampleSite/content/docs/guide/shortcodes/cards.zh-cn.md.md b/exampleSite/content/docs/guide/shortcodes/cards.zh-cn.md.md new file mode 100644 index 00000000..8a88be13 --- /dev/null +++ b/exampleSite/content/docs/guide/shortcodes/cards.zh-cn.md.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/exampleSite/content/docs/guide/shortcodes/details.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/details.zh-cn.md new file mode 100644 index 00000000..395c2761 --- /dev/null +++ b/exampleSite/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/exampleSite/content/docs/guide/shortcodes/filetree.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/filetree.zh-cn.md new file mode 100644 index 00000000..dd6bd46d --- /dev/null +++ b/exampleSite/content/docs/guide/shortcodes/filetree.zh-cn.md @@ -0,0 +1,34 @@ +--- +title: 文件树 +linkTitle: FileTree +--- + +## 示例 + +{{< 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/exampleSite/content/docs/guide/shortcodes/icon.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/icon.zh-cn.md new file mode 100644 index 00000000..196a4f1e --- /dev/null +++ b/exampleSite/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/exampleSite/content/docs/guide/shortcodes/steps.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/steps.zh-cn.md new file mode 100644 index 00000000..59d8f053 --- /dev/null +++ b/exampleSite/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/exampleSite/content/docs/guide/shortcodes/tabs.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/tabs.zh-cn.md new file mode 100644 index 00000000..087fbe68 --- /dev/null +++ b/exampleSite/content/docs/guide/shortcodes/tabs.zh-cn.md @@ -0,0 +1,93 @@ +--- +title: Tabs +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 >}}