From ced0151e4eb4a0057430f942660bb605458ba646 Mon Sep 17 00:00:00 2001
From: Maxim Karpov <makame@mail.ru>
Date: Wed, 20 Nov 2024 12:56:22 +0300
Subject: [PATCH 1/2] add included docs

---
 en/toc.yaml               |   6 ++-
 en/tools/docs/included.md | 108 ++++++++++++++++++++++++++++++++++++++
 en/tools/docs/settings.md |   1 +
 ru/toc.yaml               |   2 +
 ru/tools/docs/included.md | 108 ++++++++++++++++++++++++++++++++++++++
 ru/tools/docs/settings.md |   1 +
 6 files changed, 224 insertions(+), 2 deletions(-)
 create mode 100644 en/tools/docs/included.md
 create mode 100644 ru/tools/docs/included.md

diff --git a/en/toc.yaml b/en/toc.yaml
index eb67a34..cf87798 100644
--- a/en/toc.yaml
+++ b/en/toc.yaml
@@ -85,10 +85,12 @@ items:
                 href: tools/docs/index.md
               - name: Build
                 href: tools/docs/build.md
-              - name: Translate
-                href: tools/docs/translate.md
               - name: Settings
                 href: tools/docs/settings.md
+              - name: Translate
+                href: tools/docs/translate.md
+              - name: Gluing dependencies
+                href: tools/docs/included.md
               - name: Single-page build
                 href: tools/docs/singlepage.md
               - name: Uploading to S3
diff --git a/en/tools/docs/included.md b/en/tools/docs/included.md
new file mode 100644
index 0000000..337f9b6
--- /dev/null
+++ b/en/tools/docs/included.md
@@ -0,0 +1,108 @@
+# Dependency Merging
+
+## Description
+
+The included: true flag is a configuration parameter that is designed to speed up document processing. It merges all dependent .md files into a single final file, improving performance and simplifying document management.
+
+## Features
+
+- Faster processing: Significantly reduces the time it takes to assemble documents by reducing the number of files to process.
+- Consistency: All related documents are merged into one, making them easier to distribute and read.
+- Optimization: Avoids redundant I/O operations associated with downloading multiple individual files.
+
+## Usage
+
+To enable this feature, add the following line to your project's configuration file:
+
+```yaml
+included: true
+```
+
+Once enabled, the system will automatically merge all .md files that are marked as dependent into one:
+
+1. Project root file: This file typically contains the main content and references to other files that need to be merged.
+2. Dependent files: Files referenced by the root file will be included in the final document.
+
+## Benefits
+
+- Improved performance: Reduces the time it takes to download and process each individual file.
+- Simplified deployment and publishing: A glued together single file is easier to distribute and maintain.
+- Compatibility: Works with most standard Markdown syntaxes and tools, making integration painless.
+
+## Limitations
+
+- File size: With a significant number of dependencies, the resulting file size can become too large for convenient use.
+
+## Example
+
+### Input files
+
+```md
+start main
+
+{% include [Text](included/file-1-deep.md) %}
+
+end main
+```
+
+```md (included/file-1-deep.md)
+start file 1
+
+{% include [Text](file-2-deep.md) %}
+
+end file 1
+```
+
+```md (included/file-2-deep.md)
+start file 2
+
+{% include [Text](file-3.md) %}
+
+end file 2
+```
+
+```md (included/file-3.md)
+start file 3
+
+end file 3
+```
+
+### Результат
+
+```md
+start main
+
+{% include [Text](included/file-1-deep.md) %}
+
+end main
+{% included (included/file-1-deep.md:file-2-deep.md:file-3.md) %}
+start file 3
+
+end file 3
+{% endincluded %}
+{% included (included/file-1-deep.md:file-2-deep.md) %}
+start file 2
+
+{% include [Text](file-3.md) %}
+
+end file 2
+{% endincluded %}
+{% included (included/file-1-deep.md) %}
+start file 1
+
+{% include [Text](file-2-deep.md) %}
+
+end file 1
+{% endincluded %}
+```
+
+```html
+<p>start main</p>
+<p>start file 1</p>
+<p>start file 2</p>
+<p>start file 3</p>
+<p>end file 3</p>
+<p>end file 2</p>
+<p>end file 1</p>
+<p>end main</p>
+```
\ No newline at end of file
diff --git a/en/tools/docs/settings.md b/en/tools/docs/settings.md
index b496fa8..0af1934 100644
--- a/en/tools/docs/settings.md
+++ b/en/tools/docs/settings.md
@@ -25,5 +25,6 @@ The name of the startup key corresponds to the name of the setting.
 | `--lint-disabled`           | Should whether to turn off a linter |
 | `--build-disabled`          | Should whether to turn off a build |
 | `--add-map-file`            | Should add all paths of documentation into file.json. Disabled by default. |
