diff --git a/ru/_images/materials.png b/ru/_images/materials.png index d6aeb99..afad2b4 100644 Binary files a/ru/_images/materials.png and b/ru/_images/materials.png differ diff --git a/ru/_images/resume.png b/ru/_images/resume.png index 22c5be7..ba96730 100644 Binary files a/ru/_images/resume.png and b/ru/_images/resume.png differ diff --git a/ru/_images/sources.png b/ru/_images/sources.png index 4ba38f7..e77b83f 100644 Binary files a/ru/_images/sources.png and b/ru/_images/sources.png differ diff --git a/ru/about.md b/ru/about.md index c94470f..4278f55 100644 --- a/ru/about.md +++ b/ru/about.md @@ -1,21 +1,26 @@ -# Diplodoc - -Diplodoc - это платформа работы с документацией в парадигме Documentation as a Code. - -Вы можете создавать свои документационные проекты в YFM, cо всей структурой, контентом и элементами, необходимыми для качественного предоставления информации пользователям. - -## Достоинства платформы: - -### Простота использования -Работа с документами как с кодом: в привычной среде и с минимальными усилиями по развёртыванию и поддержке. -### Cкорость работы -Быстрая сборка, валидация и выкладка документации любого размера. Полная интеграция в существующие CI/CD-системы для ускорения работы. -### Общепринятый формат Markdown -Простой, понятный и широко распространенный синтаксис с поддержкой базового Markdown. Концентрируйтесь на контенте, а не на том, как доставить его до пользователя. -### Обширная функциональность -Создание документов любой сложности, в том числе генерация из единого источника и работа с переменными. Широкие возможности по кастомизации и отображению гарантируют удовлетворённость конечных пользователей. -### Интеграция с системами автоматической документации -Поддержка широко распространённой OpenAPI-спецификации «из коробки». Обеспечение работы специализированных систем через интерфейс подключаемых внешних документов. -### Поиск -Самый частотный пользовательский сценарий по поиску документов на базе платформы без дополнительных затрат и усилий по поддержке. - +# О Diplodoc + +Добро пожаловать на платформу документирования Diplodoc — решение, созданное для тех, кто стремится эффективно управлять и публиковать документацию с использованием подхода «docs as code». + +Diplodoc предоставляет два варианта использования (оба из которых абсолютно бесплатны): + +{% list tabs %} + +- Серверная версия + + Серверная версия Diplodoc обеспечивает простоту и удобство использования платформы без необходимости организации собственного хостинга. В этом варианте вся обработка и рендеринг контента осуществляется на наших ресурсах. + + Вы просто работаете с Markdown-файлами на Github, и платформа автоматически генерирует из них документацию на на домене [diplodoc.com](https://diplodoc.com/). + + Одним из преимуществ серверной версии является возможность проксирования с вашего собственного домена, что позволяет сохранить брендовый стиль и профессиональный вид документационного портала. + +- Cтатическая документация + + Для пользователей, предпочитающих полный контроль над инфраструктурой, Diplodoc предлагает вариант использования через интерфейс командной строки (CLI). + + В этом сценарии вы можете использовать наш CLI для генерации статических HTML-страниц из вашего контента, написанного в Markdown. + + Этот подход позволяет размещать собранные файлы на любых собственных хостинговых платформах, обеспечивая максимальную гибкость и независимость. Это идеальный вариант для команд, желающих интегрировать процесс создания документации в свои CI/CD пайплайны. + +{% endlist %} + diff --git a/ru/deploy.md b/ru/deploy.md new file mode 100644 index 0000000..1559ddb --- /dev/null +++ b/ru/deploy.md @@ -0,0 +1,7 @@ +# Публикация документации + +Diplodoc поддерживает несколько вариантов размещения документации: + +- [Публикация на Diplodoc.com](how-it-work.md) +- [Размещение на GitHub Pages](github-pages.md) +- [Публикация на локальном сервере](installation.md) \ No newline at end of file diff --git a/ru/features.md b/ru/features.md new file mode 100644 index 0000000..e5df1fd --- /dev/null +++ b/ru/features.md @@ -0,0 +1,33 @@ +# Функциональные возможности + +## Простота использования + +Управляйте документами так же, как исходным кодом: в привычной среде с минимальными усилиями на развертывание и обслуживание. + +## Расширенный Markdown + +Используйте [улучшенный Markdown](syntax/index.md) с необходимыми компонентами для документации, такими как кодовые блоки, изображения, диаграммы и многое другое. + +## Комбинирование ручной и генерируемой документации + +Поддерживается генерация из [OpenAPI-спецификаций](guides/openapi.md), а также автогенерация из Swift и Objective-C. + +## Локализация + +Платформа нативно поддерживает [извлечение текста](tools/docs/translate.md) для различных систем перевода, таких как SmartCAT, Weblate, YaCAT и Яндекс Переводчик. + +## Конструктор страниц + +Платформа нативно поддерживает [Page Constructor](https://github.com/gravity-ui/page-constructor) — тип страниц, позволяющих пользователям создавать страницы-лендинги с каруселями, фонами, плавно анимированными карточками и различными другими блоками. + +## Поддержка Right-to-Left + +Diplodoc предоставляет возможность поддержки режима Right-to-Left (RTL), обеспечивая беспрепятственный доступ и читаемость для таких языков, как арабский и иврит. + +## Встроенная функция поиска + +Наиболее типичный сценарий использования [поиска документов](project/search.md) на платформе, без дополнительных затрат или усилий по поддержке. + +## Визуальные возможности + +Платформа позволяет быстро создавать понятные формулы, красивые диаграммы и разводящие страницы, благодаря наличию [Mermaid](tools/mermaid.md), PlantUML, LaTeX. \ No newline at end of file diff --git a/ru/github-pages.md b/ru/github-pages.md new file mode 100644 index 0000000..f29ce61 --- /dev/null +++ b/ru/github-pages.md @@ -0,0 +1,21 @@ +# Публикация на GitHub Pages + +1. В GitHub в репозитории вашего документа перейдите на вкладку **Settings** и в меню слева выберите **Pages**. + +1. В разделе **Build and deployment** в выпадающем списке выберите **GitHub Actions** и в появившемся блоке **Static HTML** нажмите кнопку **Configure**. Откроется окно редактирования экшна. + +1. В блоке `jobs` после строки `uses: actions/configure-pages@v5` добавьте код + + ```yaml + - name: Build docs + uses: diplodoc-platform/docs-build-action@v3 + with: + src-root: './docs' + build-root: './docs-html' + ``` + +1. Вверху справа нажмите **Commit changes...**, укажите имя коммита в поле **Commit message** и нажмите кнопку **Commit changes**. + +1. Перейдите на вкладку **Actions**. Вверху списка будет ваш последний коммит. + +1. Нажмите на название коммита. После завершения сборки, документ будет размещен на GitHub Pages. Посмотреть его можно по ссылке ниже под надписью **deploy**. \ No newline at end of file diff --git a/ru/guides/generic.md b/ru/guides/generic.md new file mode 100644 index 0000000..0efa7dd --- /dev/null +++ b/ru/guides/generic.md @@ -0,0 +1,37 @@ +# Generic + +Вы можете сгенерировать документацию в markdown-формате любой утилитой и включить её в основную документацию. + +Инклюдер сгенерирует по ней оглавление и включит контент в документацию. + +#### Пример использования + +Проект документации лежит в `doc_root` папке. + +Положим сгенерированный контент в папку `doc_root/docs`. + +Включим этот контент с помощью generic-инклюдера в `doc_root/toc.yaml`. + +Подключим разводящую в `doc_root/index.yaml`. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: + - name: docs + include: + path: docs + includers: + - name: generic + input: docs + mode: link +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: docs + href: docs/ +``` \ No newline at end of file diff --git a/ru/guides/includers.md b/ru/guides/includers.md new file mode 100644 index 0000000..894ba16 --- /dev/null +++ b/ru/guides/includers.md @@ -0,0 +1,57 @@ +# Вставка произвольного контента (Includers) + +Вы можете включить в оглавление произвольный контент через `includers`, но только в случае если `includer` для этого типа контента имплементирован. Список имплементированных инклюдеров можно посмотреть [ниже](#implement-includers). + +Возможные способы указания инклюдеров: + +- массив `includer`-объектов в поле `includers`; + +- `includer`-объект в поле `includer` (_в процессе деприкации в пользу `includers` поля_). + +**Требования к `include`:** + +1. `include` должен иметь поле `path`, куда контент будет включен. + +2. поле `path` должно быть **путем, куда будет включен контент**. + +3. свойство `mode` должно иметь значение `link или пропущенно, `link является дефолтным поведением. + +**Требования к `includers`:** + +`includers` должен быть массивом includer-объектов, которые будут запущенны в указанном порядке. + +**Требования к `includer`:** + +Параметры между includer-объектами разные, но имя `includer` является обязательным параметром. + +`name` указывает имя инклюдера, который запустится. + + +#### Пример использования + +Абстрактный пример использования инклюдеров + +_Уточненный пример смотрите в разделе соответствуещего инклюдера для конкретного примера использования._ + +``` +# toc.yaml +... +items: + - name: + include: + path: + includers: + - name: + : + - name: + - name: + mode: link +... +``` + +## Список имплементированных инклюдеров {#implement-includers} + +- [Generic](generic.md); +- [Open API](openapi.md); +- [Unarchive](unarchive.md); +- [Source Docs](source-docs.md) (_в процессе деприкации в пользу generic инклюдера_). \ No newline at end of file diff --git a/ru/guides/openapi.md b/ru/guides/openapi.md new file mode 100644 index 0000000..9b72926 --- /dev/null +++ b/ru/guides/openapi.md @@ -0,0 +1,193 @@ +# Генерация из OpenAPI-спецификации + +Вы можете сгенерировать документ из [OpenAPI-спецификации](https://www.openapis.org/) и включить её в основной документ. + +{% note warning %} + +Openapi-инклюдер требует разрешение на использование HTML в документации, поэтому внутри конфигурационного файла `.yfm` необходимо указать значение `allowHTML: true`. + +{% endnote %} + +## Требования к OpenAPI-спецификации + +- Версия используемой спецификации не ниже 3.Х. +- Допускается использование только операторов `oneOf` и `allOf`. +- Ограничения на использование базового функционала не накладываются. + +#### Пример использования + +1. Документационный проект лежит в директории `doc_root`. + +2. OpenAPI-спецификацию размещаем по пути `doc_root/openapi.yaml`. + +3. Включаем её в оглавление `doc_root/toc.yaml` с помощью [openapi-инклюдера](includers.md). + +4. Подключаем разводящую в `doc_root/index.yaml`. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: + - name: openapi + include: + path: openapi + includers: + - name: openapi + input: openapi.yaml + mode: link +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: openapi + href: openapi/ +``` + + +### `tags` + +Позволяет менять оглавления тегов. Описания конечных точек, полученные после сборки, раскладываются по тегам. + +#### Синтаксис + +```yaml +tags: + __root__: + name: Новое название оглавления на верхнем уровне + path: hello.md + alias: 'new-url-path' + hidden: false + tag: + name: Название оглавления внутри тега tag + path: custom.md + alias: 'new-tag' + hidden: true +``` + +Параметр `tag` принимает описания тегов: + +* `name` - меняет отображаемое на сайте имя оглавления. + +* `path` - записывает в оглавление любой контент. Путь до файла с новым содержимым указыватеся относительно файла с конфигурацией OpenAPI. + +* `alias` - меняет путь до файла. Все теги на русском языке преобразуются в транслит. С помощью это поля можно указывать произвольное имя файла. Например, есть тег "Регистрация пользователя". Если его не изменить, ссылка на раздел будет выглядеть так `doc.com/registracia_polzovatelya`. Если указать `alias: registration`, ссылка будет иметь вид `doc.com/registration`. + +* `hidden` - скрывает раздел оглавления из навигации. + +Оглавление верхнего уровня можно настроить с момощью тега `__root__`. + +### `leadingPage` + +Позволяет настроить все оглавления за раз. + +#### Синтаксис + +```yaml + leadingPage: + name: Новое имя всех оглавлений + spec: + renderMode: hidden +``` +Теги: + +* `name` - меняет название всех оглавлений. +* `spec.renderMode` - определяет, нужно ли добавлять OpenAPI-спецификацию в оглавление. Если да, необходимо указать значение `renderMode: inline`, в ином случае - `renderMode: hidden`. + +### `sandbox` + +Позволяет отобржать таб с песочницей, через которую можно отправлять запросы. + +#### Синтаксис + +```yaml +sandbox: + tabName: Название таба с песочницей + host: 'https://sandbox.doc.ru' +``` + +## Скрытие полей + +```yaml +x-hidden: true +``` +Чтобы скрыть параметры операции или поля объекта, добавьте в их описание `x-hidden: true`. + +#### Пример использования + +```yaml +- name: example + required: false + schema: + type: string + description: "Пример" + x-hidden: "true" +``` + +## Скрытие описаний + +Существует 3 вида фильтрации: + +* `filter`; +* `nobuild`; +* `noindex`. + +Они имеют общий интерфейс фильтрации: + +```yaml +filter: + endpoint: tags contains "nobuild" != true + tag: name == "noindex" +``` + +Поле `endpoint` позволяет пометить конечную точку определенным свойством (зависит от выбранного режима фильтрации) аналогично тому, как поле `tag` помечает теги. + +### `filter` + +Позволяет указать условие, определяющее нужно ли добавлять конечную точку в сборку. + +#### Синтаксис + +```yaml + filter: + endpoint: tags contains "nobuild" != true +``` + +#### Пример использования + +Необходимо, чтобы незавершенные описания не попали в документацию. Чтобы получить такой результат: + +1. Добавьте каждому описанию тег `nobuild` (можно использовать любой тег, но для простоты принято добавлять именно этот). + +2. Добавьте фильтр на этот тег: + + ```yaml + filter: + endpoint: tags contains "nobuild" != true + ``` +В результате работы фильтра в документации не будет ненужных страниц. + +### `noindex` + +Позволяет написать условие, определяющее, будет ли описание индексироваться поисковыми роботами. + +#### Синтаксис + +```yaml +noindex: + tag: name == "noindex" +``` + +#### Пример использования + +Необходимо скрыть описание от поисковых роботов. Чтобы получить такой результат: + +1. Добавьте каждому описанию тег `noindex` (можно использовать любой тег, но для простоты принято добавлять именно этот). +2. Добавьте фильтр на этот тег: + + ```yaml + noindex: + tag: name == "noindex" + ``` \ No newline at end of file diff --git a/ru/guides/source-docs.md b/ru/guides/source-docs.md new file mode 100644 index 0000000..106c35d --- /dev/null +++ b/ru/guides/source-docs.md @@ -0,0 +1,39 @@ +# Source Docs + +Вы можете включить документацию в формате [Source Docs](https://github.com/SourceDocs/SourceDocs) в основной документ. + +{% note warning %} + +sourcedocs-инклюдер находится в процессе деприкации в пользу [generic-инклюдера](generic.md). + +{% endnote %} + +#### Пример использования + +Проект документации лежит в папке `doc_root`. + +Положим результат исполнения Source Docs в папку `doc_root/docs`. + +Включим его в документацию внутри `doc_root/toc.yaml`, указав `includer` sourcedocs. + +Поставим ссылку на сгенерированную разводящую в основной в `doc_root/index.yaml`. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: + - name: docs + include: + path: docs + includer: sourcedocs + mode: link +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: docs + href: docs/ +``` \ No newline at end of file diff --git a/ru/guides/unarchive.md b/ru/guides/unarchive.md new file mode 100644 index 0000000..ad1233a --- /dev/null +++ b/ru/guides/unarchive.md @@ -0,0 +1,42 @@ +# Unarchive + +Вы можете использовать unarchive-инклюдер чтобы распаковать tarball перед тем как применять другие инклюдеры к контенту внутри него, например generic-инклюдер. + +#### Пример использования + +Есть `docs.tar` в корне проекта по пути `doc_root/docs.tar`. + +Внутри `docs.tar` находится контент, который необходимо включить используя generic-инклюдер. + +В этом случае нужно применить цепь инклюдеров `unarchive` -> `generic` для достижения цели. + +```yaml +# doc_root/toc.yaml +title: documentation +href: index.yaml +items: +... + - name: multiple + include: + path: multiple + mode: link + includers: + # run unarchive includer + - name: unarchive + # specify tarball you want to unpack as input parameter + input: docs.tar + # specify output path where tarball content is going to be unpacked + output: unpacked + # run generic includer + - name: generic + # specify path from unarchive includers output field as input path + input: unpacked +``` + +```yaml +# doc_root/index.yaml +title: documentation +links: + - title: openapi + href: openapi/ +``` \ No newline at end of file diff --git a/ru/how-it-work.md b/ru/how-it-work.md index 05206f6..5b30d29 100644 --- a/ru/how-it-work.md +++ b/ru/how-it-work.md @@ -19,103 +19,3 @@ Чтобы изменить стандартное имя репозитория `diplodoc-example`, [свяжитесь с нами](https://diplodoc.com/#contact). {% endnote %} - -## Создание простого документационного проекта в YFM - -### Структура проекта - -Базовый проект состоит из нескольких конфигурационных файлов и страниц с контентом, связанных между собой в следующую структуру: - - -``` -input-folder -|-- .yfm (Файл конфигурации) -|-- toc.yaml (Оглавление) -|-- presets.yaml (Пресеты переменных) -|-- index.yaml (Разводящая страница) -|-- pages (Файлы с контентом) - |-- faq.md - |-- how-to.md -|-- _assets (Каталог с изображениями) - |-- image1.png - |-- image2.png -|-- _includes (Каталог с файлами для переиспользования) - |-- faq_shared_block.md -``` - -Больше информации про параметры и конфигурацию можно найти в разделе [**Документационный проект**](./project/index.md). - -### Сборка проекта - -Сборка выполняется с помощью инструмента [**Builder**](tools/docs/index.md) в командной строке. - -Чтобы запустить сборку, выполните команду, указав обязательные ключи запуска: - - -- input, -i — путь до директории проекта. - - -- output, -o — путь до директории, предназначенной для выходных данных (статических HTML). - -#### Пример - -``` -yfm -i ./input-folder -o ./ouput-folder -``` -### Результат - -После успешного выполнения работы сборщика появляется или готовый проект HTML или проект в YFM. -Часто вывод в YFM применяется для создания подразделов и включения в крупные проекты. - -### Использование - -Готовые проекты в HTML можно использовать локально или разместить на подходящем для Вас хостинге, включая S3-like хранилище. - -## Интеграция в ваш процесс разработки - -### Создание и построение проекта - -В общем случае структура проекта и процедуры построения не отличаются от описанного в предыдущем разделе. -В случае интеграции с вашими СI/CD пайплайнами требуется включение Builder для срабатывания по триггерам обновления документации в репозитории. - -Как для С++ или Java проектов используются специальные компиляторы в пайплайнах, так для документации эта задача выполняется Builder'ом. Он создает готовые документы (артефакты), которые потом можно автоматически разместить на внутренних или внешних ресурсах для пользователей. - - -### Подключение плагинов и расширенная конфигурация - -Как правило, большие документационные проекты используют дополнительные возможности по работе с контентом и специфичные конфигурации для построения. -Примером таких расширений является возможность работы с видео или многострочными таблицами. - -Подробнее о способах корректного отображения и трансформации контента можно почитать на [странице](./plugins/index.md). - -Особенностью конфигурации при построении может быть возможность отключения линтера или сборка проекта в виде одного большого HTML-файла. - -Дополнительно с такими возможностями можно ознакомиться на [странице](./tools/transform/settings.md). - -## Работа с Github и публикация документов на своем домене или домене https://diplodoc.com - -Если ваш проект использует Github как систему контроля версий и место хранения исходного кода вашей документации, Diplodoc позволит создать полностью интегрированный пайплайн работы, покрывающий все шаги от внесения изменений в исходные тексты до построения проекта с помощью Github actions и интеграции с Elastic Search. - -[Свяжитесь с нами](https://diplodoc.com/#contact), чтобы обсудить детали вашей конфигурации и возможные варианты решения. - -### Размещение документа на GitHub Pages - -1. В GitHub в репозитории вашего документа перейдите на вкладку **Settings** и в меню слева выберите **Pages**. - -1. В разделе **Build and deployment** в выпадающем списке выберите **GitHub Actions** и в появившемся блоке **Static HTML** нажмите кнопку **Configure**. Откроется окно редактирования экшна. - -1. В блоке `jobs` после строки `uses: actions/configure-pages@v5` добавьте код - - ```yaml - - name: Build docs - uses: diplodoc-platform/docs-build-action@v3 - with: - src-root: './docs' - build-root: './docs-html' - ``` - -1. Вверху справа нажмите **Commit changes...**, укажите имя коммита в поле **Commit message** и нажмите кнопку **Commit changes**. - -1. Перейдите на вкладку **Actions**. Вверху списка будет ваш последний коммит. - -1. Нажмите на название коммита. После завершения сборки, документ будет размещен на GitHub Pages. Посмотреть его можно по ссылке ниже под надписью **deploy**. diff --git a/ru/index.yaml b/ru/index.yaml index b80fb20..ddc8719 100644 --- a/ru/index.yaml +++ b/ru/index.yaml @@ -4,15 +4,9 @@ meta: title: Метаданные noIndex: true links: -- title: Обзор системы - description: Описание платформы, ее основные возможности, особенности и преимущества. +- title: О платформе + description: Описание платформы, ее особенности и преимущества. href: about.md -- title: Быстрый старт - description: С чего начать работу - href: how-it-work.md -- title: Yandex Flavored Markdown - description: Описание языка Yandex Flavored Markdown. - href: index-yfm.md - - - +- title: Возможности платформы + description: Функциональные возможности Diplodoc + href: features.md diff --git a/ru/installation.md b/ru/installation.md new file mode 100644 index 0000000..6bff62f --- /dev/null +++ b/ru/installation.md @@ -0,0 +1,81 @@ +# Установка и настройка + +## Предварительные требования + +- Node.js — v18.12.1 или выше. +- Текстовый редактор, например, VS Code. +- Терминал — работа с Diplodoc осуществляется через интерфейс командной строки (CLI). + +## Установка + +Установите пакет Diplodoc CLI, выполнив команду: `npm i @diplodoc/cli -g`. + +## Создание простого документационного проекта в YFM + +### Структура проекта + +Базовый проект состоит из нескольких конфигурационных файлов и страниц с контентом, связанных между собой в следующую структуру: + +``` +input-folder +|-- .yfm (Файл конфигурации) +|-- toc.yaml (Оглавление) +|-- presets.yaml (Пресеты переменных) +|-- index.yaml (Разводящая страница) +|-- pages (Файлы с контентом) + |-- faq.md + |-- how-to.md +|-- _assets (Каталог с изображениями) + |-- image1.png + |-- image2.png +|-- _includes (Каталог с файлами для переиспользования) + |-- faq_shared_block.md +``` + +Больше информации про параметры и конфигурацию можно найти в разделе [**Документационный проект**](./project/index.md). + +### Локальная сборка проекта + +Сборка выполняется с помощью инструмента [**Builder**](tools/docs/index.md) в командной строке. + +Чтобы запустить сборку, выполните команду, указав обязательные ключи запуска: + + +- `input, -i` — путь до директории проекта. +- `output, -o` — путь до директории, предназначенной для выходных данных (статических HTML). + +#### Пример + +``` +yfm -i ./input-folder -o ./ouput-folder +``` + +### Результат + +После успешного выполнения работы сборщика появляется или готовый проект HTML или проект в YFM. +Часто вывод в YFM применяется для создания подразделов и включения в крупные проекты. + +### Использование + +Готовые проекты в HTML можно использовать локально или разместить на подходящем для Вас хостинге, включая S3-like. + +#### Публикация на локальном сервере + +Чтобы опубликовать документацию на локальном сервере, выполните команду: + +``` +npx -y @diplodoc/cli@next -i ./input-docs -o ~/output-docs --output-format html && npx http-server ~/output-docs -p 5005 +``` + +Документация будет доступна по адресу + +### Подключение плагинов и расширенная конфигурация + +Как правило, большие документационные проекты используют дополнительные возможности по работе с контентом и специфичные конфигурации для построения. +Примером таких расширений является возможность работы с видео или многострочными таблицами. + +Подробнее о способах корректного отображения и трансформации контента можно почитать на [странице](./plugins/index.md). + +Особенностью конфигурации при построении может быть возможность отключения линтера или сборка проекта в виде одного большого HTML-файла. + +Дополнительно с такими возможностями можно ознакомиться на [странице](./tools/transform/settings.md). diff --git a/ru/project/toc.md b/ru/project/toc.md index e656e42..d26cd97 100644 --- a/ru/project/toc.md +++ b/ru/project/toc.md @@ -203,225 +203,3 @@ items: items: - include: { mode: merge, path: ../relative/path/to/toc.yaml } ``` - -### Вставка произвольного контента (Includers) {#includers} - -Вы можете включить в оглавление произвольный контент через `includers`, но только в случае если `includer` для этого типа контента имплементирован. Список имплементированных инклюдеров можно посмотреть [ниже](#implement-includers). - -Возможные способы указания инклюдеров: - -- массив `includer`-объектов в поле `includers`; - -- `includer`-объект в поле `includer` (_в процессе деприкации в пользу `includers` поля_). - -**Требования к `include`:** - -1. `include` должен иметь поле `path`, куда контент будет включен. - -2. поле `path` должно быть **путем, куда будет включен контент**. - -3. свойство `mode` должно иметь значение `link или пропущенно, `link является дефолтным поведением. - -**Требования к `includers`:** - -`includers` должен быть массивом includer-объектов, которые будут запущенны в указанном порядке. - -**Требования к `includer`:** - -Параметры между includer-объектами разные, но имя `includer` является обязательным параметром. - -`name` указывает имя инклюдера, который запустится. - - -#### Пример использования - -Абстрактный пример использования инклюдеров - -_Уточненный пример смотрите в разделе соответствуещего инклюдера для конкретного примера использования._ - -``` -# toc.yaml -... -items: - - name: - include: - path: - includers: - - name: - : - - name: - - name: - mode: link -... -``` - -#### Список имплементированных инклюдеров {#implement-includers} - -- [Generic](#includers-generic); -- [Open API](#includers-open-api); -- [Unarchive](#includers-unarchive); -- [Source Docs](#includers-source-docs) (_в процессе деприкации в пользу generic инклюдера_). - -#### Generic {#includers-generic} - -Вы можете сгенерировать документацию в markdown-формате любой утилитой и включить её в основную документацию. - -Инклюдер сгенерирует по ней оглавление и включит контент в документацию. - -**Пример использования:** - -Проект документации лежит в `doc_root` папке. - -Положим сгенерированный контент в папку `doc_root/docs`. - -Включим этот контент с помощью generic-инклюдера в `doc_root/toc.yaml`. - -Подключим разводящую в `doc_root/index.yaml`. - -```yaml -# doc_root/toc.yaml -title: documentation -href: index.yaml -items: - - name: docs - include: - path: docs - includers: - - name: generic - input: docs - mode: link -``` - -```yaml -# doc_root/index.yaml -title: documentation -links: - - title: docs - href: docs/ -``` - -#### Open API {#includers-open-api} - -Вы можете сгенерировать документ из [OpenAPI-спецификации](https://www.openapis.org/) и включить её в основной документ. - -{% note warning %} - -Openapi-инклюдер требует разрешение на использование HTML в документации, поэтому внутри конфигурации `.yfm` укажите значение `allowHTML: true`. - -{% endnote %} - -**Пример использования:** - -Проект документации лежит в `doc_root`. - -Положим openAPI-спецификацию по пути `doc_root/openapi.yaml`. - -Включим её в `doc_root/toc.yaml` с помощью openapi-инклюдера. - -Подключим разводящую в `doc_root/index.yaml`. - -```yaml -# doc_root/toc.yaml -title: documentation -href: index.yaml -items: - - name: openapi - include: - path: openapi - includers: - - name: openapi - input: openapi.yaml - mode: link -``` - -```yaml -# doc_root/index.yaml -title: documentation -links: - - title: openapi - href: openapi/ -``` - -#### Unarchive {#includers-unarchive} - -Вы можете использовать unarchive-инклюдер чтобы распаковать tarball перед тем как применять другие инклюдеры к контенту внутри него, например generic-инклюдер. - -**Пример использования:** - -Есть `docs.tar` в корне проекта по пути `doc_root/docs.tar`. - -Внутри `docs.tar` находится контент, который необходимо включить используя generic-инклюдер. - -В этом случае нужно применить цепь инклюдеров `unarchive` -> `generic` для достижения цели. - -```yaml -# doc_root/toc.yaml -title: documentation -href: index.yaml -items: -... - - name: multiple - include: - path: multiple - mode: link - includers: - # run unarchive includer - - name: unarchive - # specify tarball you want to unpack as input parameter - input: docs.tar - # specify output path where tarball content is going to be unpacked - output: unpacked - # run generic includer - - name: generic - # specify path from unarchive includers output field as input path - input: unpacked -``` - -```yaml -# doc_root/index.yaml -title: documentation -links: - - title: openapi - href: openapi/ -``` - -#### Source Docs - -Вы можете включить документацию в формате [Source Docs](https://github.com/SourceDocs/SourceDocs) в основной документ. - -{% note warning %} - -sourcedocs-инклюдер находится в процессе деприкации в пользу [generic-инклюдера](#includers-generic). - -{% endnote %} - -##### Пример использования - -Проект документации лежит в папке `doc_root`. - -Положим результат исполнения Source Docs в папку `doc_root/docs`. - -Включим его в документацию внутри `doc_root/toc.yaml`, указав `includer` sourcedocs. - -Поставим ссылку на сгенерированную разводящую в основной в `doc_root/index.yaml`. - -```yaml -# doc_root/toc.yaml -title: documentation -href: index.yaml -items: - - name: docs - include: - path: docs - includer: sourcedocs - mode: link -``` - -```yaml -# doc_root/index.yaml -title: documentation -links: - - title: docs - href: docs/ -``` - diff --git a/ru/static-template.md b/ru/static-template.md index 780fb8f..9d8a753 100644 --- a/ru/static-template.md +++ b/ru/static-template.md @@ -1,4 +1,4 @@ -# Тестового шаблон +# Шаблон проекта В репозитории есть [шаблон тестового проекта](https://github.com/diplodoc-platform/static-template). Форкните репозиторий шаблона, чтобы быстро развернуть свою документацию diff --git a/ru/toc.yaml b/ru/toc.yaml index 91a11d5..3513c14 100644 --- a/ru/toc.yaml +++ b/ru/toc.yaml @@ -30,27 +30,33 @@ navigation: rightItems: - type: controls items: - - name: О платформе + - name: Платформа Diplodoc labeled: true href: index.yaml - - name: Обзор системы + - name: О платформе href: about.md + - name: Функциональные возможности + href: features.md + - name: Релизы YFM + hidden: true + href: changelog.md - name: Начало работы + labeled: true items: - - name: Быстрый старт + - name: Публикация на Diplodoc.com href: how-it-work.md - - name: Тестовый шаблон + - name: Локальная сборка проекта + href: installation.md + - name: Шаблон проекта href: static-template.md - - name: Настройка личного домена - href: personal-domain-ya-cloud.md - - name: Yandex Flavored Markdown - expanded: true - href: index-yfm.md + - name: Редактирование контента + labeled: true items: - name: Синтаксис + href: syntax/index.md items: - - name: Обзор - href: syntax/index.md + - name: Yandex Flawored Markdown + href: index-yfm.md - name: Базовая разметка href: syntax/base.md - name: Списки @@ -79,9 +85,7 @@ items: href: syntax/term.md - name: Дополнительные возможности href: syntax/additional.md - - name: Настройки YFM-проекта - href: settings.md - - name: Организация YFM-проекта + - name: Организация контента items: - name: Обзор href: project/index.md @@ -91,68 +95,91 @@ items: href: project/navigation.md - name: Разводящая страница href: project/leading-page.md - - name: Поиск - href: project/search.md - - name: Page constructor - items: - - name: Обзор - href: project/page-constructor.md - - name: Пример 1 - href: project/pc-example1.yaml - - name: Пример 2 - href: project/pc-example2.yaml - - name: Пример 3 (fullScreen mode) - href: project/pc-example3.yaml - - name: Пресеты переменных - href: project/presets.md - - name: Файл конфигурации - href: project/config.md - - name: Переиспользование контента - href: project/includes.md - - name: Файл конфигурации линтера - href: project/lint.md - - name: Инструменты и библиотеки + - name: Page constructor items: - - name: Transformer - items: - - name: Обзор - href: tools/transform/index.md - - name: Настройки - href: tools/transform/settings.md - - name: Подсветка кода - href: tools/transform/highlight.md - - name: Builder - items: - - name: Обзор - href: tools/docs/index.md - - name: Сборка - href: tools/docs/build.md - - name: Настройки сборки - href: tools/docs/settings.md - - name: Локализация - href: tools/docs/translate.md - - name: Одностраничная сборка - href: tools/docs/singlepage.md - - name: Выкладка на S3 - href: tools/docs/publish-s3.md - - name: Библиотека Mermaid - href: tools/mermaid.md - hidden: true + - name: Обзор + href: project/page-constructor.md + - name: Пример 1 + href: project/pc-example1.yaml + - name: Пример 2 + href: project/pc-example2.yaml + - name: Пример 3 (fullScreen mode) + href: project/pc-example3.yaml + - name: Конфигурация проекта + labeled: true + items: + - name: Настройки проекта + href: settings.md + - name: Файл конфигурации + href: project/config.md + - name: Поиск + href: project/search.md + - name: Пресеты переменных + href: project/presets.md + - name: Переиспользование контента + href: project/includes.md + - name: Файл конфигурации линтера + href: project/lint.md + - name: Публикация + href: deploy.md + labeled: true + items: + - name: Github Pages + href: github-pages.md + - name: Внесение изменений + href: contribution.md + - name: Практические руководства + labeled: true + items: + - name: Контентная аналитика + href: guides/content-analytics.md + - name: Настройка личного домена + href: personal-domain-ya-cloud.md + - name: Автогенерация и интеграция документации + href: guides/includers.md + items: + - name: Generic + href: guides/generic.md + - name: Open API + href: guides/openapi.md + - name: Unarchive + href: guides/unarchive.md + - name: Source Docs + href: guides/source-docs.md + - name: Инструменты и библиотеки + labeled: true + items: + - name: Transformer + items: + - name: Обзор + href: tools/transform/index.md + - name: Настройки + href: tools/transform/settings.md + - name: Подсветка кода + href: tools/transform/highlight.md + - name: Builder + items: + - name: Обзор + href: tools/docs/index.md + - name: Сборка + href: tools/docs/build.md + - name: Настройки сборки + href: tools/docs/settings.md + - name: Локализация + href: tools/docs/translate.md + - name: Одностраничная сборка + href: tools/docs/singlepage.md + - name: Выкладка на S3 + href: tools/docs/publish-s3.md - name: Плагины items: - name: Обзор href: plugins/index.md - name: Дополнительные плагины href: plugins/import.md - - name: Внесение изменений - href: contribution.md - - name: Релизы YFM + - name: Библиотека Mermaid + href: tools/mermaid.md hidden: true - href: changelog.md - - name: Практические руководства - items: - - name: Контентная аналитика - href: guides/content-analytics.md - name: Вакансии hidden: true items: