Как добавить постоянные ссылки на узлы дерева в навигационном файле Markdown (mkdocs.yml)?
Навигационный файл mkdocs.yml, с которым я работаю, содержит иерархическое дерево веб-сайта руководств с несколькими категориями и подкатегориями, в которые попадают статьи; дерево является абсолютно виртуальным и не основано на структуре папок / пути к веб-сайту. Я ищу способ создания постоянных ссылок для каждого из узлов дерева (категорий). Если это невозможно с Markdown или его расширениями, возможно, можно использовать элементы html / css.
Я очень плохо знаком с Markdown и mkdocs; Я тщательно погуглил, чтобы найти решение, но не смог его найти.
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 не имеет значения, как именно будут организованы ссылки и будут ли они генерироваться автоматически или заданы вручную
ссылка может привести к странице индекса со всеми руководствами, относящимися к категории, ИЛИ просто отобразить корневую страницу mysite.net/docs/guides/ с расширенной требуемой категорией.
1 ответ
Это не поддерживается MkDocs в настоящее время, но может быть возможно с пользовательской темой.
В #1042 вы можете найти попытку найти решение, которое в конечном итоге было отклонено по ряду причин. Тем не менее, вы должны иметь возможность симулировать нечто похожее с пользовательской темой.
MkDocs не волнует, если структура nav соответствует любой фактической файловой структуре. Таким образом, вы можете расположить структуру вложений так, как хотите. Просто убедитесь, что первый дочерний элемент любого "раздела" указывает на индексный файл. Возможно, что-то вроде этого:
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 поэтому единственный способ сделать их уникальными - это чтобы каждый находился в уникальном подкаталоге. Также обратите внимание, что заголовок страниц индекса не назначен. Предположительно, будет использоваться заголовок раздела.
Затем в шаблоне вашей темы вы должны проверить наличие детей, и если первый ребенок является индексом, используйте его в качестве ссылки для этого раздела. Затем, просматривая дочерние элементы, обязательно пропустите индекс на уровне вложенности.
Возможно, что-то вроде этого:
{% 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 %}
В порядке пояснения, приведенное выше - просто слегка измененная версия примера в документации. Где заголовок раздела отображался в оригинале ({{ nav_item.title }}), вместо этого мы проверяем, является ли первый дочерний элемент индексным файлом, и, если да, вместо этого отображаем ссылку на индексную страницу. Конечно, мы включаем запасной вариант для тех случаев, когда нет индекса.
{% 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 может быть полезна здесь.
Также обратите внимание, что приведенный выше шаблон учитывает только один уровень вложенности. Потребуется разработать более сложное решение для обработки нескольких уровней вложенности. Например, вы можете определить макрос Jinja, который каждый уровень вызывает рекурсивно.
Также следует отметить, что вам не нужно разрабатывать полную пользовательскую тему. Вы можете вместо этого переопределить блок шаблона существующей темы, который является вашей собственной пользовательской навигацией.
Я реализовал плагин для этой функции, " https://github.com/oprypin/mkdocs-section-index ", и он работает аналогично тому, что описывает @Waylan - или фактически более похож на отброшенный запрос на перенос # 1042, потому что большая часть логики находится вне темы / шаблон. Специальные разделы со ссылкой явно помещаются в навигацию и представляются как таковые в теме, поэтому нет необходимости искать и исключать самого этого "первого потомка".
mkdocs.yml:
plugins:
- section-index
nav:
- Frob: index.md
- Baz: baz.md
- Borgs:
- borgs/index.md
- Bar: borgs/bar.md
- Foo: borgs/foo.md
Это дает вам такую навигацию:
Для меня имеет смысл, что эта функция не может быть включена по умолчанию, но плагин как способ выбора кажется совершенно нормальным.