Zola教程:3-导航

2023-05-31

rust zola

链接

标题链接

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显示。