Diplodoc

https://github.com/diplodoc-platform/docs
Admin
Docs-as-code platform: YFM (Yandex Flavored Markdown) syntax, the yfm CLI builder (@diplodoc/cli),...
Tokens:135,156
Snippets:1,269
Trust Score:9.2
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Diplodoc uses YFM (Yandex Flavored Markdown): CommonMark plus extensions processed by the yfm builder. Keep base text GFM-compatible and put YFM specifics in explicit blocks.
- Every YFM block must be closed and surrounded by blank lines: {% note %}...{% endnote %}, {% cut %}...{% endcut %}, {% list tabs %}...{% endlist %}, multiline tables #|...|#. An unclosed block is a build error.
- Links to other pages are relative paths with the .md extension and must point to files listed in toc.yaml, otherwise the build fails with YFM003 unreachable-link.
- Every page must be listed in toc.yaml (items with name and href). Files that are not in toc.yaml are not built.
- Use {% note info|tip|warning|alert %} only for genuinely important remarks. A plain quote is a blockquote with >.
- Use GFM tables for simple data. For block content or merged cells use multiline tables: #| || cell | cell || |#, where > joins with the cell to the left and ^ with the cell above.
- Includes: {% include [text](path/to/file.md) %} with the path relative to the current file. Variables come from presets.yaml and are written as {{ name }}.
- Image size is set with attributes: ![Alt](_images/pic.png){width=800}. Keep images in a directory prefixed with an underscore, such as _images.
- Do not use raw HTML, footnotes [^1], task lists - [ ], subscript ~x~ or underline ++x++: they are not enabled by default and render as literal text.
- One H1 per file, consecutive heading levels, no emoji (linter rule YFM021).
- Build locally with: npx -p @diplodoc/cli yfm -i <docs dir> -o <output dir>. Add --strict to turn warnings into errors.

================
CODE SNIPPETS
================
### Build documentation with Write API Key (local installation)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/algolia.md

Runs the build with the locally installed Algolia extension using npm start and passes the Write API Key via the --api-key flag.

```bash
npm start -- -i ./docs -o ./docs-out --extensions @diplodoc/algolia-extension --api-key "your-write-key"
```

--------------------------------

### Install markdown-it-katex plugin

Source: https://github.com/diplodoc-platform/docs/blob/master/en/plugins/external.md

Install the external plugin package using npm.

```bash
npm install markdown-it-katex
```

--------------------------------

### Main steps: clone repo, create project, install gh-docs extension

Source: https://github.com/diplodoc-platform/docs/blob/master/en/jam.md

Main steps for the workshop: define a step function, clone the workshop repository, create a GitHub project, and install the gh-docs extension. The comment notes that installing the extension may take some time.

```bash
function step { rm -rf ./**; cp -fr ../steps/step-$1/ .; }

git clone git@github.com:diplodoc-platform/notconf-steps.git steps
# create <docs-example> gh project from scratch
gh repo create
cd docs-example

# install our cli as a gh extension, may take some take
gh extension install diplodoc-platform/gh-docs
```

--------------------------------

### Loop example with users array

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/vars.md

Example of using a loop with an array defined in the variable presets file. Shows the output.

```yaml
default:
  users:
    - Alice
    - Mark
```

```markdown
Prefix {% for user in users %} not_var{{user}} {% endfor %} Postfix
```

```markdown
Prefix

{% for user in users %}

not_var{{user}}

{% endfor %}

Postfix
```

--------------------------------

### Preset Structure Example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/vars-service.md

Example of a root `presets.yaml` and a subdirectory `presets.yaml` showing inheritance and variable override.

```yaml
# Корневой presets.yaml
default:
  version: "1.0.0"
  environment: "production"

# Поддиректория/subfolder/presets.yaml
default:
  subfolder_var: "value"
  # Переопределяет значение из родительского пресета
  version: "2.0.0"
```

--------------------------------

### YAML: Full configuration example with CSP

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/media.md

A more complete configuration example showing the resources.csp settings along with other configuration options like allowHtml and langs.

```yaml
allowHtml: true
langs: ['en','ru']

resources:
  csp:
    - "frame-src":
        - "https://vk.com"
        - "https://login.vk.com"        
        - "https://runtime.strm.yandex.ru"

docs-viewer:
  langs: ['en','ru']
...
```

--------------------------------

### Filter examples

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/vars.md

Examples of using the capitalize and length filters. Shows the output.

```yaml
default:
  user:
    name: alice
  users:
    - Alice
    - Mark
```

```markdown
Hello not_var{{ user.name | capitalize }}!
```

```markdown
not_var{{ users | length }}

not_var{{ user.name | length }} | length
```

--------------------------------

### Enable checkbox plugin in .yfm (connection example)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/plugins/installed.md

Configuration for the .yfm file to enable the checkbox plugin, as shown in the 'Example of enabling' section. This is the same as the previous example but presented separately.

```yaml
extensions:
  - name: mdit-plugins
    plugins:
    - '@diplodoc/transform/lib/plugins/checkbox'
```

