23.08.2025 14:44
TrueRuslan 1 500 Источник

Diplodoc - платформа для создания технической документации в концепции Docs as Сode с открытым исходным кодом.

Это тоже диплодок
Это тоже диплодок

С помощью Diplodoc можно создавать документы любой сложности, быстро валидировать их и выкладывать в общий доступ, а также настраивать интеграцию с системами автоматической документации. Именно на этой технологии построена документация сервисов Яндекс.

В данной статье я расскажу, как создать базовый скелет документации на примере собственного многостраничного лендинга.

Минимальные требования для разработки

  • Node.js — v18.12.1 или выше;

  • Любой текстовый редактор или IDE (удобнее всего VS Code) .

Установка

Перед начало работы необходимо выполнить установку пачета Diplodoc CLI, выполнив команду npm i @diplodoc/cli -g

Базовая структура проекта

Минимальный проект состоит из файла оглавления (toc.yaml) и файлов с контентом (*.md). Так же можно добавить разводяющую страницу (index.yaml) для навигации и конфигурационный файл (.ymf). И для запуска необходим файл с зависимостями и скриптами package.json . Рекомендую создать директорию docs в корне проекта и в нее добавлять файлы для работы.

Навигация (toc.yaml)

Файл docs/toc.yaml создает структуру навигации шапки сайта. Описывает меню навигации, логотип, социальные ссылки и структуру страниц сайта. 

navigation:
  logo:
    url: ./index.html
    text: TrueRuslan
    target: _self
  header:
    leftItems:
      - text: Главная
        type: link
        url: index.html
        target: _self
      # ... другие пункты меню
    rightItems:
      - type: link
        text: GitHub
        url: https://github.com/True-Ruslan
      # ... социальные ссылки

title: TrueRuslan - Разработчик
href: index.yaml
items:
  - name: Обо мне
    href: ./about.md
  # ... структура страниц

Результат:

Контент (*.md)

В качестве синтаксиса для контента используется Yandex Flavored Markdown, который базируется на CommonMark Spec, дополняя его уникальными элементами из других языков разметки и шаблонизаторов.

В данной статье мы разберем, как создать простые страницы с минимальным набором контента, как встроить просмотр PDF и фото. По сути, в базовом исполнении мы используем классический Markdown.

Пример такого файла с заголовками и ссылками:

# Контакты

{% note info %}

Свяжитесь со мной любым удобным для вас способом. Я всегда открыт для новых проектов и интересных предложений.

{% endnote %}

## Основные способы связи

### ? Мессенджеры

