Настройки YFM-проекта
Настройки проекта указываются в yaml-файле .yfm в корне документа. При сборке можно указать путь до другого файла с помощью ключа запуска --config.
Некоторые параметры можно задать или переопределить через ключи запуска сборки.
Пример файла .yfm
# Корневая секция параметров
allowHtml: false
# Настройки интерфейса документации
interface:
favicon-src: https://raw.githubusercontent.com/yandex-cloud/yfm-documentation/master/_images/logo_blue_32x32.png
# Секция параметров вьюера (docs-viewer)
docs-viewer:
# Настройки логотипа
logo-options:
url: https://diplodoc.com/docs/{lang}/
src: https://storage.yandexcloud.net/docs-external/yfm-documentation/_images/logo.svg
src-dark: https://storage.yandexcloud.net/docs-external/yfm-documentation/_images/logo.svg
src-mobile: https://storage.yandexcloud.net/docs-external/yfm-documentation/_images/logo.svg
src-mobile-dark: https://storage.yandexcloud.net/docs-external/yfm-documentation/_images/logo.svg
src-preview: https://storage.yandexcloud.net/docs-external/yfm-documentation/_images/share-logo-dark.svg
# Если логотипа нет, то вместо него можно задать текст
title: Yandex Flavored Markdown
Корневая секция .yfm
|
Параметр |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Разрешить загрузки пользовательских ресурсов в статически сгенерированные страницы. |
|
|
|
Разрешить использование html-элементов в разметке. |
|
|
|
Применять ли пресеты переменных. |
|
|
Включить отображение автора статьи. Пример:
Параметры:
Значение Работает при включенном параметре vcs. |
|
|
|
|
Задать корневой путь, по которому документация будет окрываться на сайте. Пример:
Значение этого параметра:
Важно: для построения абсолютной ссылки к значению baseHref всегда справа добавляется символ |
— |
|
|
Переносить строки по символу перевода каретки. |
|
|
|
Включить отображение контрибьюторов в статье. Пример:
Параметры:
Значение Работает при включенном параметре vcs. |
|
|
|
Отключить добавление мета-тега Content-Security-Policy в сгенерированные HTML-страницы. Используйте, когда CSP управляется внешним образом (например, через HTTP-заголовки сервера). |
|
|
|
Список расширений Diplodoc, используемых для сборки проекта. Объекты в списке должны содержать параметр
Строками в списке можно в упрощенном формате задавать названия расширений:
|
— |
|
|
Настройки отправки обратной связи в статически сгенерированной документации. |
Не задан |
|
|
Массив языков, участвующих в сборке. |
— — |
|
|
Преобразовывать ссылкоподобные строки в ссылки. Примеры строк:
|
|
|
|
Подключить файл линтера. |
|
|
|
Настройки генерации файлов llms.txt и llms-full.txt для проекта:
Параметры:
|
— |
|
|
Включить отображение даты изменения статьи, которая берётся из данных VCS. Работает при включенном параметре vcs. Также, дата изменения автоматически добавляется в метаданные страницы last-modified и article:modified_time. |
|
|
|
Формат файлов итоговой сборки: |
|
|
|
Убрать из сборки все файлы, отмеченные в |
|
|
|
Включает очистку HTML-разметки от потенциально опасных элементов в |
|
|
|
Собирать одностраничную сборку. Будет создан файл Страница будет доступна по адресу
|
|
|
|
Генерировать файл |
|
|
|
Собирать html-контент статьи как часть вёрстки. По умолчанию, он находится в js-объекте и вставляется в страницу на этапе отрисовки в браузере. |
|
|
|
Строгий режим сборки, все предупреждения YFM отображаются как ошибки. С полным списком правил YFM можно ознакомиться здесь. |
|
|
|
Генерировать дополнительные якоря, совместимые с GitHub. |
|
|
|
Настройка для базового цвета в темизаторе. Переопределяет base-brand в основной секции конфигурационного файла theme.yaml. Подробнее о темизаторе. |
По умолчанию базовый цвет не меняется. |
|
|
Имя пресета переменных, который необходимо использовать при сборке. |
— |
|
|
Настройка подключения к vcs системе. Её включение позволяет использовать функциональности mtimes, authors и contributors. Требует подключения встроенного расширения |
|
Секция ai
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Включить добавление markdown-версий (markdown-компаньонов) страниц в итоговую сборку документации: |
|
|
|
Включить добавление json-схем OpenAPI-спецификаций в виде файлов |
|
Секция analytics
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Настройки аналитики Google Tag Manager. Параметры:
|
— |
|
|
Подключение счётчиков Яндекс Метрики. Каждый элемент списка — объект с обязательным полем Минимальная конфигурация:
Пример с несколькими счётчиками
В подключенные счётчики из интерфейса документации отправляются цели. |
— |
Секция content
Управление обработкой и проверками контента статей.
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Максимально допустимый размер ассета в проекте. В случае превышения сборка завершится с ошибкой. Принимает числа и строки: 1024, 512K, 8M. Если указать 0, то проверка размера ассетов выполняться не будет. |
|
|
|
Максимально допустимый размер html-контента статьи после сборки. В случае превышения сборка завершится с ошибкой. Принимает числа и строки: 1024, 512K, 8M. Максимальное значение — 96M. |
|
|
|
Максимально допустимый размер svg-изображения, при котором оно инлайнится в контент статьи автоматически. В случае превышения размера svg-изображение вставляется через тег <img>. Принимает числа и строки: 1024, 512K, 2M. Если указать 0, то svg-изображения не будут инлайниться при сборке. Максимальное значение — 16M. |
|
|
|
Максимально допустимый размер json-схемы в тексте оглавления собранной OpenAPI-спецификации. В случае превышения размера, json-схема не добавляется на страницу напрямую, а вставляется ссылкой для загрузки (режим Принимает числа и строки вида: 1024, 512K, 2M. Если указать 0, режим вставки json-схем |
|
|
|
Могут ли всплывающие подсказки содержать контент с множественными переносами строк:
|
|
Секция feedback
Задаёт адрес для отправки обратной связи в статически сгенерированной HTML-документации. Добавьте секцию в корень файла .yfm:
feedback:
url: https://api.example.com/feedback
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
URL обработчика обратной связи. |
Не задан |
Обработчик должен принимать POST-запросы с Content-Type: application/json. Вместе с отзывом передаются путь страницы (page) и время отправки в формате ISO 8601 (timestamp). Для адреса на другом домене настройте CORS на стороне обработчика.
Без feedback.url форма обратной связи в статике не отображается. Чтобы скрыть её при заданном URL, установите interface.feedback: false в .yfm или в метаданных отдельной страницы.
Секция interface
Настройки отображения интерфейса. Все настройки из секции можно переопределять для отдельных статей, указывая их значения в метаданных страниц.
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Иконка во вкладке браузера. |
— |
|
|
Управляет отображением формы обратной связи. Значение |
|
|
|
Открывать изображения и видео в галерее. По умолчанию включено. |
|
|
|
Задать отображение действий Скопировать как Markdown и Открыть Markdown: отдельными кнопками ( |
|
|
|
Скрывает поиск. Если не указан, поиск считается включенным. |
|
|
|
Скрывает оглавление (Table of contents, ToC). Если не указан, ToC считается включенным. |
|
|
|
Скрывает заголовок в ToC. Если не указан, заголовок считается включенным. |
|
Секция pdf
Настройки генерации PDF-версии документации и кнопки скачивания.
Поля enabled, hiddenPolicy и showAbsoluteUrls управляют генерацией. Поля icon, position, size и pdfFileUrl настраивают кнопку скачивания. В статической HTML-сборке ссылка появляется при заданном pdfFileUrl. Включения enabled для этого недостаточно.
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Включает подготовку данных для генератора |
|
|
|
При значении |
|
|
|
Добавляет абсолютные HTTP(S)-адреса в скобках после текста ссылок в PDF. Если текст ссылки уже совпадает с адресом, адрес не дублируется. Подробнее: Адреса ссылок в PDF. |
|
|
|
Иконка кнопки скачивания: SVG-разметка, абсолютный URL изображения или путь от корня проекта, начинающийся с |
Стандартная иконка PDF |
|
|
Расположение кнопки скачивания: |
|
|
|
Размер кнопки скачивания. Если не задан, наследуется от панели управления. Перед использованием см. ограничение ниже. |
Не задан |
|
|
URL или путь к готовому PDF-файлу для кнопки скачивания в статической HTML-сборке. Сам файл нужно сгенерировать и опубликовать отдельно. Во Viewer адрес PDF вычисляется автоматически. |
Не задан |
Примечание
Для size пока есть ограничение: схема .yfm допускает S, M, L, а интерфейс использует m, l, xl. До согласования этих значений оставляйте параметр незаданным: кнопка унаследует размер панели управления.
Пример .yfm для статической HTML-сборки с кнопкой в шапке:
pdf:
enabled: true
hiddenPolicy: true
showAbsoluteUrls: true
icon: _assets/pdf-icon.svg
position: header
pdfFileUrl: ./single-page.pdf
Поместите изображение иконки в _assets/pdf-icon.svg и опубликуйте PDF по адресу, указанному в pdfFileUrl.
Титульные и закрывающие страницы задаются отдельно в toc.yaml: pdf.startPages и pdf.endPages.
Секция resources
Управление подключаемыми к проекту ресурсами.
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Управление Content Security Policy (CSP). Пример структуры
Данная конфигурация преобразуется в HTML-тег вида:
Ключи объекта соответствуют поддерживаемым директивам CSP. Система не проверяет корректность указанных значений — они берутся из |
— |
|
|
Список подключаемых ко всем страницам проекта javascript-файлов.
Для подключения скриптов должен быть установлен параметр allowCustomResources: true. |
— |
|
|
Список подключаемых ко всем страницам проекта css-файлов.
Для подключения стилей должен быть установлен параметр allowCustomResources: true. |
— |
Секция template
Управление поддерживаемыми конструкциями синтаксиса шаблонов.
|
Параметр |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Включает обработку синтаксиса шаблонов в документации. Если не указан, шаблонизация считается включенной. |
|
|
|
||
|
|
Включает обработку синтаксиса условных операторов в блоках кода. |
|
|
|
Включает обработку синтаксиса условных операторов в тексте документа. |
|
|
|
||
|
|
Включает обработку синтаксиса циклов. |
|
|
|
Включает обработку синтаксиса условных операторов. |
|
|
|
Включает обработку синтаксиса переменных. |
|
Секция search
Чтобы добавить поиск в документацию, явно пропишите секцию search в файле .yfm.
Diplodoc поддерживает в режиме статической сборки документации три типа интеграции поиска:
- локальный поиск на клиенте (на базе Lunr.js);
- облачный поиск на базе платформы Algolia;
- внешний HTTP-поиск.
По умолчанию поиск отключен, для его появления настройте секцию search.
Общие параметры
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
При значении true страницы, скрытые параметром Явное значение noIndex у страницы или раздела сильнее политики: Параметр работает и при отключённом поиске, и при сборке в |
|
|
|
|
Выбор поисковой системы.
|
— (поиск не подключен) |
Внешний HTTP-поиск (provider: external)
search:
provider: external
endpoint: /api/docs/search
options:
version: v1
endpoint обязателен для включенного внешнего поиска. Поддерживаются HTTP(S)-адрес, путь от корня домена и путь относительно корня документации. options содержит дополнительные публичные query-параметры со строковыми, числовыми или логическими значениями. Настройки попадают в собранные страницы; учетные данные поискового движка должны оставаться на вашем сервере.
Эквивалентные CLI-параметры: --search-provider external --search-endpoint /api/docs/search --search-options '{"version":"v1"}'. Значения CLI имеют приоритет над соответствующими значениями .yfm. Чтобы отключить поиск для сборки, передайте --no-search.
Поля запросов и ответов описаны в HTTP-контракте. Сборщик не создает и не загружает внешний индекс.
Параметры для локального поиска (provider: local)
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Глубина расширения совпадений:
|
|
|
|
Режим ранжирования результатов:
|
|
Пример настройки локального поиска
search:
provider: local
tolerance: 2
confidence: phrased
Параметры для поиска через Algolia (provider: algolia)
|
Название |
Описание |
Тип и значение по умолчанию |
|---|---|---|
|
|
Algolia App ID. |
— |
|
|
Секретный Admin API Key для индексации. |
— |
|
|
Имя индекса в Algolia. |
|
|
|
Если |
|
|
|
Search API Key. |
|
|
|
Путь к js-API поиска на клиенте. |
|
|
|
— |
|
|
|
— |
Пример настройки поиска через Algolia
search:
provider: algolia
appId: <ВАШ_APP_ID>
indexName: docs
index: true
searchApiKey: <ВАШ_SEARCH_API_KEY>
indexSettings:
searchableAttributes:
- title
- content
- headings
querySettings:
hitsPerPage: 10
attributesToRetrieve:
- title
- content
- url
Примечание
- Для активации поиска обязательно добавьте секцию
searchи укажитеprovider. - Для больших проектов рекомендуется облачный поиск Algolia.
- Не публикуйте
apiKeyот Algolia в публичных репозиториях или продакшн-конфигурациях — используйте переменные среды либо CLI-параметры.
Секция docs-viewer
|
Название |
Описание |
Тип и значение по умолчанию |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Язык по умолчанию для локализации. |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Массив языков, отображаемых в интерфейсе документации. Язык по умолчанию при открытии страницы — первый элемент в массиве. Пример структуры проекта с несколькими языками
Полный список поддерживаемых языков
Важно Языки, не включенные в список, отображаться не будут. Если структура проекта содержит языковые папки, то указывать параметр обязательно, даже если в проекте используется только один язык. |
— |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Настройки логотипа:
Если логотип для темной темы не указан, используется изображение для светлой темы. Для указанных выше параметров можно настроить определенные логотипы для разных языков документации. ПримерыОдин логотип для всех языков:
Отличающиеся логотипы для разных языков:
В этом примере при переходах по ссылкам с указанием языкового каталога будут отображаться Примеры ссылок и отображаемых логотипов:
|
— — |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Глобальный запрет на индексирование всей документации внешними роботами.
Рекомендуется использовать до публичных запусков, чтобы документ не отображался в поисковиках. Настройки |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Формирует URL-адрес проекта. Требования:
Важно Есть три зарезервированных имени, которые нельзя указывать в качестве значения
|
— |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Выбор темы оформления: светлая или темная. По умолчанию доступны обе. Можно отключить одну из них, указав используемую по умолчанию, например:
Важно Параметр поддерживается только в серверной версии. |
|