--------------------------------

### Install GitHub CLI on macOS, Linux/Unix, or Windows

Source: https://github.com/diplodoc-platform/docs/blob/master/en/jam.md

Install GitHub CLI on macOS, Linux/Unix, or Windows. The macOS command uses Homebrew, the Linux/Unix command adds the GitHub CLI apt repository and installs gh, and the Windows command uses winget with the GitHub.cli package.

```bash
brew install gh
```

```bash
(type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
&& sudo mkdir -p -m 755 /etc/apt/keyrings \
&& wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y
```

```bash
winget install --id GitHub.cli
```

--------------------------------

### Function slice examples

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/vars.md

Examples of using the slice function to extract parts of a string. Shows the output.

```yaml
default:
  user:
    name: Masha
```

```markdown
Hello Pnot_var{{ user.name.slice(1) }}!

Hello Pnot_var{{ user.name.slice(1, 2) }}vel!
```

--------------------------------

### Example file with markers for lines parameter

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/code.md

Example file content used to demonstrate the lines parameter. The markers [A] and [B] are substring markers, not line numbers.

```typescript
const before = 1;
// [A]
console.log('Hello');
// [B]
const after = 2;
```

--------------------------------

### Markup: Example embed from unsupported hosting

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/media.md

Example of embedding a video from a service that is not in the supported list, using a direct link to the video player.

```markdown
@[](https://frontend.vh.yandex.ru/runtime/player/video/vplvic7jsotpobyc7o5b?autoplay=0&branding=0&from=documentation&mute=0&redirect_from=ugc)
```

--------------------------------

### theme.yaml configuration example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/style/theme.md

Example of a theme.yaml file that sets the color palette. Colors can be defined globally or separately for light and dark themes. Parameters in light or dark sections override global values.

```yaml
base-brand: rgb(152 223 37)
link: red

light:
    link: rgb(0 255 170)
    quote: rgb(255 0 255)

dark:
    quote: rgba(0, 208, 255, 1)
    base-background: hsl(30 46% 41%)

```

--------------------------------

### Install git on macOS, Linux/Unix, or Windows

Source: https://github.com/diplodoc-platform/docs/blob/master/en/jam.md

Install git on macOS, Linux/Unix, or Windows. The macOS command uses Homebrew, the Linux/Unix command uses apt-get, and the Windows command uses winget with the Git.Git package.

```bash
brew install git
```

```bash
apt-get install git
```

```bash
winget install --id Git.Git -e --source winget
```

--------------------------------

### Install Diplodoc CLI and Algolia extension globally

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/algolia.md

Installs the Diplodoc CLI and the Algolia extension globally using npm. This is the recommended approach for typical scenarios.

```bash
npm install -g @diplodoc/cli
npm install -g @diplodoc/algolia-extension
```

--------------------------------

### Configuration Example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/vars-service.md

Configures the VarsService at creation time, disabling the loading of `presets.yaml` via the `usePresets` option.

```typescript
const varsService = new VarsService(run, {
    // Отключить загрузку presets.yaml
    usePresets: false
});
```

--------------------------------

### Page constructor block markup example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/page-constructor.md

Example of a filter-block with tags, layout items, and media. Demonstrates how to configure a block with multiple properties such as `centered`, `colSizes`, `indent`, and `items`.

```yaml
::: page-constructor
blocks:
  - type: 'filter-block'
    centered: true
    title:
      text: 'Нам доверяют'
    tags:
      - id: 'one'
        label: 'DoubleСloud'
      - id: 'two'
        label: 'Yandex Support'
      - id: 'three'
        label: 'Yandex Cloud'
      - id: 'four'
        label: 'YDB'
      - id: 'five'
        label: 'CatBoost'
    colSizes:
      all: 12
      xl: 12
      md: 12
      sm: 12
    indent:
      top: s
    items:
      - tags:
          - 'one'
        card:
          type: 'layout-item'
          media:
            image:
              src: 'https://storage.yandexcloud.net/cloud-www-assets/pages/index-diplodoc/diplodoc-tab-1.png'
              disableCompress: true
          border: true
          content:
            links:
              - text: 'Посмотреть документацию'
                url: 'https://double.cloud/docs/en/'
                theme: 'normal'
                arrow: true
                color: #54BA7E
:::
```

--------------------------------

### Run local server with http-server

Source: https://github.com/diplodoc-platform/docs/blob/master/en/quickstart.md

Starts a local web server for the folder with the build result. The documentation will be available at http://localhost:5005.

```bash
npx http-server ./output-folder -p 5005

```

--------------------------------

### resources.style example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Example YAML for the `resources.style` setting, which lists CSS files connected to all project pages. Requires `allowCustomResources: true` to be set.

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

--------------------------------

### Manual anchor example in Markdown

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/base.md

