/yfm-docs

Создавай документацию с помощью yfm-docs в Markdown и HTML форматах

Primary LanguageTypeScriptMIT LicenseMIT

NPM version

yfm-docs

Yfm-docs позволяет собрать полноценный документационный проект: с навигацией, внутренними переходами и полной поддержкой Yandex Flavored Markdown (YFM). Например, как документация Яндекс.Облака.

Пример отображения страницы документации

Установка

npm i @doc-tools/docs -g

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

yfm -i ./input-folder -o ./ouput-folder -v "{\"name\":\"Alice\"}"

Список возможных параметров

  • --input, -i

    Путь до директории проекта (обязательный параметр).

  • --output, -o

    Путь к директории для выходных данных (обязательный параметр).

  • --allowHTML

    Разрешить использование HTML в md файлах.

  • --varsPreset

    Название используемого пресета.

  • --vars, -v

    Значения YFM переменных

  • --strict, -s

    Запуск в строгом режиме.

    Предупреждения YFM трактуются как ошибки. По-умолчанию, выключено.

  • --quiet, -q

    Запуск в тихом режиме.

    Не выводить логи в stdout. По-умолчанию, выключено.

  • --config, -c

    Путь до файла конфигурации YFM.

  • --output-format

    Формат генерации: html или md. По-умолчанию, html.

  • --apply-presets

    Подставлять ли пресеты при конвертации md2md.

  • --version

    Текущая версия.

  • --help

    Список команд.

Подробнее yfm-docs --help

Более подробное описание структуры проекта

Результат сборки

Собранный проект представляет собой набор статических HTML, которые можно просмотреть локально, разместить на хостинге, в GitHub Pages или в S3:

input-folder
|-- index.html (Разводящая страница документации)
|-- quickstart.html  (Файлы документации и изображения)
|-- pages
    |-- faq.html
    |-- how-to.html
|-- assets
    |-- image1.png
    |-- image2.png
|-- includes
    |-- faq_shared_block.html

Сборка в YFM

Так же можно собрать проект в YFM с помощью ключа --output-format=md.

В этом случае

  • будут подставлены вставки в файлах оглавлений;
  • вычислены условия в контенте и в файлах оглавлений;
  • подставлены переменные, если указан параметр apply-presets;
  • скопированы все файлы, которые указаны в файлах оглавления, и используемые в них картинки и файлы вставок.

Подробнее про переменные и условия в документации YFM.

input-folder
|-- index.yaml (Разводящая страница документации)
|-- quickstart.md (Файлы документации и изображения)
|-- pages
    |-- faq.md
    |-- how-to.md
|-- assets
    |-- image1.png
    |-- image2.png
|-- includes
    |-- faq_shared_block.md

Исходники

Установка

cd yfm-docs
npm ci && npm run build

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

npm run start -- -i ./input-folder -o ./ouput-folder -v "{\"name\":\"Alice\"}"

License

MIT