Установка и настройка

Предварительные требования

• Node.js — v18.12.1 или выше.
• Текстовый редактор, например, VS Code.
• Терминал — работа с Diplodoc осуществляется через интерфейс командной строки (CLI).

Установка

Установите пакет Diplodoc CLI, выполнив команду: npm i @diplodoc/cli -g.

Создание простого документационного проекта в YFM

Структура проекта

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

input-folder
|-- .yfm (Файл конфигурации)
|-- toc.yaml (Оглавление)
|-- presets.yaml (Пресеты переменных)
|-- index.yaml (Разводящая страница)
|-- pages (Файлы с контентом)
    |-- faq.md
    |-- how-to.md
|-- _assets (Каталог с изображениями)
    |-- image1.png
    |-- image2.png
|-- _includes (Каталог с файлами для переиспользования)
    |-- faq_shared_block.md

Больше информации про параметры и конфигурацию можно найти в разделе Документационный проект.

Локальная сборка проекта

Сборка выполняется с помощью инструмента Builder в командной строке.

Чтобы запустить сборку, выполните команду, указав обязательные ключи запуска:

• input, -i — путь до директории проекта.
• output, -o — путь до директории, предназначенной для выходных данных (статических HTML).

Пример

yfm -i ./input-folder -o ./ouput-folder

Результат

После успешного выполнения работы сборщика появляется или готовый проект HTML или проект в YFM.
Часто вывод в YFM применяется для создания подразделов и включения в крупные проекты.

Использование

Готовые проекты в HTML можно использовать локально или разместить на подходящем для Вас хостинге, включая S3-like.

Публикация на локальном сервере

Чтобы опубликовать документацию на локальном сервере, выполните команду:

npx -y @diplodoc/cli@next -i ./input-docs -o ~/output-docs --output-format html && npx http-server ~/output-docs -p 5005

Документация будет доступна по адресу http://localhost:5005

Подключение плагинов и расширенная конфигурация

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

Подробнее о способах корректного отображения и трансформации контента можно почитать на странице.

Особенностью конфигурации при построении может быть возможность отключения линтера или сборка проекта в виде одного большого HTML-файла.

Дополнительно с такими возможностями можно ознакомиться на странице.