Shows how to set a manual anchor for a heading using {#anchor-example}.

```markdown
## Заголовок h2 {#anchor-example}
```

--------------------------------

### Regular expression redirect example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/redirects.md

Shows a redirect rule using a regular expression to match paths starting with /concepts/referral- and redirect them to /index.

```yaml
- from: /concepts/referral-(.*)
  to: /index
```

--------------------------------

### Project structure example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/guides/single-source/profiling.md

Shows the recommended folder layout for a multi-version project: a common folder with language subfolders (ru/en) containing index.md, presets.yaml, and toc.yaml, plus separate document folders (document_name_1, etc.) each with a .yfm configuration file.

```text
project_name
├── common  # папка с файлами проекта
│   ├── ru # языковая папка
│   │   ├── index.md
│   |   ├── presets.yaml
│   |   └── toc.yaml
|   └── en  # языковая папка
│       ├── index.md
│       ├── presets.yaml
│       └── toc.yaml
├── document_name_1  # Папка собираемого документа, например android, windows или tld-com
│   ├── .yfm
├── document_name_2
│   ├── .yfm
├── document_name_3
|   ├── .yfm
```

--------------------------------

### Example of preset file hierarchy

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/presets.md

Shows a directory structure with two presets.yaml files. When building 'faq.md', variables from file No. 1 (closer to the file) take priority over file No. 2. When building 'quickstart.md', only file No. 2 is used.

```text
input-folder
|-- .yfm
|-- toc.yaml
|-- presets.yaml # файл 2
|-- index.yaml
|-- quickstart.md
|-- pages
    |-- presets.yaml # файл 1
    |-- faq.md
    |-- how-to.md
```

--------------------------------

### Directory structure for linkIndex example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/guides/generic.md

Directory structure used in the linkIndex example. Shows two subdirectories each containing an index.md and additional pages.

```text
gen_docs/
  section-a/
    index.md
    page1.md
    page2.md
  section-b/
    index.md
    page1.md

```

--------------------------------

### Example: Preset Merging and Access

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/vars-service.md

Illustrates directory structure with two presets.yaml files and how variables merge and are accessed via `varsService.for('api/page.md')`.

```typescript
// Структура директорий:
// /docs
//   presets.yaml
//   /api
//     presets.yaml
//     page.md

// /docs/presets.yaml
default:
  version: "1.0.0"
  environment: "production"

// /docs/api/presets.yaml
default:
  api_version: "2.0.0"
  version: "2.0.0" // Переопределяет версию из родительского пресета

// Получение переменных для /docs/api/page.md
const vars = varsService.for('api/page.md');

// Доступ к переменным
console.log(vars.version); // "2.0.0"
console.log(vars.environment); // "production"
console.log(vars.api_version); // "2.0.0"
```

--------------------------------

### Check Node.js installation

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/portable.md

Run this command in a terminal (PowerShell on Windows) to verify Node.js is installed. It should print a version number, e.g., v24.18.0.

```shell
node -v
```

--------------------------------

### resources.script example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Example YAML for the `resources.script` setting, which lists JavaScript files attached to all project pages. Requires `allowCustomResources: true` to be set.

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

--------------------------------

### Install Algolia extension with npm

Source: https://github.com/diplodoc-platform/docs/blob/master/en/extensions/index.md

Use npm to install the @diplodoc/algolia-extension package before connecting it to a project. Loading is required before use; local files can also be used for custom extensions.

```bash
npm install @diplodoc/algolia-extension
```

--------------------------------

### Example yfm-build-stats.json output

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/build.md

Example output of the `yfm-build-stats.json` file generated when running with the `--build-stats` flag or `buildStats: true`. Shows the schema version, CLI and build metadata, counters, and output statistics.

```json
{
  "schemaVersion": 1,
  "cli": { "version": "5.29.0", "node": "v22.22.0", "platform": "darwin", "arch": "arm64" },
  "build": {
    "durationMs": 1474,
    "phasesMs": { "prepare": 1242, "entries": 148, "finalize": 84 },
    "outputFormat": "html",
    "langs": ["ru", "en"],
    "features": ["addAlternateMeta", "allowHtml", "buildStats", "sanitizeHtml"],
    "memoryUsageMb": 256
  },
  "counters": {
    "tocs": 3,
    "entriesPlanned": 133,
    "entriesProcessed": 133,
    "entriesByExtension": { ".md": 122, ".yaml": 11 },
    "entriesByLang": { "ru": 91, "en": 42 },
    "headings": 345,
    "contentBytes": 1693771,
    "graph": { "entries": 130, "sources": 12, "resources": 74, "missed": 0, "edges": 129 },
    "warnings": 3,
    "errors": 1,
    "warningsByCode": { "YFM013": 2, "(uncoded)": 1 },
    "errorsByCode": { "YFM016": 1 }
  },
  "output": {
    "files": 421,
    "totalBytes": 45350699,
    "bytesByExtension": { ".html": 2865454, ".js": 9721257, ".png": 24588860 }
  }
}
```

--------------------------------

### Usage example for markdown-it-katex

Source: https://github.com/diplodoc-platform/docs/blob/master/en/plugins/external.md

Markdown syntax to display a mathematical formula using the plugin.

```markdown
$\sqrt{3x-1}+(1+x)^2$
```

--------------------------------

### Markup: Example VK video embed

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/media.md

A complete example of the markup for embedding a VK video, using the link from the iframe src attribute.

```markdown
@[vk](https://vk.com/video_ext.php?oid=-207738372&id=456239060&hd=2&autoplay=1)
```

--------------------------------

### Get leading page dependencies

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/leading-service.md

Gets the dependencies of the leading page at the given path. Returns a promise with an array of dependencies (never[]).

```typescript
const deps = await leadingService.deps('path/to/leading.yaml');
```

--------------------------------

### extensions parameter example with strings

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Lists extension names in a simplified format, including local and author-scoped extensions.

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

--------------------------------

### Build documentation with Write API Key (global installation)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/algolia.md

Runs the yfm build command with the Algolia extension and passes the Write API Key via the --api-key flag. This is used for a secure build.

```bash
yfm build -i ./docs -o ./docs-out --extensions "$(npm root -g)/@diplodoc/algolia-extension" --api-key "your-write-key"
```

--------------------------------

### Example with multiple Yandex Metrika counters

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Example configuration for `analytics.metrika` with multiple counters, each optionally passing `params` for counter initialization parameters like `clickmap` and `webvisor`.

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

--------------------------------

### presets.yaml example with default, internal, and external presets

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/presets.md

Defines the required 'default' preset and optional 'internal' and 'external' presets. Values from 'default' are applied first, then the selected preset overrides them.

```yaml
default:
    position: Волшебник
internal:
    place: Изумрудный город
external:
    place: Страна Оз
```

--------------------------------

### Install @diplodoc/cli globally

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/index.md

Install the @diplodoc/cli package globally. Run this command before using the CLI commands for project creation, building, single file build, or translation.

```shell
npm i @diplodoc/cli -g
```

--------------------------------

### Example yfm-build-content.json output

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/build.md

Example of the yfm-build-content.json output file. It shows the schemaVersion, contentHashes table with hash and size per source path, and pageAssets mapping pages to their resource dependencies.

```json
{
  "schemaVersion": 1,
  "contentHashes": {
    "ru/foo.md": { "hash": "sha256-...", "size": 1234 },
    "ru/foo/inc.md": { "hash": "sha256-...", "size": 567 },
    "ru/img/pic.png": { "hash": "sha256-...", "size": 8901 }
  },
  "pageAssets": {
    "ru/foo.md": ["ru/img/pic.png"]
  }
}
```

--------------------------------

### Setup method: logger.setup

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/logger-service.md

Configures logger parameters. The 'quiet' option disables informational messages. Returns the current logger instance.

```typescript
logger.setup({quiet: true});
```

--------------------------------

### Paragraph example in Markdown

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/base.md

Shows how to create a paragraph by separating blocks of text with a blank line.

```markdown
Параграф.

Следующий параграф.
```

--------------------------------

### Root .yfm configuration example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Example of the root section of a .yfm configuration file. Enables LLM file generation, sets a project description, limits the llms-full.txt size to 8M, and specifies an external llms.txt URL.

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

```

--------------------------------

### Example redirects.yaml file

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/redirects.md

Complete example of a redirects.yaml file with language-specific sections (ru, en) and a common section. Paths in language sections are relative to language folders, while common paths are relative to the project root.

```yaml
# Секция редиректов для отдельных языков документации
ru:
    - from: /entry1
      to: /folder1/entry1
en:
    - from: /entry2
      to: /folder2/entry2
# Секция common
common:
    - from: /entry3
      to: /folder3/entry3
```

--------------------------------

### Get list of file assets (assets)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/markdown-service.md

Gets the list of file assets for a given path. Returns a promise with an array of asset paths.

```typescript
const assets = await markdownService.assets('path/to/file.md');
```

--------------------------------

### Publish with command-line arguments

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/publish-s3.md

Publishes documentation to S3 using command-line arguments for endpoint, bucket, prefix, region, and access keys. This example shows how to pass all parameters directly, which is useful when you don't want to use a configuration file.

```bash
yfm publish -i docs-html/ \
  --endpoint "https://storage.yandexcloud.net" \
  --bucket "my-docs-bucket" \
  --prefix "docs/v1.0/" \
  --region "eu-central-1" \
  --access-key-id "YCAJE..." \
  --secret-access-key "YCO..."
```

--------------------------------

### Quote example in Markdown

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/base.md

Shows how to display a quote using the '>' markup.

```markdown
> Цитирование
```

--------------------------------

### OpenAPI Specification for API Gateway Proxy

Source: https://github.com/diplodoc-platform/docs/blob/master/en/personal-domain-ya-cloud.md

Example OpenAPI specification for configuring a Yandex Cloud API Gateway to proxy documentation to an external domain. Requires changing the external domain address and the path to which documentation should be proxied. The documentation will be located at example-for-your-domain.net/docs when using this example.

```yaml
openapi: 3.0.0
info:
  title: Proxy Example
  version: 1.0.0
servers:
- url: https://d5dj3947rd2qu5g1lbak.apigw.yandexcloud.net
- url: example-for-your-domain.net
paths:
  /путь/{path+}:
    get:
      x-yc-apigateway-integration:
        headers:
          x-real-host: example-for-your-domain.net
          x-docs-proxy-base: docs
          x-docs-project-name: diplodoc-platform--docs
        http_method: get
        query:
          '*': '*'
        type: http
        url: https://diplodoc-platform--docs.viewer.diplodoc.com/{path}
      parameters:
        - name: path
          in: path
          required: false
          schema:
            type: string

```

--------------------------------

### deps

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/leading-service.md

Gets the dependencies of the leading page.

```APIDOC
## deps

### Description
Gets the dependencies of the leading page.

### Method
deps

### Signature
```typescript
const deps = await leadingService.deps('path/to/leading.yaml');
```

### Parameters
- `path: RelativePath` - Required - Path to the file.

### Returns
- `Promise<never[]>` - Promise with an array of dependencies.

### Example
```typescript
const deps = await leadingService.deps('path/to/leading.yaml');
```
```

--------------------------------

### Heading levels example in Markdown

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/base.md

Shows the syntax for heading levels h1 through h4.

```markdown
# Заголовок h1
## Заголовок h2
### Заголовок h3
#### Заголовок h4
```

--------------------------------

### extensions parameter example with objects

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Lists Diplodoc extensions with the name parameter and extension-specific options.

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

--------------------------------

### Line break example in Markdown

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/base.md

Shows how to break a line by moving the caret to a new line.

```markdown
Строка.
Следующая строка.
```

--------------------------------

### resources.csp example structure

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Example YAML structure for the `resources.csp` setting, which manages Content Security Policy directives. The system does not validate the correctness of the specified values; they are taken from the `.yfm` file and automatically included in the meta tag.

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

--------------------------------

### Example of the .yfm file

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Shows the structure of a .yfm configuration file with root settings, interface settings, and docs-viewer logo options.

```yaml
# Корневая секция параметров
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
```

--------------------------------

### Reference-style link example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/links.md

Shows the two-part reference-style link: a brief description in the text and the URL definition at the end.

```markdown
My favorite search engine is [Yandex][1].

[1]: https://yandex.com/ "The best search engine"
```

--------------------------------

### Standard PC page YAML configuration

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/page-constructor.md

Example of a Page constructor page configuration in YAML format. It defines a 'header-block' with title, description, background image, and buttons. Field descriptions for each block are available in the library documentation.

```yaml
blocks:
  - type: 'header-block'
    width: 's'
    offset: 'default'
    title: 'Diplodoc'
    resetPaddings: true
    verticalOffset: 'l'
    description: 'Платформа для создания технической документации в концепции Docs as Сode с открытым исходным кодом. Простое и удобное решение для развёртывания документации больших и маленьких команд.'
    background:
      image:
        mobile: 'https://storage.yandexcloud.net/diplodoc-www-assets/pages/index-diplodoc/ddos-index-cover-mini.png'
        desktop: '_assets/test-move.png'
      color: '#C6FE4D'
      fullWidth: false
    buttons:
      - text: 'Начать'
        theme: 'dark'
        size: 'promo'
        url: '/quickstart'
      - text: 'GitHub'
        theme: 'outlined'
        size: 'promo'
        url: 'https://github.com/diplodoc-platform'
```

--------------------------------

### Simple dropdown list configuration

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/navigation.md

Example of a simple dropdown list with two links. The dropdown item type is used at the first level of the top menu.

```yaml
- type: dropdown
  text: 'Dropdown'
  items:
    - type: link
      text: 'Link 1'
      url: 'https://diplodoc.com'
    - type: link
      text: 'Link 2'
      url: 'https://diplodoc.com/docs/'
```

--------------------------------

### init

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/leading-service.md

Initializes the service by loading plugins.

```APIDOC
## init

### Description
Initializes the service by loading plugins.

### Method
init

### Signature
```typescript
await leadingService.init();
```

### Parameters
None

### Returns
- `Promise<void>` - A promise that resolves when initialization is complete.

### Example
```typescript
await leadingService.init();
```
```

--------------------------------

### tags metadata example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/meta.md

Lists page tags. After the build, tags are displayed below the article and added to the HTML as separate <meta property="article:tag" content="..."> elements. Tags are converted to lowercase, surrounding whitespace removed, duplicates merged, and each tag can contain up to 32 characters. Tags starting with _ are technical and not displayed or used in search.

```yaml
---
title: Working with tables
tags:
  - Markdown
  - Tables
---
```

--------------------------------

### Comment example in Markdown

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/base.md

Shows how to add a comment that is not displayed in the built file. Requires a blank line before the comment.

```markdown
[//]: # (Комментарий)
```

--------------------------------

### Initialize a project with yfm init --skip-interactive

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/init.md

Use this command to create a documentation project without interactive prompts. It sets the output directory to ./output-folder, names the project example, and enables Russian and English languages. The --skip-interactive flag triggers manual mode, and the --force flag can overwrite existing files.

```shell script
# example of a call without interactive mode
yfm init --skip-interactive -o ./output-folder --name example --langs ru,en
```

--------------------------------

### Nested quote example in Markdown

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/base.md

Shows how to create a nested quote using '>>'.

```markdown
> Цитирование
>> Вложенное цитирование
```

--------------------------------

### Service API - init Method

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/vars-service.md

Initializes the service by loading all `presets.yaml` files from the `input` directory.

```typescript
// Инициализация сервиса
await varsService.init();
```

--------------------------------

### Get file metadata (meta)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/markdown-service.md

Gets file metadata for a given path. Returns a promise with metadata.

```typescript
const meta = await markdownService.meta('path/to/file.md');
```

--------------------------------

### Substitutions and conditional operators in landing page

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/leading-page.md

Shows how to use substitutions and conditional operators in the title and description of the document and links. The example uses not_var{{ }} for substitutions and {% if %} for conditional operators.

```yaml
title: "not_var{{ title }}"
description: "{% if version == 10 %}not_var{{ description_legacy }}{% else %}not_var{{ description }}{% endif %}"
meta:
  title: "not_var{{ meta_title }}"
links:
- title: "not_var{{ link_title }}"
  description: "not_var{{ link_description }}"
  href: path/to/conditional/file.md

```

--------------------------------

### Get dictionary of headings and anchors (titles)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/markdown-service.md

Gets a dictionary of headings and their anchors for a given path. Returns a promise with a dictionary of headings.

```typescript
const titles = await markdownService.titles('path/to/file.md');
```

--------------------------------

### Get file headings (headings)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/markdown-service.md

Gets information about file headings for a given path. Returns a promise with an array of heading information.

```typescript
const headings = await markdownService.headings('path/to/file.md');
```

--------------------------------

### Get file dependency graph (graph)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/markdown-service.md

Gets the file dependency graph for a given path. Returns a promise with the dependency graph.

```typescript
const graph = await markdownService.graph('path/to/file.md');
```

--------------------------------

### presets.yaml for different platforms

Source: https://github.com/diplodoc-platform/docs/blob/master/en/guides/single-source/profiling.md

Example of a presets.yaml file for different platforms. The default preset is mandatory and contains default variable values; separate presets (ios, android) define platform-specific values.

```yaml
default: # набор значений по умолчанию
  locale: ru
  platform: browser

ios: # набор значений для ios
  platform: ios

android: # набор значений для android
  platform: android
```

--------------------------------

### translate.list file format

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/translate.md

Example content of a list file used with --files or --include. It supports comments and empty lines, resolves paths relative to the file itself, and forbids paths pointing above the file.

```text
# The file supports comments and empty lines

# Paths are resolved relative to the translate.list file itself
./some/path/to/translated/file-1.md
./some/path/to/translated/file-2.md

# Paths must not point above translate.list
# Example of an invalid path:
../some/path/to/translated/file.md

```

--------------------------------

### Accessing TOC Service

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/toc-service.md

Shows how to access the TOC service from the build context and obtain its hooks. Use this in an extension's apply method to start working with the ToC.

```typescript
export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            // Получение сервиса из контекста
            const {toc} = run;
            
            // Получение hooks сервиса
            const tocHooks = getTocHooks(run.toc);
        });
    }
}
```

--------------------------------

### Create interactive task list in markdown

Source: https://github.com/diplodoc-platform/docs/blob/master/en/plugins/installed.md

Markdown syntax for creating an interactive task list after enabling the checkbox plugin. The example uses Russian text.

```markdown
- [x] ~~Написать пресс-релиз~~
- [ ] Обновить веб-сайт  
- [ ] Связаться со СМИ
```

--------------------------------

### contributors parameter example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Enables displaying contributors in the article with ignore patterns. Works when the vcs parameter is enabled.

```yaml
contributors:
  enabled: true
  ignore:
    - robot-*
    - noreply@company.com
