Как добавить постоянные ссылки на узлы дерева в навигационном файле Markdown (mkdocs.yml)? - PullRequest
Новая
       17

Как добавить постоянные ссылки на узлы дерева в навигационном файле Markdown (mkdocs.yml)?

0 голосов
/ 08 февраля 2019

Навигационный файл 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 Ответ

0 голосов
/ 08 февраля 2019

Это не поддерживается 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, который каждый уровень вызывает рекурсивно.

Также следует отметить, что вам не нужно разрабатывать полную пользовательскую тему.Возможно, вы захотите вместо переопределить шаблонный блок существующей темы, которая является вашей собственной пользовательской навигацией.

...