Быстрый старт

Подготовка

• Установите Node.js v22 или выше.

• Установите текстовый редактор, например VS Code.

• Установите пакет Diplodoc CLI, выполнив в терминале команду npm i @diplodoc/cli -g.

Создание проекта

Использование шаблона

Вы можете использовать шаблон тестового проекта из нашего репозитория.

Сделайте форк репозитория шаблона, чтобы быстро развернуть свою документацию:

1. На странице шаблона рядом с заголовком нажмите кнопку Fork. Откроется страница Create a new fork.

2. Нажмите Create fork. В вашем профиле GitHub будет создан репозиторий с готовой структурой проекта.

3. Склонируйте созданный репозиторий на свой компьютер.

Структура проекта

doc-folder
|-- .yfm # Файл конфигурации
|-- toc.yaml # Оглавление
|-- index.md # Разводящая страница
|-- content-page.md # Страница с контентом

• Конфигурационный файл .yfm.
• Разводящая страница.
• Страницы с контентом.
• Файл оглавления toc.yaml.

Подробнее о параметрах и конфигурации читайте в разделе Документационный проект.

Сборка проекта

Сборка выполняется с консольной утилиты yfm и команды yfm build.

Чтобы собрать проект, выполните команду:

yfm build -i ./doc-folder -o ./output-folder

Где:

• -i — путь до директории проекта (например, папка, которую вы склонировали).
• -o — путь до директории, куда будут сохранены статические HTML-файлы.

После успешного выполнения появится папка с готовым HTML-проектом.

Запуск локального сервера

Чтобы посмотреть результат сборки в браузере, используйте локальный веб-сервер.

1. Соберите проект:

   yfm build -i ./doc-folder -o ./output-folder
   

   Совет

   Используйте watch-режим. Для этого добавьте флаг --watch, чтобы изменения сразу отображались в локальной сборке.

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

2. Запустите сервер для папки с результатом сборки с помощью пакета http-server:

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

Документация будет доступна по адресу http://localhost:5005.

Публикация на GitHub Pages

1. Перейдите в репозиторий вашего документа на GitHub, откройте вкладку Settings и в меню слева выберите Pages.

2. В разделе Build and deployment в выпадающем списке выберите GitHub Actions.

3. В появившемся блоке Static HTML нажмите Configure. Откроется окно GitHub Actions.

4. В файле workflow найдите блок jobs и после строки uses: actions/configure-pages@v5 добавьте:

   - name: Build docs
     uses: diplodoc-platform/docs-build-static-action@v1
     with:
       src-root: './docs'
       build-root: './docs-html'
   

5. В том же файле найдите шаг Upload artifact и измените путь на каталог с собранной документацией:

   - name: Upload artifact
     uses: actions/upload-pages-artifact@v3
     with:
       path: './docs-html'
   

6. В правом верхнем углу нажмите Commit changes..., в поле Commit message укажите сообщение коммита и нажмите Commit changes.

7. Перейдите на вкладку Actions. Вверху списка будет ваш последний коммит.

8. Нажмите на название коммита. После завершения сборки документ будет размещен на GitHub Pages. Посмотреть его можно по ссылке ниже под надписью deploy.

Публикация на diplodoc.com

1. Перейдите на сайт diplodoc.com и нажмите кнопку Начать.

2. Следуйте инструкции, указанной на странице.

3. На вашей странице GitHub будет автоматически создан репозиторий diplodoc-example и создана ссылка на пример документации.