```

--------------------------------

### Label item themes configuration

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/navigation.md

Example of configuration with static text blocks (label items). The theme property defines the block style; available themes include normal, info, danger, warning, success, utility, unknown, and clear.

```yaml
- type: label
  theme: normal
  text: normal

- type: label
  theme: info
  text: info

- type: label
  theme: danger
  text: danger

- type: label
  theme: warning
  text: warning

- type: label
  theme: success
  text: success

- type: label
  theme: utility
  text: utility

- type: label
  theme: unknown
  text: unknown

- type: label
  theme: clear
  text: clear
```

--------------------------------

### Accessing the Logger Service and its hooks

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/logger-service.md

Shows how to access the Logger Service from the build context and retrieve its hooks. Use this as the starting point for any extension that needs to interact with logging.

```typescript
export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            // Получение сервиса из контекста
            const {logger} = run;
            
            // Получение хуков сервиса
            const loggerHooks = getLoggerHooks(logger);
        });
    }
}
```

--------------------------------

### Example of a project structure with multiple languages

Source: https://github.com/diplodoc-platform/docs/blob/master/en/settings.md

Shows a typical folder layout for a multi-language documentation project, with language subfolders (ru, en) each containing toc.yaml and index.md.

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

--------------------------------

### Dropdown with multiple columns and sections

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/navigation.md

Example of a dropdown list with groups of links in multiple columns. The dropdown contains two columns, each with a section that groups links under a title.

```yaml
- type: dropdown
  text: 'Dropdown'
  items:
    - type: column
      items:
      - type: section
        title: 'Section 1'
        items:
          - type: link
            text: 'Link 1'
            url: 'https://diplodoc.com'
          - type: link
            text: 'Link 2'
            url: 'https://diplodoc.com/docs/'
      - type: section
        title: 'Section 2'
        items:
          - type: link
            text: 'Link 3'
            url: 'https://diplodoc.com/docs/'
    - type: column
      items:
      - type: section
        title: 'Section 3'
        items:
          - type: link
            text: 'Link 4'
            url: 'https://diplodoc.com/docs/ru/dev/'
          - type: link
            text: 'Link 5'
            url: 'https://diplodoc.com/docs/ru/quickstart/'
          - type: link
            text: 'Link 6'
            url: 'https://diplodoc.com/docs/ru/project/'
