集合中的 Jekyll 链接文档？

Question

在 Jekyll 的 Front Matter 中，有没有办法引用另一个文档？

我有一个自定义集合，并想在每个文档中添加元数据，例如“parent-topic”（到父级的链接）和“children”（文档数组）或“related-主题”。

通过这样的引用，我可以访问链接文档的元数据，例如它们的标题、url 或其他任意数据。

这个想法是文档的层次结构，包含主题、子主题、子子主题等。主题页面可以显示子主题列表或父主题的面包屑等。

Answer 1

值得真正回答的真实问题。我也遇到了这个文档问题。继advise from Ben Balter之后，我开始使用collections。这个想法是让

• 反映主题/子主题排列的目录，
• 每页都有一个面包屑导航

我放弃了，因为针对 pages 进行编码是最简单的。所以，这就是我用页面做文档的方法。

先决条件：

• 文档在一个文件夹中，例如：文档

• permalink 在 _config.yml 中设置为 pretty

• 文件夹层次结构描述文档组织

示例

documentation
|--index.html
|--chapter-1
|  |--index.html
|
|--chapter-2
|  |--index.html
|  |
|  |--part-1
|  |  |--index.html
|  |  |--subpart-1
|  |     |--index.html
|  |--part-2
|  |  |--index.html
|  |
|  |--part-3.html

注意：documentation/chapter-2/part-2/index.html也可以是documentation/chapter-2/part-2.html，因为permalink设置为pretty，生成的页面会在documentation/chapter-2/part-2/index.html。

• 同一级别的页面根据weight front matter 变量进行排序。这可以是你想要的任何东西。 第十位编号便于插入新文档。

前面的例子

---
title: My title
weight: 10
---

• 文档从_config.yml 获取默认变量值

示例

defaults:
  -
    scope:
      path: "documentation"
      type: pages

    values:
      isDoc: true # allows quick extraction from site.pages
      layout: page

一旦满足这些先决条件，就可以轻松打印目录和面包屑。

目录

_includes/show-children.html

{% assign parentDir = include.dir %}
{% if parentDir == nil %}<h1>You must specify a root directory</h1>{% endif %}

{% assign allDocs = include.docs %}
{% if allDocs == nil %}{% assign allDocs = site.pages | sort: "weight" %}{% endif %}

{% assign level = include.level %}
{% if level == nil %}{% assign level = parentDir | remove_first: "/" | split:"/" | size %}{% endif %}

{% assign maxLevel = include.maxLevel %}
{% if maxLevel == nil %}{% assign maxLevel = 100 %}{% endif %}

{% assign nextLevel = level | plus : 1 %}

{% comment %}+++++++++++++++++++++++++++++++++++++++++++++++++
Looking for all page in this path with the same level (siblings)
This avoid to deep recursion and error like :
__ Liquid Exception: Nesting too deep __
+++++++++++++++++++++++++++++++++++++++++++++++++{% endcomment %}

{% assign siblings = "" | split: "/" %}
{% for s in allDocs %}
    {% assign sPageLevel = s.url | remove_first: "/" | split:"/" | size %}
    {% if sPageLevel == level and s.url contains parentDir %}
        {% if s.title %}{% assign siblings = siblings | push: s %}{% endif %}
    {% endif %}
{% endfor %}

<ul>
{% for p in siblings %}
    <li><a href="{{site.baseurl}}{{p.url}}"{%if p.url == page.url%} class="active"{%endif%}>{{ p.title }}</a>
    {% if nextLevel <= maxLevel %}
      {% include show-children.html dir=p.dir docs=allDocs level=nextLevel maxLevel=maxLevel %}
    {% endif %}
    </li>
{% endfor %}
</ul>

{% comment %}+++++++++++++++++++++++++++++++++++++++++++++++++
Because all variables are globales (all includes have the same scope)
we restore level and nextLevel variables to parent values
+++++++++++++++++++++++++++++++++++++++++++++++++{% endcomment %}
{% assign level = level | minus : 1 %}
{% assign nextLevel = nextLevel | minus : 1 %}

使用

可以使用多个参数调用此包含：

dir：要探索的根目录（即：/documentation）

docs ：页面数组 - 默认为 site.pages

level：我们开始打印的级别（/documentation 处于级别 1， /documentation/chapter-1 处于第 2 级，依此类推） 默认为 'dir' 级别

ma​​xLevel：停止打印的位置 - 默认为 100

Extracting documentation pages
{% assign documents = site.pages | where: "isDoc", true | sort: "weight" %}
{% assign dir = "documentation" %}

This will print all documentation hierachy
{% include show-children.html dir=dir docs=documents %}

This will start printing at level 2
{% include show-children.html dir=dir docs=documents level=2 %}

This stop printing at level 2
{% include show-children.html dir=dir docs=documents maxLevel=2 %}

在页面布局上，如果您只想打印页面子级，您可以这样做：

{% assign documents = site.pages | where: "isDoc", true | sort: "weight" %}
{% assign level = page.dir | remove_first: "/" | split:"/" | size %}
{% assign childrenLevel = level | plus : 1 %}
{% include show-children.html docs=documents dir=page.dir level=childrenLevel %}

面包屑

_includes/breadcrumb.html

{% assign minLevel = include.minLevel %}
{% if minLevel == nil %}{% assign minLevel = 1 %}{% endif %}

<div class="breadcrumb">
<p>You are here : </p>
{% assign documents = site.pages | where: "isDoc", true | sort: "weight" %}
{% include get-parents.html page=page minLevel=minLevel docs=documents %}
<p>{{ page.title }}</p>
</div>

<style type="text/css">
.breadcrumb p { display: inline; }
.breadcrumb p+p+p:before { content:"» "; }
</style>

_includes/get-parents.html

{% assign currentPage = include.page %}
{% assign minLevel    = include.minLevel %}
{% assign allDocs     = include.docs %}
{% assign pageLevel   = currentPage.dir | remove_first: "/" | split:"/" | size %}
{% assign parentLevel = pageLevel | minus: 1 %}
{% if parentLevel >= minLevel %}
    {% for p in allDocs %}
        {% assign pPageLevel = p.dir | remove_first: "/" | split:"/" | size %}
        {% if pPageLevel == parentLevel and currentPage.dir contains p.dir %}
            {% include get-parents.html page=p minLevel=minLevel docs=allDocs %}
            <p><a href="{{site.baseurl}}{{p.url}}">{{ p.title }}</a></p>
        {% endif %}
    {% endfor %}
{% endif %}

使用

打印Documentation > chapter 1 > part 1

{% include breadcrumb.html %}

打印Chapter 1 > part 1

{% include breadcrumb.html minLevel=2 %}

可以更简单吗？

Working code can be found here.