From f9be77205d18c261a1d54c4b0f642a07f0d0d554 Mon Sep 17 00:00:00 2001 From: Adyan Imkenov Date: Sun, 24 Nov 2024 12:57:35 +0300 Subject: [PATCH] Change quick-start --- ru/how-it-work.md | 62 -------------------------------- ru/installation.md | 84 ++++++++++++++++++++++++++++++++++++++++++- ru/static-template.md | 2 +- 3 files changed, 84 insertions(+), 64 deletions(-) diff --git a/ru/how-it-work.md b/ru/how-it-work.md index a7ea730..5b30d29 100644 --- a/ru/how-it-work.md +++ b/ru/how-it-work.md @@ -19,65 +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 хранилище. - -### Подключение плагинов и расширенная конфигурация - -Как правило, большие документационные проекты используют дополнительные возможности по работе с контентом и специфичные конфигурации для построения. -Примером таких расширений является возможность работы с видео или многострочными таблицами. - -Подробнее о способах корректного отображения и трансформации контента можно почитать на [странице](./plugins/index.md). - -Особенностью конфигурации при построении может быть возможность отключения линтера или сборка проекта в виде одного большого HTML-файла. - -Дополнительно с такими возможностями можно ознакомиться на [странице](./tools/transform/settings.md). diff --git a/ru/installation.md b/ru/installation.md index c26d11c..7797224 100644 --- a/ru/installation.md +++ b/ru/installation.md @@ -1 +1,83 @@ -# Установка \ No newline at end of file +# Установка и настройка + +## Предварительные требования + +- 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. + +Diplodoc поддерживает размещение на [Github Pages](github-pages.md). + +#### Публикация на локальном сервере + +Чтобы опубликовать документацию на локальном сервере, выполните команду: + +``` +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/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). Форкните репозиторий шаблона, чтобы быстро развернуть свою документацию