更新时间:2023-11-10 18:14:40
真正的问题,应该得到真正的答案.我也遇到了这个文档问题.遵循从Ben Balter提出的建议,我开始使用collections
.这个想法是使
Real question that deserve a real answer. I also got this documentation problem. Following advise from Ben Balter, I started to use collections
. The idea was to make
我放弃是因为针对pages
进行编码最简单.因此,这是我如何处理页面文档.
I gave up because it was simplest to code against pages
. So, here's how I do documentation with pages.
文档位于文件夹中,例如:documentation
documentation is in a folder eg : documentation
permalink
设置为pretty
文件夹层次结构描述了文档组织
folders hierarchy describes documentation organization
示例
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
.
Note : documentation/chapter-2/part-2/index.html
can also be documentation/chapter-2/part-2.html
, because permalink
is set to pretty
, generated page will be at documentation/chapter-2/part-2/index.html
.
weight
前题变量进行排序.这可以是您想要的任何东西.
十分之一编号可以轻松插入新文档.weight
front matter variable. This can be anything you want.
Numbering by tenth allows easy insertion for new doc.前事示例
---
title: My title
weight: 10
---
_config.yml
_config.yml
示例
defaults:
-
scope:
path: "documentation"
type: pages
values:
isDoc: true # allows quick extraction from site.pages
layout: page
一旦具备这些先决条件,就很容易打印目录和面包屑.
Once those prerequisites are in place, it's easy to print a table of content and a breadcrumb.
_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 %}
可以使用几个参数调用这个include:
This include can be called with several arguments :
dir :要探索的根目录(即:/documentation)
dir : root dir to explore (ie : /documentation)
文档:一组页面-默认为site.pages
docs : an array of pages - default to site.pages
级别:我们开始打印的级别(/文档处于级别1, /documentation/chapter-1位于级别2,依此类推) 默认为目录"级别
level: level at which we start printing (/documentation is at level 1, /documentation/chapter-1 is at level 2, and so on) Default to 'dir' level
maxLevel :在何处停止打印-默认为100
maxLevel: where to stop to print - default to 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 %}
在页面布局上,如果您只想打印页面孩子,则可以执行以下操作:
On page layout if you just want to print page children you can do :
{% 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 %}
可以更简单吗?