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

Параметр

Описание

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

allowCustomResources

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

boolean

false

allowHtml

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

boolean

false

applyPresets

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

boolean

false

authors

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

Пример:

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

Параметры:

• enabled — boolean — включить отображение автора статьи,
• ignore — string[] — игнорировать авторов по паттернам, перечисленным в списке.

Значение authors: true аналогично authors: enabled: true.

Работает при включенном параметре vcs.

boolean | object

false

breaks

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

boolean

true

contributors

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

Пример:

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

Параметры:

• enabled — boolean — включить отображение контрибьюторов в статье,
• ignore — string[] — игнорировать контрибьюторов по паттернам, перечисленным в списке.

Значение contributors: true аналогично contributors: enabled: true.

Работает при включенном параметре vcs.

boolean | object

false

disableCsp

Отключить добавление мета-тега Content-Security-Policy в сгенерированные HTML-страницы.

Используйте, когда CSP управляется внешним образом (например, через HTTP-заголовки сервера).

boolean

false

extensions

Список расширений Diplodoc, используемых для сборки проекта.

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

extensions:
  - name: my-extension
    option1: true
    option2: true
    ...

Строками в списке можно в упрощенном формате задавать названия расширений:

extensions:
  - algolia
  - some-author/my-extension
  - /my-local-extension

(string\|object)[]

—

langs

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

—

—

linkify

Преобразовывать ссылкоподобные строки в ссылки.

Примеры строк:

• https://diplodoc.com/ru
• diplodoc.com/ru

boolean

false

lint

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

boolean

false

llms

Настройки генерации файлов llms.txt и llms-full.txt для проекта:

llms:
  enabled: true
  description: описание проекта

Значение опционального поля description добавляется в начало файлов llms*.txt.

object

—

mtimes

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

Работает при включенном параметре vcs.

Также, дата изменения автоматически добавляется в метаданные страницы last-modified и article:modified_time.

boolean

false

outputFormat

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

string

html

removeHiddenTocItems

Убрать из сборки все файлы, отмеченные в toc.yaml атрибутом hidden: true.

boolean

false

sanitizeHtml

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

boolean

true

singlePage

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

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

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

boolean

false

staticContent

Собирать html-контент статьи как часть вёрстки. По умолчанию, он находится в js-объекте и вставляется в страницу на этапе отрисовки в браузере.

boolean

false

strict

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

С полным списком правил YFM можно ознакомиться здесь.

boolean

false

supportGithubAnchors

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

boolean

false

theme

Настройка для базового цвета в темизаторе. Переопределяет base-brand в основной секции конфигурационного файла theme.yaml. Подробнее о темизаторе.

По умолчанию базовый цвет не меняется.

varsPreset

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

string

—

vcs

Настройка подключения к vcs системе. Её включение позволяет использовать функциональности mtimes, authors и contributors.

Требует подключения встроенного расширения github-vcs.

boolean | object

false

Название

Описание

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

gtm

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

Параметры:

• id — string — идентификатор Google Tag Manager в формате GTM,
• mode — string — тип уведомления перед отправкой событий base (по умолчанию) или notification.

object

—

metrika

Подключение счётчиков Яндекс Метрики.

Каждый элемент списка — объект с обязательным полем id (номер счётчика) и опциональным полем params для передачи параметров инициализации счётчика.

Минимальная конфигурация:

analytics:
  metrika:
    - id: 123456

analytics:
  metrika:
    - id: 123456
      params:
        clickmap: true
    - id: 456789
      params:
        clickmap: true
        webvisor: true

В подключенные счётчики из интерфейса документации отправляются цели.

object[]

—

Название

Описание

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

maxAssetSize

Максимально допустимый размер ассета в проекте. В случае превышения сборка завершится с ошибкой.

Принимает числа и строки: 1024, 512K, 8M.

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

number | string

64M

maxHtmlSize

Максимально допустимый размер html-контента статьи после сборки. В случае превышения сборка завершится с ошибкой.

Принимает числа и строки: 1024, 512K, 8M.

Максимальное значение — 96M.

number | string

42M

maxInlineSvgSize

Максимально допустимый размер svg-изображения, при котором оно инлайнится в контент статьи автоматически. В случае превышения размера svg-изображение вставляется через тег <img>.

Принимает числа и строки: 1024, 512K, 2M.

Если указать 0, то svg-изображения не будут инлайниться при сборке.

Максимальное значение — 16M.

number | string

2M

maxOpenapiIncludeSize

Максимально допустимый размер json-схемы в тексте оглавления собранной OpenAPI-спецификации. В случае превышения размера, json-схема не добавляется на страницу напрямую, а вставляется ссылкой для загрузки (режим link).

Принимает числа и строки вида: 1024, 512K, 2M.

Если указать 0, режим вставки json-схем inline всегда заменяется на link.

number | string

100K

multilineTermDefinitions

Могут ли всплывающие подсказки содержать контент с множественными переносами строк:

• true — подсказки могут содержать контент с множественными переносами строк.

• false — подсказки могут содержать только одиночные переносы строк, все определения терминов должны располагаться в конце файла (при нарушении этого условия сборка завершится с ошибкой YFM009).

boolean

true

Название

Описание

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

favicon-src

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

string

—

toc

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

boolean

true

toc-header

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

boolean

true

feedback

Скрывает фидбэк в конце страницы. Если не указан, фидбэк включенным.

boolean

true

search

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

boolean

true

Название

Описание

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

enabled

Включить предобработку данных для сервиса @diplodoc/pdf-generator.

boolean

false

hiddenPolicy

При значении true скрытые параметром hidden страницы будут убраны из pdf-версии документации.

При значении false скрытые страницы будут отображаться в pdf-версии документации.

boolean

true

Название

Описание

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

csp

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

resources:
  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

—

script

Список подключаемых ко всем страницам проекта javascript-файлов.

resources:
  script:
    - _assets/scripts/custom.js
    - _assets/scripts/some.js

Для подключения скриптов должен быть установлен параметр allowCustomResources: true.

string[]

—

style

Список подключаемых ко всем страницам проекта css-файлов.

resources:
  style:
    - _assets/style/custom.css
    - _assets/style/my.css

Для подключения стилей должен быть установлен параметр allowCustomResources: true.

string[]

—

Параметр

Описание

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

enabled

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

boolean

true

scopes

scopes.code

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

boolean

false

scopes.text

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

boolean

true

features

features.cicles

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

boolean

true

features.conditions

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

boolean

true

features.substitutions

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

boolean

true

Название

Описание

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

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, только создается локальный индекс.

boolean

false

searchApiKey

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

string

search-api-key

api

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

string

_search/api.js

indexSettings

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

object

—

querySettings

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

object

—

Название

Описание

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

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

—

—

no-index

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

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

boolean

false

project-name

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

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

string

—

themes

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

themes: ['dark']

string[]
['light', 'dark']