- **Telegram**: [@TrueRuslan](https://t.me/TrueRuslan)

### ? Email

- **Основной**: ruslan.nemikin@gmail.com

### ? Социальные сети

- **GitHub**: [True-Ruslan](https://github.com/True-Ruslan)
- **LinkedIn**: [Ruslan Nemykin](https://linkedin.com/in/trueruslan)
- **Habr**: [Руслан Немыкин](https://habr.com/ru/users/TrueRuslan/)
- **VK**: [Руслан Немыкин](https://vk.com/trueruslan)
- **Instagram**: [true.ruslan](https://instagram.com/true.ruslan)

---

**Не стесняйтесь обращаться!** Я всегда рад новым знакомствам и интересным проектам.

Результат:

Работа с изображениями

Если хотите добавить изображения, то создайте директорию docs/_images. Обязательно перед название папки добавьте нижнее подчеркиваение ( _ ), иначе они будут удалены при сборке.

## Галерея

![Аватарка](./_images/avatar.png "Аватарка"){height=230}

Работа с файлами

Для вставки, например, PDF файла используйте следующую конструкцию:

### Встроенный просмотр

<iframe 
src="cv.pdf" 
width="100%" 
height="800px" 
style="border: 1px solid #e5e5e5; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1);">
  <p>Ваш браузер не поддерживает отображение PDF. 
  <a href="cv.pdf" target="_blank">Открыть резюме в новой вкладке</a></p>
</iframe>

Главная страница (index.yaml)

Для быстрой навигации по документу вы можете оформить корневую страницу в виде сетки с ссылками на основные разделы index.yaml. Файл определяет SEO-метаданные, заголовок страницы и основные ссылки навигации.

Пример:

title: Руслан Немыкин # имя документа
description: Добро пожаловать на мой персональный сайт! # описание документа

meta: # метаданные
  title: Руслан Немыкин - Разработчик
  description: Персональный сайт TrueRuslan - Java-разработчика. Проекты, навыки, контакты.

links: # разделы
  - title: Обо мне
    description: Подробная информация о моем опыте и навыках
    href: ./about.md
  # ... другие ссылки

Результат:

Конфигурация Diplodoc (.ymf)

Файл конфигурации .yfm содержит список всех параметров в формате YAML. Этот файл определяет, как Diplodoc будет обрабатывать ваши Markdown файлы, генерировать HTML и пр.

Например: 

allowHTML: true
outputFormat: html

Полный список параметров доступен по ссылке

Редирект (index.html)

Корневой index.html автоматически перенаправляет посетителей на основную страницу. Обеспечивает автоматический редирект с корня домена на сгенерированную страницу.

Код:

<!DOCTYPE HTML>
<html lang="en-US">
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="refresh" content="0; url=docs-html/index.html">
        <script type="text/javascript">
            window.location.href = "docs-html/index.html"
        </script>
        <title>Diplodoc Playground Redirect</title>
    </head>
    <body>
        If you are not redirected automatically, follow this 
        <a href='docs-html/index.html'>to go to the diplodoc playground</a>.
    </body>
</html>

Зависимости и скрипты (package.json)

Определяет команды для сборки документации и локального запуска сервера.

Пример: 

{
  "name": "@true-ruslan/trueruslan-landing",
  "version": "0.1.2",
  "description": "Многостраничный лендинг TrueRuslan",
  "homepage": "https://wiki.marketdb.ru/",
  "repository": {
    "type": "git",
    "url": "https://github.com/true-ruslan/trueruslan-landing.git"
  },
  "bugs": {
    "url": "https://github.com/true-ruslan/trueruslan-landing/issues",
    "email": "ruslan.nemikin@gmail.com"
  },
  "author": {
    "name": "TrueRuslan",
    "email": "ruslan.nemikin@gmail.com",
    "url": "https://github.com/True-Ruslan"
  },
  "keywords": [
    "diplodoc",
    "markdown-it",
    "markdown",
    "playground",
    "sandbox",
    "documentation",
    "development",
    "hot-reload",
    "codespaces",
    "template"
  ],
  "license": "MIT",
  "main": "scripts/serve.js",
  "scripts": {
    "start": "npm run build:docs && node scripts/serve.js",
    "build:docs": "yfm --input docs --output docs-html"
  },
  "dependencies": {
    "@diplodoc/cli": "^4.24.0",
    "@diplodoc/transform": "^4.14.0",
    "@gravity-ui/page-constructor": "^5.14.1",
    "chokidar": "^3.5.3",
    "express": "5.0.0",
    "glob": "^10.3.4",
    "lodash": "^4.17.21",
    "open": "^8.4.2",
    "parse5": "^7.1.2",
    "parse5-utils": "^2.0.0",
    "serve-static": "2.1.0"
  },
  "devDependencies": {
    "@gravity-ui/uikit": "^6.14.0"
  }
}

После того как мы разобрались с содержанием базовых файлов должна получиться примерно следующая структура проекта:

landing/
├── docs/                   # Исходные Markdown файлы
│   ├── _images/            # Изображения для лендинга
│   ├── main.md             # Основные страницы лендинга
│   ├── *.md                # Дополнительные страницы
│   ├── .yfm                # Конфигурация Diplodoc
│   ├── index.yaml          # Главная страница
│   └── toc.yaml            # Навигация и структура
├── docs-html/              # Сгенерированные HTML файлы после билда
├── package.json            # Зависимости и скрипты
└── index.html              # Редирект на основную страницу

Развертывание

Локально

После того как структура проекта готова, приступаем к локальной сборке проекта и проверки, что все работает. Для ручной сборки и загрузки используем npm run build:docs. После выполнении команда создает папку docs-html с готовыми файлами, которую уже, кстати, можно загрузить на любой статический хостинг.

Далее для локального запуска выполните npm start и перейдите на локальный сервер http://localhost:3000. Если все делали правильно (особенно указали пути к другим файлам), то проект должен запуститься без ошибок и все страницы корректно отображаться.

GitHub Pages

Перейдем к интересному. Публиковать проект мы будет с помощью GitHub сервиса Pages, который будет развернут по адресу https://<username>.github.io/<repository-name> бесплатно и доступен всем.

Для того, что воркфлоу запускался автоматически при каждом пуше в main ветку необходимо добавить еще несколько файлов.

Для начала в корне проекта создадим следующие директории: .github/workflows. Все скрипты сборки будем создавать в папке workflows.

Проверка сборки (build.yml)

Создайте файл build.yml со следующим содержимым:

name: Build

on:
  pull_request:

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Build
        uses: diplodoc-platform/docs-build-action@v3
        with:
          revision: "pr-${{ github.event.pull_request.number }}"
          src-root: "./docs"
          storage-endpoint: ${{ vars.DIPLODOC_STORAGE_ENDPOINT }}
          storage-region: ${{ vars.DIPLODOC_STORAGE_REGION }}
          storage-bucket: ${{ vars.DIPLODOC_STORAGE_BUCKET }}
          storage-access-key-id: ${{ secrets.DIPLODOC_ACCESS_KEY_ID }}
          storage-secret-access-key: ${{ secrets.DIPLODOC_SECRET_ACCESS_KEY }}

Важно! Ничего изменять не нужно. Данный шаг нужен для проверки корректности сборки документации при создании Pull Request.

Статический хостинг (static.yml)

В этой же директории создайте файл static.yml. Данный скрипт автоматически собирает документацию при каждом пуше, развертывает результат на GitHub Pages, а так же использует кэширование npm для ускорения сборки.

Так же ничего менять не нужно. Файл:

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  push:
    branches: ["main", "master", "test"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - name: Install dependencies
        run: npm ci
      - name: Build docs
        run: npm run build:docs
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './docs-html'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Если не хотите разбираться что к чему и копипастить, предлагаю сделать форк моего репозитория, склонировать и играться с содержимым. Но после форка необходимо еще настроить репо, об этом ниже.

Репозиторий проекта по ссылке, а так он выглядит после публикации на GH Pages.

Как сделать форк? Откройте репозиторий по ссылке, и нажмите кнопку fork и далее нажмите на зеленую кнопку Create fork

Дополнительно Docker-образ (deploy.yml)

Далее шаги не обязательны, но почему бы и нет, если можем. Они нужны для публикации контейнера нашего приложения. Для этого добавьте файл deploy.yml, который создает Docker образ с собранной документацией для развертывания в контейнерах на GitHub Packages.

name: Master
on:
  push:
    branches:
      - 'master'
      - 'main'
      - 'rc/**'
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    permissions:
      packages: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
      - name: Init NodeJS
        uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'npm'
      - name: Install Packages
        run: npm install
        shell: bash
      - name: Build
        run: npm run build:docs
      - name: Deploy image
        uses: valitydev/action-deploy-docker@v1.0.16
        with:
          registry-username: ${{ github.actor }}
          registry-access-token: ${{ secrets.GITHUB_TOKEN }}
          dockerfile-path: .
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}

Dockerfile

Создает легковесный образ на базе Nginx с собранной документацией. Создайте файл Dockerfile со следующим содержимым:

FROM nginx:1.21
COPY docs-html /usr/share/nginx/html
COPY nginx.conf /etc/nginx/vhosts.d/checkout.conf

Nginx конфигурация (nginx.conf)

Необходим для настройки веб-сервера для корректного отображения статических файлов:

server {
    listen       8080;
    server_name  localhost;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

Настройка репозитория

Теперь когда наш проект готов необходимо создать публичный GitHub репозиторий. Публичный потому что только так мы сможем бесплатно разворачивать статику на GitHub Pages.

После создания репозитория перейдите во вкладку Settings ->

-> далее перейдите в раздел Pages ->

-> и в разделе Build and deployment нажмите на выпадающее меню и выберите GitHub Actions.

Теперь наш репозиторий готов и после пуша будет собираться и публиковаться статика.

Так же можно вручную запустить джобу сборки и публикации статики:

А если что-то пошло не так, тут же можно посмотреть логи.

После выполнения всех инструкций в вашем репозитории появится следующая информация в разделе Deployments:

Нажав на последнюю сборку вы перейдете на страницу с описанием и историей предыдущих сборок, откуда так же сможете открыть развернутый лендинг.

Должно получиться примерно следующее: https://true-ruslan.github.io/trueruslan-landing/

На этом наш проект готов, пользуйтесь ?

Исходный код проекта смотрите здесь -> TrueRuslan-landing
Если есть вопросы и предложения, пишите в телеграм -> @TrueRuslan
Так же заглядывайте в мой телеграм канал, вдруг выложу что полезно -> @TrueRuslan_Blog

Успехов!

Комментарии (1)


  1. tizian
    23.08.2025 19:37
    #28745254

    Документация без версионирования - это не дело.