这是本节的多页打印视图。点击此处打印.

内容定制

Docsy主题的内容和定制化

1: 添加内容
2: 外观和体验
3: 导航
4: 手工链接1
5: 手工链接2
6: 版本
7: shortcodes
8: 图标图片
9: 启用CSE搜索
10: Google Analytics
11: 百度统计

1 - 添加内容

在docsy中添加内容

参考： Adding Content | Docsy

content section

Docsy 主题带有三个模版，以提供三种常见的内容章节：

docs
blog
community

TODO：看代码还有一个 swagger 不知道要怎么用

自定义section

如复制了 example 网站，不想使用所提供的内容部分，只需删除相应的内容子目录。

同样地，如果想添加一个顶层section，只需添加一个新的子目录，不过如果您想使用任何现有的Docsy模板，而不是默认的模板，您需要在每个页面的前言中明确指定布局或内容类型。例如，如果您创建了一个新的目录 content/en/amazing，并希望该自定义部分中的一个或多个页面使用 Docsy 的 docs 模板，您可以在每个页面的前言中添加 type: docs。

---
title: "My amazing new section"
weight: 1
type: docs
description: >
    A special section with a docs layout.    
---

或者，在你的项目的布局目录中，根据现有的模板之一，为你的新栏目创建你自己的页面模板。

TODO: 理论上只要找到合适的页面模版，就可以在 docsy 主题中支持更多的section。有需要时再研究。

从Hugo 0.76开始，不需要在每一个页面上都指定 type: blog，可以在索引页中指定:

---
title: "Latest News"
linkTitle: "News"
menu:
  main:
    weight: 30

cascade:
- type: "blog"
---

这就方便太多了。不然每个页面都要指定很麻烦的。

RSS feeds

rss_sections = ["docs", "docsy"]

2 - 外观和体验

docsy的外观和体验

参考： Look and Feel | Docsy

颜色和css

这些暂时先用默认吧。

代码高亮

继续用默认的 Chroma 和 tango style。

Mermaid的支持

有 plantuml 就先不用这个。

plantuml的支持

试试这个：

participant participant as Foo
actor       actor       as Foo1
boundary    boundary    as Foo2
control     control     as Foo3
entity      entity      as Foo4
database    database    as Foo5
collections collections as Foo6
queue       queue       as Foo7
Foo -> Foo1 : To actor 
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue

开启方式：

[params.plantuml]
enable = true
theme = "default"

#Set url to plantuml server 
#default is http://www.plantuml.com/plantuml/svg/
svg_image_url = "https://www.plantuml.com/plantuml/svg/"

注意 guessSyntax 必须设置为false，否则无法生效：

[markup]
  [markup.highlight]
      guessSyntax = "false"

3 - 导航

docsy的导航

参考：https://www.docsy.dev/docs/adding-content/navigation/

顶级菜单

每个 section 都可以通过 weight 参数指定在顶级菜单中的排序，从小到大，从左到右排序：

---
title: "Welcome to Docsy"
linkTitle: "Documentation"
menu:
  main:
    weight: 30
    pre: <i class='fas fa-paper-plane'></i>
---

注意这里可以通过 pre 设置每个菜单项的css，如为每个菜单项设置一个图标，非常实用。

图标来自 Font Awesome，具体选择可以参考：

https://fontawesome.com/v5.15/icons?d=gallery&p=2 内容有点多
http://www.fontawesome.com.cn/faicons/ ：看这里会比较简单直接

也可以单独增加一个带链接的菜单项，修改 config.toml：

[[menu.main]]
    name = "GitHub"
    weight = 50
    url = "https://github.com/google/docsy/"
    pre = "<i class='fab fa-github'></i>"
    post = "<span class='alert'>New!</span>"

这里同样可以使用 pre 来增加图标，用 post 来增加说明。

左侧导航菜单的设置

默认显示section所有的页面，当页面数量较多/层次较深时不太好看，而且太长也不好找内容。

可以通过 params.ui 参数来控制 sidebar 的显示：

[params.ui]
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact = true
ul_show = 1
sidebar_menu_foldable = true
sidebar_cache_limit = 100

具体解释参见： https://www.docsy.dev/docs/adding-content/navigation/#section-menu-options