+| `--included`                | Activation of gluing all dependencies of md files into 1 file to speed up display, more details in the section [Gluing dependencies](./included.md) of files. Disabled by default. |
 
 To view the full list of keys, run the `yfm --help` command.
diff --git a/ru/toc.yaml b/ru/toc.yaml
index e22e2b3..570dc3d 100644
--- a/ru/toc.yaml
+++ b/ru/toc.yaml
@@ -130,6 +130,8 @@ items:
                 href: tools/docs/settings.md
               - name: Локализация
                 href: tools/docs/translate.md
+              - name: Склеивание зависимостей
+                href: tools/docs/included.md
               - name: Одностраничная сборка
                 href: tools/docs/singlepage.md
               - name: Выкладка на S3
diff --git a/ru/tools/docs/included.md b/ru/tools/docs/included.md
new file mode 100644
index 0000000..531bb3a
--- /dev/null
+++ b/ru/tools/docs/included.md
@@ -0,0 +1,108 @@
+# Склеивание зависимостей
+
+## Описание
+
+Флаг included: true — это параметр конфигурации, который предназначен для ускорения обработки документов. Он объединяет все зависимые .md файлы в один конечный файл, что позволяет улучшить производительность и упростить управление документами.
+
+## Особенности
+
+- Ускоренная обработка: Значительное уменьшение времени на сборку документов за счет сокращения количества обрабатываемых файлов.
+- Единообразие: Все связанные документы сливаются в один, что облегчает их распространение и чтение.
+- Оптимизация: Позволяет избегать избыточных операций ввода-вывода, связанных с загрузкой множества отдельных файлов.
+
+## Использование
+
+Чтобы активировать данную функцию, добавьте следующую строку в конфигурационный файл вашего проекта:
+
+```yaml
+included: true
+```
+
+После активации, система автоматически объединит все файлы .md, которые отмечены как зависимые, в один:
+
+1. Корневой файл проекта: Этот файл обычно содержит основное содержание и ссылки на другие файлы, которые необходимо объединить.
+2. Файлы-зависимости: Файлы, на которые ссылается корневой файл, будут включены в финальный документ.
+
+## Преимущества
+
+- Улучшенная производительность: Снижается время на загрузку и обработку каждого отдельного файла.
+- Упрощенное развертывание и публикация: Склеенный единый файл проще распространять и поддерживать.
+- Совместимость: Работает с большинством стандартных Markdown синтаксисов и инструментов, что делает интеграцию безболезненной.
+
+## Ограничения
+
+- Объем файла: При значительном количестве зависимостей размер итогового файла может стать слишком большим для удобного использования.
+
+## Пример
+
+### Входные файлы
+
+```md
+start main
+
+{% include [Text](included/file-1-deep.md) %}
+
+end main
+```
+
+```md (included/file-1-deep.md)
+start file 1
+
+{% include [Text](file-2-deep.md) %}
+
+end file 1
+```
+
+```md (included/file-2-deep.md)
+start file 2
+
+{% include [Text](file-3.md) %}
+
+end file 2
+```
+
+```md (included/file-3.md)
+start file 3
+
+end file 3
+```
+
+### Результат
+
+```md
+start main
+
+{% include [Text](included/file-1-deep.md) %}
+
+end main
+{% included (included/file-1-deep.md:file-2-deep.md:file-3.md) %}
+start file 3
+
+end file 3
+{% endincluded %}
+{% included (included/file-1-deep.md:file-2-deep.md) %}
+start file 2
+
+{% include [Text](file-3.md) %}
+
+end file 2
+{% endincluded %}
+{% included (included/file-1-deep.md) %}
+start file 1
+
+{% include [Text](file-2-deep.md) %}
+
+end file 1
+{% endincluded %}
+```
+
+```html
+<p>start main</p>
+<p>start file 1</p>
+<p>start file 2</p>
+<p>start file 3</p>
+<p>end file 3</p>
+<p>end file 2</p>
+<p>end file 1</p>
+<p>end main</p>
+```
\ No newline at end of file
diff --git a/ru/tools/docs/settings.md b/ru/tools/docs/settings.md
index 108f69a..5102d33 100644
--- a/ru/tools/docs/settings.md
+++ b/ru/tools/docs/settings.md
@@ -24,5 +24,6 @@
 `--lint-disabled` | Возможность отключить линтер.
 `--build-disabled` | Возможность отключить cборку.
 `--add-map-file` | Добавлять создание file.json со всеми путями к документации. По умолчанию выключено.
