Настройки YFM-проекта

Параметр

Описание

Тип и значение по умолчанию

allowCustomResources

Разрешить загрузки пользовательских ресурсов в статически сгенерированные страницы.

bool

false

allowHtml

Разрешить использование html-элементов в разметке.

bool

false

applyPresets

Применять ли пресеты переменных.
Подробнее о пресетах.

bool

false

authors

Включить отображение автора статьи. Данные берутся из vcs.

bool или object

false
Параметры объекта:
enabled - bool -
Включить отображение автора статьи.
ignore - string[] -
Игнорировать авторов по паттернам перечисленным в списке.

Пример:

authors:
  enabled: true
  ignore:
    - robot-*
    - noreply@company.com

breaks

Переносить строки по символу перевода каретки.

bool

true

contributors

Включить отображение контрибьюторов в статье. Данные берутся из vcs.

bool или object

false
Параметры объекта:
enabled - bool -
Включить отображение автора статьи.
ignore - string[] -
Игнорировать авторов по паттернам перечисленным в списке.

Пример:

authors:
  enabled: true
  ignore:
    - robot-*
    - noreply@company.com

langs

Массив языков, участвующих в сборке.

—

—

linkify

Преобразовывать ссылкоподобные строки в ссылки.
Пример ссылки: https://diplodoc.com/ru или diplodoc.com/ru.

bool

false

lint

Подключить файл линтера.

bool

false

mtimes

Включить отображение даты изменения статьи. Берется из данных vcs.

bool

false

outputFormat

Формат файлов итоговой сборки.

string (html или md)

html

pdf

При значении pdf: true для документа будет собираться pdf-версия. Чтобы сборка прошла корректно, обязательно должен быть указан параметр singlePage: true. После завершения сборки в левом нижнем углу документа отображается значок собранного PDF-файла, который можно скачать.

bool

false

removeHiddenTocItems

Убрать из оглавления все объекты, отмеченные атрибутом hidden: true.

bool

false

sanitizeHtml

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

bool

true

singlePage

Собирать одностраничную сборку. Будет создан файл single-page.html, который объединит содержимое всех файлов проекта.

Страница будет доступна по адресу

<корень_документации>/
single-page.

bool

false

staticContent

Разрешить использовать статический контент (например, файлов изображений, CSS или JS).

bool

false

strict

Cтрогий режим сборки, все предупреждения YFM отображаются как ошибки.

bool

false

supportGithubAnchors

Генерировать дополнительные якоря, совместимые с GitHub.

bool

false

varsPreset

Имя пресета переменных, который необходимо использовать при сборке.

string

—

vcs

Настройка подключения к vcs ситеме. Если выключена, то не работают фичи authors и contributors.

boolean или object

undefined

analytics

Конфигурация для модуля аналитки.

Object

undefined

resources

Список разрешенных ресурсов.

Object

undefined

template

Конфигурация синтаксиса шаблонизации.

Object

undefined

Параметр

Описание

Тип и значение по умолчанию

enabled

Включает обработку синтаксиса шаблонов в документации. Если не указан, шаблонизация считается включенной.

bool

true

scopes

scopes.code

Включает обработку синтаксиса условных операторов в блоках кода.

bool

false

scopes.text

Включает обработку синтаксиса условных операторов в тексте документа.

bool

true

features

features.cicles

Включает обработку синтаксиса циклов.

bool

true

features.conditions

Включает обработку синтаксиса условных операторов.

bool

true

features.substitutions

Включает обработку синтаксиса переменных.

bool

true

Название

Описание

Тип и значение по умолчанию

gtm

Настройки аналитики Google Tag Manager.

Object

undefined

gtm.id

Идентификатор Google Tag Manager в формате GTM.

string

undefined

gtm.mode

Тип уведомления перед отправкой событий base или notification.

string

base

Название

Описание

Тип и значение по умолчанию

favicon-src

Иконка во вкладке браузера.
Можно использовать любую ссылку на изображение, подходящее под стандартные требования к фавиконкам.

string

—

toc

Скрывает оглавление (Table of contents, ToC). Если не указан, ToC считается включенным.

bool

true

toc-header

Скрывает заголовок в ToC. Если не указан, заголовок считается включенным.

bool

true

search

Скрывает поиск. Если не указан, поиск считается включенным.

bool

true

Название

