如何在Markdown导航文件(mkdocs.yml)中向树节点添加永久链接? [英] How to add permalinks to tree nodes in Markdown nav file (mkdocs.yml)?
问题描述
我正在使用的mkdocs.yml导航文件包括手册网站的分层树，其中包含内容文章所属的几个类别和子类别；该树绝对是虚拟的，并不基于文件夹结构/网站路径.我正在寻找一种为树的每个节点(类别)生成永久链接的方法. 如果用Markdown或其扩展名无法做到这一点，则可以使用html/css元素.
The mkdocs.yml nav file I am working with includes a hierarchical tree of a manuals website with several categories and subcategories the content articles fall into; the tree is absolutely virtual and not based on a folder structure/website path. I am looking for a way to generate permalinks for each of the tree's nodes (categories). If that is impossible with Markdown or its extensions than perhaps html/css elements could be used.
我对Markdown和mkdocs很陌生；我在Google上进行了彻底的搜索以获取解决方案，但没有找到解决方案.
I am very new to Markdown and mkdocs; I googled thoroughly to get a solution but failed to find one.
site_name: My Site
site_dir: docs/guides/
site_url: http://example.net/
docs_dir: 'src'
nav:
- 'TOP LEVEL CATEGORY':
- 'BOTTOM LEVEL CATEGORY':
- Manual 1: 'manuals/Manual1.md'
- Manual 2: 'manuals/Manual2.md'
- 'BOTTOM LEVEL 2':
{...}
- 'TOP LEVEL CATEGORY 2':
{...}
markdown_extensions:
- smarty
- toc:
permalink: True
separator: "_"
- sane_lists
- tables
- meta
- fenced_code
- admonition
- footnotes
可以构建带有可扩展节点的虚拟层次树，但是我确实需要为每个类别和子类别生成永久链接，例如 example.net/docs/guides/toplevelcat/bottomlevelcat 或者 example.net/docs/guides/toplevelcat#bottomlevelcat 链接的组织方式，是否自动生成或手动预设都无所谓
The virtual hierarchical tree with expandable nodes which is built is all right, but I really need to generate permalinks for each category and subcategory, e.g. example.net/docs/guides/toplevelcat/bottomlevelcat or example.net/docs/guides/toplevelcat#bottomlevelcat it does not matter how exactly the links will be organized and whether they are generated automatically or preset manually
该链接可能会导致一个索引页面，其中所有手册都属于该类别，或者仅显示根目录 mysite.net/docs/guides/并扩展了所需的类别
the link could lead to an index page with all manuals belonging to the category OR just display the root mysite.net/docs/guides/ page with the required category expanded
推荐答案
This is not supported by MkDocs at this time, but may be possible with a custom theme.
在#1042 中，您可以找到最终解决方案的尝试由于多种原因而被拒绝.也就是说，您应该能够使用自定义主题模拟类似内容.
In #1042, you can find an attempt at a solution which was ultimately rejected for a number of reasons. That said, you should be able to simulate something similar with a custom theme.
MkDocs不在乎nav的结构是否匹配任何实际的文件结构.因此，您可以根据需要安排嵌套结构.只要确保任何节"的第一个孩子都指向索引文件即可.也许是这样的:
MkDocs does not care if the structure of the nav matches any actual file structure. So you can arrangement the nesting structure however you want. Just make sure the first child of any "section" points at an index file. Perhaps something like this:
nav:
- 'TOP LEVEL CATEGORY':
- 'toplevel1/index.md'
- 'BOTTOM LEVEL CATEGORY':
- 'bottomlevel1/index.md'
- Manual 1: 'manuals/Manual1.md'
- Manual 2: 'manuals/Manual2.md'
- 'BOTTOM LEVEL 2':
- 'bottomlevel2/index.md'
请注意，每个部分都包含一个唯一的索引文件.当然，索引文件必须命名为index.md，因此使它们唯一的唯一方法是使每个文件都位于唯一的子目录中.另请注意，没有标题分配给索引页.大概将使用该部分的标题.
Note that each section includes a unique index file. Of course index files must be named index.md so the only way to make them unique is for each one to be in a unique subdirectory. Also notice that there is no title assigned to the index pages. Presumably, the section title will be used.
然后，在主题模板中，您需要检查子项，如果第一个子项是索引，请使用该子项作为该部分的链接.然后，在遍历子级时，请确保跳过嵌套级别中的索引.
Then in your theme template you need to check for children and if the first child is an index, use that as the link for that section. Then when looping through the children, be sure to skip the index in the nested level.
也许是这样的:
{% if nav|length>1 %}
<ul>
{% for nav_item in nav %}
{% if nav_item.children %}
<li>{% if nav_item.children[0].is_index %}
<a href="{{ nav_item.children[0].url|url }}">{{ nav_item.title }}</a>
{% else %}
{{ nav_item.title }}
{% endif %}
<ul>
{% for nav_item in nav_item.children[1:] %}
<li class="{% if nav_item.active%}current{% endif %}">
<a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
</li>
{% endfor %}
</ul>
</li>
{% else %}
<li class="{% if nav_item.active%}current{% endif %}">
<a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
</li>
{% endif %}
{% endfor %}
</ul>
{% endif %}
By way of explanation, the above is simply a slightly modified version of the example in the docs. Where the section title was displayed in the original ({{ nav_item.title }}), we instead check if the first child is an index file and, if so, display a link to the index page instead. Of course, we include a fallback for those occasions where there is no index.
{% if nav_item.children[0].is_index %}
<a href="{{ nav_item.children[0].url|url }}">{{ nav_item.title }}</a>
{% else %}
{{ nav_item.title }}
{% endif %}
然后，在遍历子级时，我们希望避免包括索引文件.在示例中，我使用了{% for nav_item in nav_item.children[1:] %}([1:]对列表进行切片以排除第一项)，但是假定始终存在一个索引文件.其他一些解决方案可能更好，留给读者练习. Jinja文档在这里可能会有所帮助.
Then when stepping through the children, we want to avoid including the index file. I used {% for nav_item in nav_item.children[1:] %} in my example ([1:] slices the list to exclude the first item), but that assumes there always is an index file. Some other solutions may be better and left as a exercise for the reader. The Jinja documentation may be helpful here.
还请注意，以上模板仅说明了一层嵌套.需要开发一种更复杂的解决方案来处理多个嵌套级别.例如，您可能想定义一个Jinja宏，每个级别都递归调用.
Also note that the above template only accounts for one level of nesting. A more sophisticated solution would need to be developed to handle multiple nesting levels. For example, you might want to define a Jinja macro, which each level calls recursively.
还要注意的是，您不需要开发完整的自定义主题.您可能想覆盖模板块.
Also of note is that you don't need to develop a complete custom theme. You might want to instead override a template block of an existing theme which your own custom navigation.
这篇关于如何在Markdown导航文件(mkdocs.yml)中向树节点添加永久链接?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