为每个页面加图标

可以在左侧的 sidebar 中为每个页面设置图标，如本页面展示的：

title: "导航"
date: 2021-08-13
weight: 230
icon: fas fa-tools

可以手工添加一个链接到左侧的 sidebar，新建一个页面，内容如下：

---
title: "手工链接1"
date: 2021-08-13
weight: 231
manualLink: "https://skyao.io"
description: >
  docsy的手工链接展示
---

也可以通过 manualLinkRelref 指定一个 hugo 的 relref：

---
title: "手工链接2"
date: 2021-08-13
weight: 232
manualLinkRelref: "/docsy/content/navigation"
description: >
  docsy的手工链接展示2
---

详见：https://www.docsy.dev/docs/adding-content/navigation/#add-manual-links-to-the-section-menu

同样也可以通过 icon 来为链接增加图标。

4 - 手工链接1

docsy的手工链接展示

5 - 手工链接2

docsy的手工链接展示2

6 - 版本

docsy的多版本支持

参考：Doc Versioning | Docsy

用的时候再验证吧，现在做学习笔记没有这个需要。

7 - shortcodes

docsy的shortcodes支持

参考：Docsy Shortcodes | Docsy

Hugo让你定义和使用快捷代码，而不是从头开始编写你的所有网站页面。这些是可重复使用的内容片段，你可以将其包含在你的页面中，通常使用HTML来创造在简单的Markdown中很难或无法做到的效果。短码也可以有参数，例如，让你在一个花哨的短码文本框中添加自己的文字。除了Hugo的内置短代码，Docsy还提供了一些自己的短代码来帮助你建立你的页面。

Blocks

cover/lead/section/feature/link-down，这是 docsy 首页用到的几个 shortcode。

helpers

alert/警告

警报短代码创建了警报块，可用于显示通知或警告：

Warning

This is a warning.

color 是 theme colors, 可以是： primary, info, warning 等。

pageinfo

pageinfo短代码创建了一个文本框，您可以用它来为一个页面添加横幅信息：例如，让用户知道该页面包含占位符内容，该内容已被废弃，或者它记录了一个测试版功能。

This is placeholder content.

imgproc

imgproc短码在当前页面包中找到一张图片，并根据一组处理指令对其进行缩放。

TODO: 没想好什么情况下需要用，平时还是简单的图片插入容易直接看到图片结果

swaggerui

swaggerui短码可以放置在具有swagger布局的页面内的任何地方；它使用任何OpenAPI YAML或JSON文件作为源文件渲染Swagger UI。这可以托管在你喜欢的任何地方，例如在你的网站的根/static文件夹中。

iframe

TODO: 暂时没想到用的地方

标签式面板

这个在涉及多种实现，如多个系统/多个编程需要/多个条件时特别有用。

有时，在编写内容时，采用标签式窗格是非常有用的。一个常见的用例是显示多个语法高亮的代码块，展示同一个问题，以及如何用不同的编程语言来解决这个问题。作为一个例子，下面的表格显示了著名的Hello world！程序的特定语言变体，当人们从头开始学习一种新的编程语言时，通常会先写这个程序。

Docsy模板提供了两个快捷键tabpane和tab，让你轻松地创建标签式窗格。为了了解如何使用它们，请看下面的代码块，它显示为一个有三个标签的窗格。

    Welcome!

    Herzlich willkommen!

    Karibu sana!

标签式面板是通过两个 shortcode 实现的:

tabpane 短代码，它是标签的容器元素。这个 shortcode 可以选择性地持有命名的参数lang和/或highlight。这些可选参数的值作为第二个LANG和第三个OPTIONS参数传递给Hugo内置的highlight函数，该函数用于渲染各个标签的代码块。如果标签的标题文本等于标签代码块中使用的语言（如上面第一个标签窗格的例子），你可以在周围的标签窗格短代码中指定langEqualsHeader=true。然后，单个标签的标题文本被自动设置为各自标签的语言参数。
各种 tab 短代码，实际上代表了你想显示的标签。我们建议为每个文本指定命名参数header，以便设置每个标签的标题文本。如果需要，你还可以为每个标签指定命名参数lang和highlight。这允许你覆盖在父标签页短代码中给出的设置。如果语言既没有在tabpane中也没有在tabshortcode中指定，它默认为Hugo的站点变量 .Site.Language.Lang 。