Описание

Тип и значение по умолчанию

script

Добавление пользовательских скриптов на страницу.

—

—

style

Добавление пользовательских стилей на страницу.

—

—

csp

Управление Content Security Policy (CSP).

csp:
	- "script-src":
    	- "self"
        - "domain1.com"
        - "domain2.com"
        "*.domain3.com"
    - "style-src":
    	- "self"
    ...
    ...
    ...
    

<meta http-equiv="content-security-policy" content="script-src 'self' domain1.com domain2.com *.domain3.com; style-src 'self' ... ... ...">

object

—

Название

Описание

Тип и значение по умолчанию

favicon-src

Иконка во вкладке браузера.
Можно использовать любую ссылку на изображение, подходящее под стандартные требования к фавиконкам.

string

—

lang

Язык по умолчанию для локализации.
Для следующих языков контент будет отображаться в формате RTL (right-to-left).

string

ru

langs

Массив языков, отображаемых в интерфейсе документации. Язык по умолчанию при открытии страницы — первый элемент в массиве.

input-folder
|-- .yfm
|-- ru
    |-- toc.yaml
    |-- index.md
|-- en
    |-- toc.yaml
    |-- index.md

string[]

—

logo-options

Настройки логотипа:

• src — ссылка на изображение для светлой темы;

• src-dark — ссылка на изображение для темной темы;

• src-mobile — ссылка на изображение для светлой темы на мобильных;

• src-mobile-dark — ссылка на изображение для темной темы на мобильных;

• src-preview — логотип для превью ссылки при шеринге на внешних ресурсах, применяется стандарт OpenGraph;

• url — ссылка, на которую перенаправляет при нажатии на логотип. Можно задать шаблон ссылки с параметром {lang}, чтобы он заменился на текущий язык документации при переходе. Например, ссылка https://diplodoc.com/docs/{lang}/ при переходе из документации на русском языке будет вести на https://diplodoc.com/docs/ru/;

• title — текст, который показывается вместо логотипа, если он не задан.

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

Для указанных выше параметров можно настроить определенные логотипы для разных языков документации.

src: logo

src:
  ru: logo1
  en: logo2
  default: logo3

—

—

metrika

Номер счетчика Яндекс Метрики.

Можно подключить несколько счетчиков:

docs-viewer:
  metrika: [21930706, 96924079]

string | string[]

undefined

no-index

Запрет на индексирование внешними роботами.

Рекомендуется использовать до публичных запусков, чтобы документ не отображался в поисковиках.

bool

false

project-name

Формирует URL-адрес проекта. Требования:

• только нижний регистр;
• только латиница, цифры, дефис и нижнее подчеркивание;
• максимальная длина — 63 символа.

string

—

themes

Выбор темы оформления: светлая или темная. По умолчанию доступны обе. Можно отключить одну из них, указав используемую по умолчанию, например:

themes: ['light']

string

light

Название

Описание

Тип и значение по умолчанию

provider

Выбор поисковой системы.
Варианты:

• local — локальный поиск (Lunr.js);
• algolia — облачный поиск на базе Algolia.

string

— (поиск не подключен)

Название

Описание

Тип и значение по умолчанию

tolerance

Глубина расширения совпадений:

• 0 — только полное совпадение слова;
• 1 — совпадение по префиксу (word*);
• 2 — совпадение по любой подстроке слова (*word*).

number

2

confidense

Режим ранжирования результатов:

• phrased — выше ранжируются результаты по длине найденной фразы;
• sparsed — выше ранжируются результаты по количеству найденных слов.

string

phrased

Название

Описание

Тип и значение по умолчанию

appId

Algolia App ID.
Обязательный параметр для облачного поиска.

string

—

apiKey

Секретный Admin API Key для индексации.
Рекомендуется передавать через переменные среды или CLI.

string

—

indexName

Имя индекса в Algolia.

string

docs

index

Если true, индекс будет автоматически загружаться в Algolia после сборки.
Если false, только создается локальный индекс.

bool

false

searchApiKey

Search API Key.
Клиентский ключ для поиска на фронте. Без него облачный поиск не работает на клиенте.

string

search-api-key

api

Путь к js-API поиска на клиенте.

string

_search/api.js

indexSettings

Настройки индекса Algolia.

object

—

querySettings

Настройки параметров поиска Algolia.

object

—