This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

主题 | Docsy 常用记录

Docsy 是 Hugo 的一个主题。该主题适合作为产品文档。 Docsy github - https://github.com/google/docsy

快速熟悉 Docsy 的方法：

  1. 熟悉 Hugo 使用。
  2. 对照官方示例，把官方文档通读一遍。
  3. 善于利用官方文档和 Docsy 源码。

官方文档

示例 example

1 - 外观（Look）

设置主题的样式、颜色、站点标识、站点图标等。

样式 style

  • assets/scss/_variables_project.scss 可以覆盖主题原有的变量值（在 assets/scss/_variables.scss 找到主题原有的变量值）和 Bootstrap 变量默认值。
  • assets/scss/_styles_project.scss 可以添加自己的自定义 SCSS 样式的地方，包括覆盖 Docsy 主题 SCSS 文件中的任何样式。

颜色 color

在 assets/scss/_variables_project.scss 中设置：

1$primary: #390040;
2$secondary: #A23B72;

将图片放在 assets/icons/logo.svg 会覆盖默认的站点标识。

通过配置 navbar_logo: false 也可以不显示站点标识。

站点图标 favicon

将图标放在 static/favicons/ 中会覆盖默认的站点图标。

因为主题会在头文件中插入下面引用 themes/docsy/layouts/partials/favicons.html

 1
 2<!-- Favicons as generated by http://cthedot.de/icongen -->
 3<link rel="shortcut icon" href="{{ "favicons/favicon.ico" | relURL }}" >
 4<link rel="apple-touch-icon" href="{{ "favicons/apple-touch-icon-180x180.png" | relURL }}" sizes="180x180">
 5<link rel="icon" type="image/png" href="{{ "favicons/favicon-16x16.png" | relURL }}" sizes="16x16">
 6<link rel="icon" type="image/png" href="{{ "favicons/favicon-32x32.png" | relURL }}" sizes="32x32">
 7<link rel="icon" type="image/png" href="{{ "favicons/android-36x36.png" | relURL }}" sizes="36x36">
 8<link rel="icon" type="image/png" href="{{ "favicons/android-48x48.png" | relURL }}" sizes="48x48">
 9<link rel="icon" type="image/png" href="{{ "favicons/android-72x72.png" | relURL }}" sizes="72x72">
10<link rel="icon" type="image/png" href="{{ "favicons/android-96x96.png" | relURL }}" sizes="96x96">
11<link rel="icon" type="image/png" href="{{ "favicons/android-144x144.png" | relURL }}" sizes="144x144">
12<link rel="icon" type="image/png" href="{{ "favicons/android-192x192.png" | relURL }}" sizes="192x192">

Tips： 通过 http://cthedot.de/icongen（允许您从单个图像创建各种图标大小和选项）或 https://favicon.io 可以快速创建一组网站图标。

图标样式 icon

https://fontawesome.com/icons?d=gallery&m=free

2 - 封面（Cover）

定制站点的封面页，如：首页、关于页。

这些页面通常作为独特的封面页：

  • content/_index.md —— 首页
  • content/about.md —— 关于页

根据模板优先级，封面页最终使用 layouts/_default/baseof.html 作为页面模板。这个模板只有 header 和 footer。

背景图 background

Docsy 提供 layouts/shortcodes/blocks/cover.html 简码来生成封面页背景图。

  1. 添加图片 “content/featured-background.jpg” (图片包含background即可)

  2. 调用简码

     1{{% blocks/cover title="Welcome to Docsy!" image_anchor="top" height="full" %}}
 2<a class="btn btn-lg btn-primary me-3 mb-4" href="{{% relref '/about' %}}">
 3Learn More <i class="fa-solid fa-circle-right ms-2"></i>
 4</a>
 5<a class="btn btn-lg btn-secondary me-3 mb-4" href="https://github.com/google/docsy">
 6Download <i class="fa-brands fa-github ms-2 "></i>
 7</a>
 8
 9A Hugo theme for creating great technical documentation sites
10{.lead .mt-5}
11
12{{% blocks/link-down color="info" %}}
13{{% /blocks/cover %}}

    参数：

    • title
    • subtitle
    • byline
    • color
    • height
    • image_anchor
    • logo_anchor

3 - 布局（Layout）

主题会预先定义好几种页面布局，以应对主题考虑的几种页面场景。

主题提供了以下几种内容类型（ContentType）：

用法参考： Hugo 的布局（Layout）概念

4 - 简码（Shortcode）

简码，顾名思义"用于简化操作的代码块"。

官方文档： https://www.docsy.dev/docs/adding-content/shortcodes/ (可用简码列表)

使用参考： Hugo 简码使用

5 - 搜索（Search）

搜索站点关键字。

官方文档： https://www.docsy.dev/docs/adding-content/search/

6 - 部署（Deploy）

将站点发布到网上。

6.1 - Github

使用 Github Action 部署站点。

核心项目： https://github.com/peaceiris/actions-hugo#readme

本项目为例： .github/workflows/gh-pages.yaml

 1name: GitHub Pages
 2
 3on:
 4  push:
 5    branches:
 6      - master  # Set a branch to deploy
 7  pull_request:
 8
 9jobs:
10  deploy:
11    runs-on: ubuntu-22.04
12    concurrency:
13      group: ${{ github.workflow }}-${{ github.ref }}
14    steps:
15      - uses: actions/checkout@v4
16        with:
17          submodules: recursive  # Fetch the Docsy theme
18          fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
19
20      - name: Setup Hugo
21        uses: peaceiris/actions-hugo@v2
22        with:
23          hugo-version: '0.119.0'
24          extended: true
25
26      - name: Setup Node
27        uses: actions/setup-node@v3
28        with:
29          node-version: '18'
30          cache: 'npm'
31          # The action defaults to search for the dependency file (package-lock.json,
32          # npm-shrinkwrap.json or yarn.lock) in the repository root, and uses its
33          # hash as a part of the cache key.
34          # https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-data
35          cache-dependency-path: '**/package-lock.json'
36
37      - run: npm ci
38      - run: hugo --minify
39        env:
40          HUGO_ENV: production
41
42      - name: Deploy
43        uses: peaceiris/actions-gh-pages@v3
44        if: github.ref == 'refs/heads/master'
45        with:
46          github_token: ${{ secrets.GITHUB_TOKEN }}
47          publish_branch: gh-pages