链接

标题链接

zola会为每个标题（heading，也即markdown的一个或多个#开头的文字）自动生成唯一的id。如果slugify.anchors设置成on（默认），zola会通过将标题内容转换成slug来生成id。如果slugify.paths=safe，生成的id中的空格会被下划线替换，并且移除以下字符：#，%，<，>，[，]，(，)，`，^，{，|，}。如果 slugify.paths=off则不对id做这些处理，但是会产生一些不合法的id。如果有多个相同的标题，会在id的结尾附加数字来区分。我们来看一些例子：

# Something exciting! <- something-exciting
## Example code <- example-code

# Something else <- something-else
## Example code <- example-code-1

你也可以主动给heading加上自定义的id，以及css样式：

# Something manual! {#manual .header .bold}

zola的这个特性在生成深度链接时非常有用，修改了标题不会让已有的链接中断，另外合并站点时也不会因为站点之间id规则不同产生问题。

锚点链接

zola可以自动在标题后面插入锚点链接，这可以通过在section的Front matter中设置insert_anchor_links来实现。insert_anchor_links可取的值有"left", "right", "heading" 和 "none"。默认的模板非常简单，你可能需要调整一下CSS样式让结果显得好看一点。也可以在模板目录下创建一个anchor-link.html模板来覆盖默认的样式。默认的模板内容是这样的：

<a class="zola-anchor" href="#{{ id }}" aria-label="Anchor link for: {{ id }}"> </a>

在这个模板中可以用的变量包括：

• id：为标题自动生成的id
• lang：当前的语言
• level：标题级别，1到6

如果设置了insert_anchor = "heading"，模板文件仍然会被使用，但是只有<a>标签会从模板文件提取出来，其余内容都不会用上。

内部链接

由于链接到其他页面及其标题是很常见的操作，Zola为此加了一种专门的Markdown链接格式，在链接前面加上@/，指向一个md文件，文件的路径从content目录开始算起。

例如，指向文件content/pages/about.md的链接是my link ，同时你也可以直接指向一个链接：[my link](@ /pages/about.md#example)

默认的，不合法的内部链接被看作error，如果想当成warning，需要在config.toml的[link_checker]部分设置internal_level = "warn"。不过要注意的是对于错误的内部链接，zola无法正确处理，因为会直接渲染成HTML的链接，例如[my link](@ /pages/whoops.md)就会被渲染成<a href="@ /pages/whoops.md"> 。

目录

每个page和section都会基于markdown的标题结构自动生成一个目录。可以在模板中通过page.toc 或 section.toc 变量来使用目录。

toc是一个Header的数组，header包含以下属性：

// The hX level
level: 1 | 2 | 3 | 4 | 5 | 6;
// The generated slug id
id: String;
// The text of the header
title: String;
// A link pointing directly to the header, using the inserted anchor
permalink: String;
// All lower level headers below this header
children: Array<Header>;

下面是一个渲染两级目录结构的例子：

{% if page.toc %}
 <ul>
 {% for h1 in page.toc %}
 <li>
 <a href="{{ h1.permalink | safe }}">{{ h1.title }}</a>
 {% if h1.children %}
 <ul>
 {% for h2 in h1.children %}
 <li>
 <a href="{{ h2.permalink | safe }}">{{ h2.title }}</a>
 </li>
 {% endfor %}
 </ul>
 {% endif %}
 </li>
 {% endfor %}
 </ul>
{% endif %}

分类学

概念

zola内置了分类学（taxonomies）的支持，可以让用户对内容进行分组。

• Taxonomy: 可以对内容进行分组的一个类别（Category）
• Term: taxonomy中的一个分组
• Value: 可以绑定到Term的一部分内容

示例

这是一个视频网站的例子。假设你有一个网站用来展示不同电影的信息，你可能需要的分类信息有：

• Director
• Genres
• Awards
• Release year

zola在build时可以生成taxonomy列表，每个taxonomy包含term列表，每个term包含的page列表，如下所示：

- Shape of water                   <--- Value
  - Director                         <--- Taxonomy
    - Guillermo Del Toro                 <--- Term
  - Genres                            <--- Taxonomy
    - Thriller                           <--- Term
    - Drama                              <--- Term
  - Awards                           <--- Taxonomy
    - Golden globe                         <--- Term
    - Academy award                        <--- Term
    - BAFTA                                <--- Term
  - Release year                      <--- Taxonomy
    - 2017                                <--- Term
    
- The Room:                         <--- Value
  - Director                           <--- Taxonomy
    - Tommy Wiseau                         <--- Term
  - Genres                              <--- Taxonomy
    - Romance                              <--- Term
    - Drama                                <--- Term
  - Release Year                       <--- Taxonomy
    - 2003                                 <--- Term

- Bright                           <--- Value
  - Director                           <--- Taxonomy
    - David Ayer                           <--- Term
  - Genres                              <--- Taxonomy
    - Fantasy                              <--- Term
    - Action                               <--- Term
  - Awards                             <--- Taxonomy
    - California on Location Awards        <--- Term
  - Release Year                       <--- Taxonomy
    - 2017                                 <--- Term

在这个例子中，Release year的列表包含2003和2017的所有电影，其中2017包含的电影有Shape of Water 和 Bright。

配置

taxonomy有6个属性：

• name：名字，通常会在url中用到
• paginate_by：如果设置成数字，taxonomy下的term会被分页
• paginate_path：如果设置了，分页的path会在这个值后面加上数字，例如page/1
• feed：如果设置为true，每个term会生成一个feed（默认是atom格式）
• lang：只在多语言站点中生效，指明这个taxonomy对那个语言生效
• render：如果为false，属于这个taxonomy或者单独某个term的页面不会被渲染

下面是单语言的配置，注意配置项要放在main section，而不是[extra] section：

taxonomies = [
 { name = "director", feed = true},
 { name = "genres", feed = true},
 { name = "awards", feed = true},
 { name = "release-year", feed = true},
]

多语言的配置例子如下：

# These taxonomies go in the main section
taxonomies = [
 {name = "director", feed = true},
 {name = "genres", feed = true},
 {name = "awards", feed = true},
 {name = "release-year", feed = true},
]

[languages.fr]
taxonomies = [
 {name = "director", feed = true},
 {name = "genres", feed = true},
 {name = "awards", feed = true},
 {name = "release-year", feed = true},
]

使用

设置好之后，你就可以在内容中添加分类信息：

+++
title = "Shape of water"
date = 2019-08-15 # date of the post, not the movie
[taxonomies]
director=["Guillermo Del Toro"]
genres=["Thriller","Drama"]
awards=["Golden Globe", "Academy award", "BAFTA"]
release-year = ["2017"]
+++

Path

在path中，taxonomy不会被slugified，term会根据slugify.taxonomies配置做slugified（设置为on时会被slugified）。

taxonomy页面的path示例：

$BASE\_URL/$NAME/ (taxonomy)
$BASE\_URL/$NAME/$SLUG (taxonomy entry)

注意的是taxonomy名字是不区分大小写的，相同的slug的term会被合并。有相同tag的page和section会在同一个taxonomy显示。