```

--------------------------------

### Ignore paths matching pattern with build -i -o --ignore

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/settings.md

Used to skip processing of paths matching the pattern. The first example ignores *.bad.md files; the second ignores the ./build directory.

```bash
build -i ./input -o ./output --ignore *.bad.md
```

```bash
build -i ./ -o ./build --ignore ./build
```

--------------------------------

### Enable soft wrap with wrap keyword

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/code.md

Use the keyword `wrap` in the opening line to enable soft wrap by default in a code block. The example shows the markdown source and the resulting rendered block.

```markdown
``` wrap
Очень длинная строка в блоке кода, которая точно не поместится в длину, если её искусственно не свернуть
```
```

--------------------------------

### Get leading page assets

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/leading-service.md

Gets the list of assets of the leading page at the given path. Returns a promise with an array of asset paths (NormalizedPath[]).

```typescript
const assets = await leadingService.assets('path/to/leading.yaml');
```

--------------------------------

### Build documentation with yfm build --pdf

Source: https://github.com/diplodoc-platform/docs/blob/master/en/guides/generate-pdf.md

Builds the documentation project with PDF preparation. The `-i .` flag specifies the source folder, `-o ./docs-output` specifies the output folder, and `--pdf` enables data preparation for PDF generation. If PDF support is enabled in `.yfm`, the `--pdf` flag is not required.

```bash
yfm build -i . -o ./docs-output --pdf
```

--------------------------------

### HTML: VK video embed iframe example

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/media.md

An example of an iframe tag used to embed a video from VK. The link from the src attribute is used in the markup.

```html
<iframe src="https://vk.com/video_ext.php?oid=-207738372&id=456239060&hd=2&autoplay=1" width="853" height="480" allow="autoplay; encrypted-media; fullscreen; picture-in-picture; screen-wake-lock;" frameborder="0" allowfullscreen></iframe>
```

--------------------------------

### yfm build command with --vars-preset flag

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/presets.md

Builds documentation with a specified preset. The build must be run separately for each preset. If no presets are used, the flag is not needed and the 'default' preset is used. Output files are in .html format and will be overwritten if the same directory is used.

```bash
yfm build -i ./<document root directory> -o ./<directory with the build output> --vars-preset "<preset name>"
```

--------------------------------

### Use service APIs for TOC, Leading, and Markdown

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services.md

Use the service APIs directly on the `run` object: TOC service (`dir`, `data`, `entries`), Leading service (`has`, `get`), and Markdown service (`read`, `save`). These methods provide build-context data, caching, and format support.

```typescript
export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            // TOC Service API
            const tocPath = run.toc.dir(entry);      // Получение директории TOC
            const tocData = run.toc.data(entry);     // Получение данных TOC
            const entries = run.toc.entries;         // Список всех entry в TOC
            
            // Leading Service API
            const hasLeading = run.leading.has(path);    // Проверка наличия leading-страницы
            const leadingData = run.leading.get(path);   // Получение данных leading-страницы
            
            // Markdown Service API
            const content = run.markdown.read(path);     // Чтение markdown-файла
            await run.markdown.save(path, content);      // Сохранение markdown-файла
        });
    }
}
```

--------------------------------

### Build project with --watch flag

Source: https://github.com/diplodoc-platform/docs/blob/master/en/quickstart.md

Builds the project in watch mode so changes are immediately reflected in the local build. Use this flag to enable live updates.

```bash
yfm build -i ./doc-folder -o ./output-folder --watch

```

--------------------------------

### Check portable CLI version on Windows and macOS/Linux

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/portable.md

Run the built portable CLI to check its version. On Windows use dist\yfm.exe --version; on macOS and Linux use ./dist/yfm --version. The output should be the CLI version, for example 5.55.3.

```shell
dist\yfm.exe --version
```

```shell
./dist/yfm --version
```

--------------------------------

### Configure CSP frame-src in .yfm

Source: https://github.com/diplodoc-platform/docs/blob/master/en/guides/csp.md

Configure CSP policies in the .yfm file to manage allowed sources for resources. This example allows loading frames only from https://test.site; add your own rules and sources as needed.

```yaml
resources:
  csp:
    - "frame-src":
        - "https://test.site"
```

--------------------------------

### Enable line numbers with showLineNumbers

Source: https://github.com/diplodoc-platform/docs/blob/master/en/syntax/code.md

Use the keyword `showLineNumbers` in the opening line to enable line numbers in a code block. The example shows the markdown source and the resulting rendered block.

```markdown
```sql showLineNumbers
  price = '2000'
  size = '24'  
  color = 'primary'
  variant = 'detailed' 
```
```

--------------------------------

### init

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/markdown-service.md

Initializes the service, computing the final set of analyzers and plugins for file processing.

```APIDOC
## init

