Skip to content

Мой плагин на Python для MkDocs

Код плагина

Зачем это было сделано?

Когда я начинал работу с MkDocs, я сразу обратил внимание на структуру и организацию файлов. Меня смутил момент, что у нас не единственный источник истины!

Другими словами мы должны:

  1. Описать наш файл в mkdocs.yml файле
  2. Следить чтобы они существовали в директории

Это накладывает некоторые ограничения и неудобства, и я часто сталкивался с проблемой, что мне нужно создать большое количество страничек, разделов, а также создание всех этих же файлов ВРУЧНУЮ.

Конечно же я сразу полез искать готовые решения, и нашёл, но не в том формате в котором мне это виделось.

Нашёл решение mkdocs-simple-hooks, но оно не подходило под мой запрос.

В случае использования этого плагина, всё равно всё сводилось к тому, что приходилось бы вручную создавать кучу файлов, папок для разделов.

Я в этот момент я подумал:

Нужно написать своё решение для этого!

Как это работает?

Мой плагин предоставляет возможность редактировать исключительно mkdocs.yml, и автоматически создаёт недостающие директории / файлы.

Таким образом можно быстро накидать структуру того, какие разделы будут вложены друг в друга, и уже иметь полностью готовое пространство для этого.

# Функции возвращают множества:
# 1. real_files - файлы которые существуют в директории 
# 2. nav_files - файлы описаны в .yml в блоке nav

real_files = get_real_docs_files(str(docs_dir))
nav_files = get_mkdocs_nav_files(str(mkdocs_yml_path))

if real_files == nav_files:
    print("Изменений нет!")
    return

В отличии от плагина который я приводил выше, тут единственным источником правды выступает .yml файл, а не файловая система.

Это полностью закрывает потребность в необходимости вручную создавать что-либо из директорий/файлов.

Намеренное решение

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

# Реализация в коде

if untracked_files:
    print("Не добавленные в mkdocs.yml:")
    for f in sorted(untracked_files):
        print(f" - {f}")