YFM project settings

Parameter

Description

Type and default value

allowCustomResources

Allow loading custom resources into statically generated pages.

boolean

false

allowHtml

Allow using HTML elements in markup.

boolean

false

applyPresets

Whether to apply variable presets.
For more details about presets, see.

boolean

false

authors

Enable displaying the article author.

Example:

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

Parameters:

• enabled — boolean — enable displaying the article author,
• ignore — string[] — ignore authors by patterns listed in the array.

The value authors: true is equivalent to authors: enabled: true.

Works when the vcs parameter is enabled.

boolean | object

false

breaks

Wrap lines at the carriage return character.

boolean

true

contributors

Enable displaying contributors in the article.

Example:

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

Parameters:

• enabled — boolean — enable displaying contributors in the article,
• ignore — string[] — ignore contributors by patterns listed in the array.

The value contributors: true is equivalent to contributors: enabled: true.

Works when the vcs parameter is enabled.

boolean | object

false

disableCsp

Disable adding the Content-Security-Policy meta tag to generated HTML pages.

Use this when CSP is managed externally (for example, via server HTTP headers).

boolean

false

extensions

List of Diplodoc extensions used for building the project.

Objects in the list must contain the name parameter with the extension name, as well as operation parameters unique to each extension.

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

Strings in the list can specify extension names in a simplified format:

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

(string\|object)[]

—

langs

An array of languages involved in the build.

—

—

linkify

Convert link-like strings into links.

Examples of strings:

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

boolean

false

lint

Enable the linter file.

boolean

false

llms

Settings for generating llms.txt and llms-full.txt files for the project:

llms:
  enabled: true
  description: описание проекта
  llmsFullMaxSize: 8M
  url: https://example.com/llms.txt

Parameters:

• description – string — a string with the project description, added to the beginning of the llms*.txt files;
• llmsFullMaxSize — number|string — the maximum size of the llms-full.txt file, accepts numbers and strings like 1024, 512K, 8M;
• url – string — a link to the external llms.txt file, which will be written into documentation articles.

object

—

mtimes

Enable displaying the article modification date, which is taken from VCS data.

Works when the vcs parameter is enabled.

Also, the modification date is automatically added to the page metadata last-modified and article:modified_time.

boolean

false

outputFormat

The format of the final build files: html or md.

string

html

removeHiddenTocItems

Remove from the build all files marked in toc.yaml with the attribute hidden: true.

boolean

false

sanitizeHtml

Enables cleaning HTML markup from potentially dangerous elements in .md files using an HTML sanitizer. Defines allowed and forbidden tags, attributes, styles, and other elements when cleaning HTML content.

boolean

true

singlePage

Build a single-page build. A file single-page.html will be created, which will combine the contents of all project files.

The page will be available at

<documentation_root>/
single-page

boolean

false

staticContent

Build the article's HTML content as part of the layout. By default, it is in a JS object and is inserted into the page during rendering in the browser.

boolean

false

strict

Strict build mode, all YFM warnings are displayed as errors.

You can find the full list of YFM rules here.

boolean

false

supportGithubAnchors

Generate additional anchors compatible with GitHub.

boolean

false

theme

Setting for the base color in the themizer. Overrides base-brand in the main section of the theme.yaml configuration file. Learn more about the themizer.

By default, the base color does not change.

varsPreset

The name of the variables preset to use during the build.

string

—

vcs

Setting for connecting to a VCS system. Enabling it allows using the mtimes, authors, and contributors features.

Requires connecting the built-in extension github-vcs.

boolean | object

false

Name

Description

Type and default value

gtm

Google Tag Manager analytics settings.

Parameters:

• id — string — Google Tag Manager identifier in GTM format,
• mode — string — notification type before sending events base (default) or notification.

object

—

metrika

Connecting Yandex Metrica counters.

Each list item is an object with a required field id (counter number) and an optional field params for passing counter initialization parameters.

Minimal configuration:

analytics:
  metrika:
    - id: 123456

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

Goals are sent to the connected counters from the documentation interface.

object[]

—

Name

Description

Type and default value

maxAssetSize

Maximum allowed asset size in the project. If exceeded, the build will fail with an error.

Accepts numbers and strings: 1024, 512K, 8M.

If you specify 0, asset size checking will not be performed.

number | string

64M

maxHtmlSize

Maximum allowed size of the article's HTML content after the build. If exceeded, the build will fail with an error.

Accepts numbers and strings: 1024, 512K, 8M.

Maximum value — 96M.

number | string

42M

maxInlineSvgSize

Maximum allowed size of an SVG image at which it is inlined into the article content automatically. If the size is exceeded, the SVG image is inserted via the <img> tag.

Accepts numbers and strings: 1024, 512K, 2M.

If you specify 0, SVG images will not be inlined during the build.

Maximum value — 16M.

number | string

2M

maxOpenapiIncludeSize

Maximum allowed size of the JSON schema in the table of contents text of the built OpenAPI specification. If the size is exceeded, the JSON schema is not added to the page directly, but is inserted as a download link (link mode).

Accepts numbers and strings like: 1024, 512K, 2M.

If you specify 0, the inline JSON schema insertion mode is always replaced with link.

number | string

100K

multilineTermDefinitions

Whether tooltips can contain content with multiple line breaks:

• true — tooltips can contain content with multiple line breaks.

• false — tooltips can contain only single line breaks, and all term definitions must be placed at the end of the file (if this condition is violated, the build will fail with an YFM009 error).

boolean

true

Name

Description

Type and default value

favicon-src

Icon in the browser tab.
You can use any image link that meets standard favicon requirements.

string

—

toc

Hides the table of contents (ToC). If not specified, the ToC is considered enabled.

boolean

true

toc-header

Hides the header in the ToC. If not specified, the header is considered enabled.

boolean

true

feedback

Hides the feedback at the end of the page. If not specified, feedback is enabled.

boolean

true

search

Hides search. If not specified, search is considered enabled.

boolean

true

Name

Description

Type and default value

enabled

Enable data preprocessing for the @diplodoc/pdf-generator service.

boolean

false

hiddenPolicy

If set to true, pages hidden by the hidden parameter will be removed from the PDF version of the documentation.

If set to false, hidden pages will be displayed in the PDF version of the documentation.

boolean

true

Name

Description

Type and default value

csp

Managing 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

List of JavaScript files attached to all project pages.

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

To connect scripts, the parameter allowCustomResources: true must be set.

string[]

—

style

A list of css files to be connected to all pages of the project.

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

To connect styles, the parameter allowCustomResources: true must be set.

string[]

—

Parameter

Description

Type and default value

enabled

Enables processing of template syntax in the documentation. If not specified, templating is considered enabled.

boolean

true

scopes

scopes.code

Enables processing of conditional operators syntax in code blocks.

boolean

false

scopes.text

Enables processing of conditional operators syntax in document text.

boolean

true

features

features.cicles

Enables processing of loops syntax.

boolean

true

features.conditions

Enables processing of conditional operators syntax.

boolean

true

features.substitutions

Enables processing of variables syntax.

boolean

true

Name

Description

Type and default value

provider

Selection of the search engine.
Options:

• local — local search (Lunr.js);
• algolia — cloud search based on Algolia.

string

— (search not connected)

Name

Description

Type and default value

tolerance

Depth of match expansion:

• 0 — only exact word match;
• 1 — prefix match (word*);
• 2 — match by any substring of the word (*word*).

number

2

confidense

Result ranking mode:

• phrased — results are ranked higher by the length of the found phrase;
• sparsed — results are ranked higher by the number of found words.

string

phrased

Name

Description

Type and default value

appId

Algolia App ID.
Required parameter for cloud search.

string

—

apiKey

Secret Admin API Key for indexing.
It is recommended to pass them via environment variables or CLI.

string

—

indexName

The name of the index in Algolia.

string

docs

index

If true, the index will be automatically uploaded to Algolia after the build.
If false, only a local index is created.

boolean

false

searchApiKey

Search API Key.
Client-side key for search on the frontend. Without it, cloud search does not work on the client.

string

search-api-key

api

Path to the client-side search JS API.

string

_search/api.js

indexSettings

Algolia index settings.

object

—

querySettings

Algolia search parameter settings.

object

—

Name

Description

Type and default value

lang

Default language for localization.
For the following languages, content will be displayed in RTL (right-to-left) format.

string

ru

langs

Array of languages displayed in the documentation interface. The default language when opening a page is the first element in the array.

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

string[]

—

logo-options

Logo settings:

• src — link to the image for the light theme;

• src-dark — link to the image for the dark theme;

• src-mobile — link to the image for the light theme on mobile;

• src-mobile-dark — link to the image for the dark theme on mobile;

• src-preview — logo for the link preview when sharing on external resources, uses the standard OpenGraph;

• url — link to which the user is redirected when clicking the logo. You can set a link template with the {lang} parameter so that it is replaced with the current documentation language when navigating. For example, the link https://diplodoc.com/docs/{lang}/ when navigating from the Russian-language documentation will lead to https://diplodoc.com/docs/ru/;

• title — text that is shown instead of the logo if it is not set.

If the logo for the dark theme is not specified, the image for the light theme is used.

For the parameters listed above, you can configure specific logos for different documentation languages.

src: logo

src:
  ru: logo1
  en: logo2
  default: logo3

—

—

no-index

Prohibition on indexing by external robots.

It is recommended to use it before public launches so that the document is not displayed in search engines.

boolean

false

project-name

Forms the project URL. Requirements:

• lowercase only;
• only Latin letters, digits, hyphen, and underscore;
• maximum length — 63 characters.

string

—

themes

Selecting the design theme: light or dark. Both are available by default. You can disable one of them by specifying the one used by default, for example:

themes: ['dark']

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