卡片面板

在编写内容时，有时将类似的文本块或代码片

TODO: 没用过，看着不错，在需要并排展示，或者对比展示时非常有用。效果会比简单的 list 要好看。

8 - 图标图片

docsy的图标图片支持，在项目中添加和定制标识、图标和图像。

参考：Logos and Images | Docsy

Logo

在项目中添加项目标识作为 assets/icons/logo.svg。这将覆盖主题中默认的 Docsy 标志。

如果当前项目没有设置，则默认使用 docsy 模版下的 assets/icons/logo.svg 和 assets/icons/logo.png。其中在每个页面的左上角出现的 Logo 必须是要通过设置 svg 图片来覆盖，png 格式的 Logo 文件暂时还没有看到用的地方。

备注：logo 图片不要求是正方形，长方形的图片也是可以的，而且显示效果也还可以。比如 hugo 学习的 Logo 图片就是长条形的。

favicon

最简单的方法是通过 http://cthedot.de/icongen（它可以让你在一张图片上创建大量的图标尺寸和选项）和/或 https://favicon.io ，并把它们放在你的网站项目的 static/favicons 目录中。这将覆盖主题中的默认图标。

请注意，https://favicon.io 并不像Icongen那样可以创建广泛的尺寸，但可以让你快速地从文本中创建图标：如果你想创建文本图标，你可以使用这个网站来生成它们，然后使用 Icongen 从你生成的 .png 文件中创建更多尺寸（如果需要）。

如果你有特殊的favicon要求，你可以用你的链接创建你自己的 layouts/partials/favicons.html 。

实践：

准备png文件：先找一个项目对应的 Logo 文件，最好是正方形，png格式，背景透明。如果不是，用 photoshop 等工具进行修改，如通过选择工具或者抓图的方式将主体复制出来到新的图片（注意新图片的背景设置为透明），然后将画布大小调整为正方形，四周留一点空白。然后导出为 png 格式。
通过 http://cthedot.de/icongen 网站生成各种格式的 icon 文件，主要在默认的前四个选项的基础上勾选增加第五个 andord app
将生成的文件下载下来，将各种icon图片复制到当前项目下的 static/favicons 目录中

9 - 启用CSE搜索

使用google CSE来搜索站内内容

创建cse搜索

登录cse网站

https://cse.google.com/cse/all

可以看到当前已经添加的搜索引擎
添加一个搜索引擎

注意在"外观" -> “布局” 中设置 “由google托管”，然后"搜索结果会现在以下位置"中选择"当前窗口"

获取 搜索引擎 ID 之后，修改 config.toml :

gcs_engine_id = "8f763efbce07435e9"
#gcs_engine_id = "011737558837375720776:fsdu1nryfng"

在页面上尝试搜索

10 - Google Analytics

启用Google Analytics来跟踪网站访问情况

创建Google Analytics账号

https://analytics.google.com/

创建账号和媒体，拿到 Analytics ID ，如 G-4BVWTNS4MB

设置Google Analytics支持

Docsy 内建对 Google Analytics 的支持。设置方式参考官方文档：

https://www.docsy.dev/docs/adding-content/feedback/

修改 config.toml 文件：

 [services.googleAnalytics]
 id = "G-4BVWTNS4MB"

构建时的特殊设置

Ensure that your site is built with HUGO_ENV="production", as Docsy only adds Analytics tracking to production-ready sites.

确保网站构建时带有HUGO_ENV="production"，因为Docsy只在生产就绪的网站上添加分析跟踪。

需要在构建时为hugo增加环境变量：

$ env HUGO_ENV="production" hugo

11 - 百度统计

启用百度统计来跟踪网站访问情况

没有找到 docsy 主题支持百度统计的方式，只好暴力添加。

修改 docsy 主题中的 layouts/partials/footer.html 文件，在 <footer> 标签中强制加入一下内容：

<script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?17048c9d4209e5d08a9ae5b0b4160808";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>

不是一个好办法，但好歹能工作。