+`--included` | Активация склеивания всех зависимостей md файлов в 1 файл для ускорения отображения, подробнее в разделе [Склеивание зависимостей](./included.md) файлов. По умолчанию выключено.
 
 Чтобы ознакомиться с полным списком ключей, выполните команду `yfm --help`.

From 491191136cafa2ddda40d60077cd8d9abc1de72a Mon Sep 17 00:00:00 2001
From: Maxim Karpov <makame@mail.ru>
Date: Wed, 20 Nov 2024 13:47:57 +0300
Subject: [PATCH 2/2] add included docs

---
 en/tools/docs/included.md | 18 ++++++++++++------
 ru/tools/docs/included.md | 14 ++++++++++----
 2 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/en/tools/docs/included.md b/en/tools/docs/included.md
index 337f9b6..dced524 100644
--- a/en/tools/docs/included.md
+++ b/en/tools/docs/included.md
@@ -2,7 +2,7 @@
 
 ## Description
 
-The included: true flag is a configuration parameter that is designed to speed up document processing. It merges all dependent .md files into a single final file, improving performance and simplifying document management.
+The "included: true" flag is a configuration parameter that is designed to speed up document processing. It merges all dependent .md files into a single final file, improving performance and simplifying document management.
 
 ## Features
 
@@ -35,7 +35,7 @@ Once enabled, the system will automatically merge all .md files that are marked
 
 ## Example
 
-### Input files
+### Input
 
 ```md
 start main
@@ -45,7 +45,9 @@ start main
 end main
 ```
 
-```md (included/file-1-deep.md)
+#### included/file-1-deep.md
+
+```md
 start file 1
 
 {% include [Text](file-2-deep.md) %}
@@ -53,7 +55,9 @@ start file 1
 end file 1
 ```
 
-```md (included/file-2-deep.md)
+#### included/file-2-deep.md
+
+```md
 start file 2
 
 {% include [Text](file-3.md) %}
@@ -61,13 +65,15 @@ start file 2
 end file 2
 ```
 
-```md (included/file-3.md)
+#### included/file-3.md
+
+```md
 start file 3
 
 end file 3
 ```
 
-### Результат
+### Result
 
 ```md
 start main
diff --git a/ru/tools/docs/included.md b/ru/tools/docs/included.md
index 531bb3a..e790a0a 100644
--- a/ru/tools/docs/included.md
+++ b/ru/tools/docs/included.md
@@ -2,7 +2,7 @@
 
 ## Описание
 
-Флаг included: true — это параметр конфигурации, который предназначен для ускорения обработки документов. Он объединяет все зависимые .md файлы в один конечный файл, что позволяет улучшить производительность и упростить управление документами.
+Флаг "included: true" — это параметр конфигурации, который предназначен для ускорения обработки документов. Он объединяет все зависимые .md файлы в один конечный файл, что позволяет улучшить производительность и упростить управление документами.
 
 ## Особенности
 
@@ -45,7 +45,9 @@ start main
 end main
 ```
 
-```md (included/file-1-deep.md)
+#### included/file-1-deep.md
+
+```md
 start file 1
 
 {% include [Text](file-2-deep.md) %}
@@ -53,7 +55,9 @@ start file 1
 end file 1
 ```
 
-```md (included/file-2-deep.md)
+#### included/file-2-deep.md
+
+```md
 start file 2
 
 {% include [Text](file-3.md) %}
@@ -61,7 +65,9 @@ start file 2
 end file 2
 ```
 
-```md (included/file-3.md)
+#### included/file-3.md
+
+```md
 start file 3
 
 end file 3