diff --git a/en/toc.yaml b/en/toc.yaml index eb67a34d..cf877981 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 00000000..dced5241 --- /dev/null +++ b/en/tools/docs/included.md @@ -0,0 +1,114 @@ +# 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 + +```md +start main + +{% include [Text](included/file-1-deep.md) %} + +end main +``` + +#### included/file-1-deep.md + +```md +start file 1 + +{% include [Text](file-2-deep.md) %} + +end file 1 +``` + +#### included/file-2-deep.md + +```md +start file 2 + +{% include [Text](file-3.md) %} + +end file 2 +``` + +#### included/file-3.md + +```md +start file 3 + +end file 3 +``` + +### Result + +```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 +
start main
+start file 1
+start file 2
+start file 3
+end file 3
+end file 2
+end file 1
+end main
+``` \ No newline at end of file diff --git a/en/tools/docs/settings.md b/en/tools/docs/settings.md index b496fa8f..0af19344 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 e22e2b3f..570dc3da 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 00000000..e790a0a5 --- /dev/null +++ b/ru/tools/docs/included.md @@ -0,0 +1,114 @@ +# Склеивание зависимостей + +## Описание + +Флаг "included: true" — это параметр конфигурации, который предназначен для ускорения обработки документов. Он объединяет все зависимые .md файлы в один конечный файл, что позволяет улучшить производительность и упростить управление документами. + +## Особенности + +- Ускоренная обработка: Значительное уменьшение времени на сборку документов за счет сокращения количества обрабатываемых файлов. +- Единообразие: Все связанные документы сливаются в один, что облегчает их распространение и чтение. +- Оптимизация: Позволяет избегать избыточных операций ввода-вывода, связанных с загрузкой множества отдельных файлов. + +## Использование + +Чтобы активировать данную функцию, добавьте следующую строку в конфигурационный файл вашего проекта: + +```yaml +included: true +``` + +После активации, система автоматически объединит все файлы .md, которые отмечены как зависимые, в один: + +1. Корневой файл проекта: Этот файл обычно содержит основное содержание и ссылки на другие файлы, которые необходимо объединить. +2. Файлы-зависимости: Файлы, на которые ссылается корневой файл, будут включены в финальный документ. + +## Преимущества + +- Улучшенная производительность: Снижается время на загрузку и обработку каждого отдельного файла. +- Упрощенное развертывание и публикация: Склеенный единый файл проще распространять и поддерживать. +- Совместимость: Работает с большинством стандартных Markdown синтаксисов и инструментов, что делает интеграцию безболезненной. + +## Ограничения + +- Объем файла: При значительном количестве зависимостей размер итогового файла может стать слишком большим для удобного использования. + +## Пример + +### Входные файлы + +```md +start main + +{% include [Text](included/file-1-deep.md) %} + +end main +``` + +#### included/file-1-deep.md + +```md +start file 1 + +{% include [Text](file-2-deep.md) %} + +end file 1 +``` + +#### included/file-2-deep.md + +```md +start file 2 + +{% include [Text](file-3.md) %} + +end file 2 +``` + +#### included/file-3.md + +```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 +start main
+start file 1
+start file 2
+start file 3
+end file 3
+end file 2
+end file 1
+end main
+``` \ No newline at end of file diff --git a/ru/tools/docs/settings.md b/ru/tools/docs/settings.md index 108f69a3..5102d330 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`.