### Description
Initializes the service. Computes the final set of analyzers and plugins for file processing.

### Method
init

### Signature
```typescript
await markdownService.init();
```

### Parameters
None

### Returns
- `Promise<void>` - promise that resolves when initialization is complete

### Example
```typescript
await markdownService.init();
```
```

--------------------------------

### toc.yaml and folder2/toc.yaml for cross-referencing

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/toc-multiple.md

Two YAML table-of-contents files from the example. The root toc.yaml links to the subsection article, and folder2/toc.yaml links back to the root article. Use these to create cross-references between multiple tables of contents.

```yaml
items:
  - name: Article 1
    href: article1.md
  - name: Article 2
    href: article2.md
  - name: Article 3
    href: folder1/article3.md
  - name: Article 4
    href: folder2/article4.md # ссылка на подраздел
```

```yaml
items:
  - name: Article 4
    href: article4.md
  - name: Article 5
    href: article5.md
  - name: Article 6
    href: folder3/article6.md
  - name: Back to Article 1
    href: ../article1.md # ссылка в корневое оглавление
```

--------------------------------

### Initialize leading service

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/leading-service.md

Initializes the service by loading plugins. Call this before using other methods.

```typescript
await leadingService.init();
```

--------------------------------

### Get service hooks with getHooks

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services.md

Get service hooks using the corresponding `getHooks` functions from `@diplodoc/cli/lib`. Pass the service instance (e.g., `run.toc`) to the matching hook getter.

```typescript
import {getHooks as getBaseHooks} from '@diplodoc/cli/lib/program';
import {getHooks as getTocHooks} from '@diplodoc/cli/lib/toc';
import {getHooks as getMarkdownHooks} from '@diplodoc/cli/lib/markdown';
import {getHooks as getLeadingHooks} from '@diplodoc/cli/lib/leading';

