Перейти к основному содержимому

Как редактировать документацию

Где находятся исходники​

Документация каждого проекта хранится в репозитории самого проекта, а не в репозитории Docusaurus.

Расположение документации по проектам​

ПроектРепозиторийПапка документации
Commonrr-git.gitlab.yandexcloud.net/commondocumentation/
Mediarr-git.gitlab.yandexcloud.net/mediadocumentation/
Scountrr-git.gitlab.yandexcloud.net/scountdocumentation/

Процесс редактирования​

Шаг 1: Откройте репозиторий проекта​

# Пример для проекта Common
cd E:\Working\Gitlab\Common

# Убедитесь, что вы на актуальной ветке
git checkout master
git pull

Шаг 2: Внесите изменения​

Отредактируйте нужный markdown файл:

# Пример
code documentation/processes/development.md

Шаг 3: Закоммитьте изменения​

git add documentation/
git commit -m "documentation: обновлена документация по процессу разработки"
git push origin master

Шаг 4: Автоматический деплой​

После push в master ветку:

  1. GitLab CI/CD автоматически синхронизирует документацию
  2. Соберёт новую версию сайта
  3. Задеплоит на https://docs.softproduct.pro

Обычно занимает 3-5 минут.

Создание новой страницы​

1. Создайте markdown файл​

cd documentation/your-section/
touch new-page.md

2. Добавьте frontmatter​

---
sidebar_position: 3
title: Название новой страницы
---

# Название новой страницы

Содержимое страницы...

3. Напишите содержимое​

Используйте стандартный Markdown синтаксис:

## Заголовок раздела

Текст параграфа с **жирным** и *курсивом*.

- Список
- элементов

### Подзаголовок

> Цитата или важное примечание

```bash
# Блок кода
echo "Hello, World!"
```

[Ссылка](https://example.com)

Создание категории (раздела)​

Для группировки страниц в боковом меню:

1. Создайте папку​

mkdir documentation/new-category

2. Добавьте _category_.json​

cd documentation/new-category
cat > _category_.json << EOF
{
  "label": "Новая категория",
  "position": 5,
  "collapsible": true,
  "collapsed": false
}
EOF

3. Добавьте страницы в категорию​

Создайте markdown файлы в этой папке, они автоматически попадут в категорию.

Редактирование в Obsidian​

Вы можете использовать Obsidian для более удобного редактирования:

Настройка​

  1. Откройте Obsidian
  2. Создайте новый Vault → "Open folder as vault"
  3. Выберите папку с документацией проекта (например, E:\Working\Gitlab\Common\documentation)

Плагины для Obsidian​

Рекомендуемые плагины:

  • Obsidian Git - для коммитов прямо из Obsidian
  • Paste Image - для вставки изображений
  • Markdown Table Editor - для редактирования таблиц
  • Markdown Formatting Assistant - для форматирования

Важно​

⚠️ Навигация в Docusaurus определяется не структурой папок, а:

  • Полем sidebar_position в frontmatter
  • Файлами _category_.json

Поэтому в Obsidian граф связей будет работать, но навигация может отличаться от сайта.

Для удобства восприятия навигации в Obsidian рекомендуется выстраивать порядок файлов с помощью числовых префиксов 01, 02 и т.д. Например:

documentation/
├── processes/
│   ├── 01-doc1.md
│   └── 02-doc2.md

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

Размещение изображений​

Храните изображения в папке img/ рядом с документацией:

documentation/
├── processes/
│   ├── img/
│   │   └── workflow.png
│   └── development.md

Вставка в документ​

![Описание изображения](./img/workflow.png)

Изображения в Obsidian​

Obsidian автоматически создаст правильный путь при вставке изображения через Paste Image.

Форматирование кода​

Inline код​

Используйте обратные кавычки:

Запустите команду `npm start` для dev-сервера.

Блоки кода​

С подсветкой синтаксиса:

```typescript
function hello(name: string): string {
  return `Hello, ${name}!`;
}
```

Поддерживаемые языки: typescript, javascript, python, bash, json, yaml, dockerfile, и другие.

Специальные элементы Docusaurus​

Примечания (Admonitions)​

:::note
Это обычное примечание
:::

:::tip[Совет]
Это полезный совет
:::

:::warning[Предупреждение]
Будьте внимательны!
:::

:::danger[Опасно]
Критическое предупреждение
:::

Табы​

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm" default>
    ```bash
    npm install
    ```
  </TabItem>
  <TabItem value="yarn" label="Yarn">
    ```bash
    yarn install
    ```
  </TabItem>
</Tabs>

Проверка изменений локально​

Dev-режим (без поиска)​

cd E:\Working\Gitlab\Common\docusaurus\Docusaurus
npm start

Откроется http://localhost:3000 с hot reload.

Продакшн-режим (с поиском)​

npm run build
npm run serve

Откроется http://localhost:3000 в продакшн-режиме.

Частые проблемы​

Изменения не появляются на сайте​

Причина: Забыли синхронизировать (закомитить) документацию, или не отработал пайплайн публикации.

Навигация работает неправильно​

Причина: Отсутствует sidebar_position в frontmatter.

Решение: Добавьте frontmatter во все markdown файлы:

---
sidebar_position: 1
title: Название
---

Причина: Неправильные ссылки между страницами.

Решение: Используйте относительные пути:

[Другая страница](./other-page.md)
[Страница в категории](../category/page.md)

Изображения не отображаются​

Причина: Неправильный путь к изображению.

Решение: Используйте относительные пути от текущего файла:

![Alt](./img/image.png)

Стандарты оформления​

Заголовки​

  • Используйте один H1 (#) в начале документа
  • Структурируйте контент с H2 (##) и H3 (###)
  • Не пропускайте уровни (не делайте H1 → H3)

Ссылки​

  • Используйте описательный текст вместо "нажмите здесь"
  • ✅ [документация API](./api.md)
  • ❌ [здесь](./api.md) документация API

Списки​

  • Используйте - для ненумерованных списков
  • Используйте 1. для нумерованных списков
  • Добавляйте пустую строку перед и после списка

Код​

  • Всегда указывайте язык для блоков кода
  • Для команд терминала используйте bash
  • Для конфигов указывайте формат: json, yaml, toml

Полезные ссылки​