export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            // Получение хуков сервисов
            const tocHooks = getTocHooks(run.toc);
            const markdownHooks = getMarkdownHooks(run.markdown);
            const leadingHooks = getLeadingHooks(run.leading);
        });
    }
}
```

--------------------------------

### Build YFM executable on Windows (PowerShell)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/tools/docs/portable.md

Builds the portable YFM executable on Windows. Creates the yfm-exe folder, writes package.json with the required internal CLI file list, installs @diplodoc/cli and @yao-pkg/pkg, then packages with pkg targeting node24-win-x64. The resulting file is yfm-exe/dist/yfm.exe.

```powershell
mkdir yfm-exe
cd yfm-exe
@'
{
  "name": "yfm-portable",
  "version": "1.0.0",
  "bin": "node_modules/@diplodoc/cli/build/index.js",
  "pkg": {
    "scripts": [
      "node_modules/@diplodoc/cli/build/**/*.js",
      "node_modules/@diplodoc/cli/lib/**/*.js",
      "node_modules/@diplodoc/client/build/server/**/*.js"
    ],
    "assets": [
      "node_modules/@diplodoc/cli/assets/**/*",
      "node_modules/@diplodoc/cli/build/manifest.json",
      "node_modules/@diplodoc/cli/package.json",
      "node_modules/highlight.js/styles/**/*"
    ]
  }
}
'@ | Set-Content -Encoding Ascii package.json
npm install @diplodoc/cli @yao-pkg/pkg
npx pkg --compress GZip --public -t node24-win-x64 -o dist/yfm.exe package.json
```

--------------------------------

### Initialize the markdown service (init)

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/markdown-service.md

Initializes the service and computes the final set of analyzers and plugins for file processing. Call this before using other methods.

```typescript
await markdownService.init();
```

--------------------------------

### interface metadata example disabling table of contents

Source: https://github.com/diplodoc-platform/docs/blob/master/en/project/meta.md

Overrides the interface settings from the same-named section of .yfm for the current page. This example disables the table of contents on the page.

```yaml
---
interface:
  toc: false
---
```

--------------------------------

### Initializing the Search Service

Source: https://github.com/diplodoc-platform/docs/blob/master/en/dev/extensions/services/search-service.md

Calls the init method to initialize the service by loading the search provider.

```typescript
await searchService.init();
```
Tokens:
Raw