Инструкция по редактированию документации

Эта документация написана с помощью VitePress, и хранится в репозитории на GitHub: wotstat-25/mods-development-docs

Для внесения изменений вам необходим аккаунт на GitHub, если у вас его нет, то зарегистрируйтесь, это бесплатно и не займёт много времени.

Есть два способа внести изменения в документацию:

1. Через кнопку Редактировать страницу внизу каждой страницы. Это быстрый и простой способ внести небольшие правки, например исправить опечатку или добавить пару строк.
2. Через fork репозитория и создание pull request. Этот способ более сложный, но он позволяет вносить более серьёзные изменения, например добавлять новые страницы и статьи.

Подготовка

Чтобы ваш аккаунт отображался в качестве автора изменений внизу страницы, необходимо использовать служебный email‑адрес GitHub. Для этого:

1. Перейдите в настройки вашего аккаунта на GitHub: https://github.com/settings/emails
2. Активируйте опцию Keep my email address private

Редактирование через кнопку Редактировать страницу

1. Перейдите на страницу, которую хотите отредактировать.
2. Нажмите на кнопку Редактировать страницу внизу страницы.
3. Нажмите на кнопку Fork this repository, чтобы создать локальную копию репозитория.
4. После этого в открывшемся интерфейсе вы можете изменить страницу.

Пример интерфейса редактирования

5. После внесения изменений в верхнем правом углу нажмите на кнопку Commit changes.
6. В открывшемся окне введите краткое описание ваших изменений.

Пример окна коммита

7. Нажмите кнопку Create pull request.

Пример окна создания Pull Request

После этого ваши изменения будут отправлены на рассмотрение, и после проверки, они будут приняты в основную документацию.

Редактирование через fork и Pull Request

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

Подготовка

Вам потребуется установить Git, VSCode и Node.js, если у вас их нет, то:

1. Установите Git — это система контроля версий, которая позволит вам работать с репозиторием документации.
2. Установите VSCode — это редактор кода, который мы будем использовать для редактирования документации.
3. Установите Node.js — это среда выполнения JavaScript, которая необходима для запуска VitePress локально. Необходима версия 24 или новее.

Создание fork

1. Перейдите на страницу репозитория документации: wotstat-25/mods-development-docs
2. Нажмите на кнопку Fork в правом верхнем углу страницы.

Интерфейс создания fork

3. Выберите свой аккаунт, в который хотите создать fork. И нажмите на кнопку Create fork.
4. Вас переадресует в вашу личную копию репозитория, в котором вы можете его как угодно редактировать.

Создайте локальную копию

1. Склонируйте ваш fork себе на компьютер:

• На странице вашего fork нажмите на кнопку Code и скопируйте ссылку.

Интерфейс клонирования репозитория

• Откройте VSCode, и в меню Source Control нажмите на кнопку Clone Repository.

Интерфейс клонирования репозитория

• Вставьте скопированную ссылку и нажмите Enter. Выберите папку, в которую хотите склонировать репозиторий.
• После клонирования, VSCode предложит вам открыть склонированный репозиторий, нажмите Open.

2. Установите зависимости, для этого в секции NPM SCRIPTS нажмите на кнопку запуска на строчке setup. У вас откроется терминал, дождитесь окончания установки.

Интерфейс установки зависимостей

3. Запустите локальный сервер для предпросмотра документации: в секции NPM SCRIPTS нажмите на кнопку запуска на строчке dev. Откроется терминал, и после окончания запуска в нём будет ссылка на локальный сервер (обычно http://localhost:5173/). Перейдите по этой ссылке в браузере.

Интерфейс запуска локального сервера

Настройка связанного с GitHub адреса email

Чтобы ваш профиль отображался внизу страницы как автор изменений, необходимо настроить email‑адрес, связанный с вашим аккаунтом на GitHub. Для этого:

1. Перейдите в настройки вашего аккаунта на GitHub: https://github.com/settings/emails
2. Активируйте опцию Keep my email address private
3. Скопируйте служебный email адрес, который выглядит как <username>@users.noreply.github.com
4. В VSCode, внутри проекта, откройте терминал (Ctrl+` или Terminal -> New Terminal) и выполните команду:

git config user.email "<your-email>"

Замените <your-email> на скопированный email адрес.

Внесение изменений

Теперь вы можете вносить изменения в документацию. Все страницы находятся в папке docs, а файлы страниц имеют расширение .md (Markdown).

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

Когда вы достигнете определённого прогресса и захотите сохранить ваши изменения в репозиторий, выполните следующие шаги:

1. В VSCode, в меню Source Control вы увидите список изменённых файлов.
2. Наведите курсор на подраздел Changes и нажмите на кнопку +, чтобы отметить все изменения.
3. Введите краткое описание ваших изменений в поле ввода сверху.

Интерфейс коммита изменений

4. Нажмите на кнопку Commit, чтобы зафиксировать изменения.
5. Нажмите на кнопку Sync Changes, чтобы отправить ваши изменения в GitHub.

Создание Pull Request

1. Перейдите на страницу вашего fork на GitHub.
2. Нажмите на кнопку Contribute и выберите Open pull request.

Интерфейс создания Pull Request

3. В интерфейсе создания Pull Request введите заголовок и описание ваших изменений.

Интерфейс описания Pull Request

4. Если вы уже готовы, нажмите на кнопку Create pull request, чтобы отправить ваши изменения на рассмотрение.

• Если вы хотите продолжить вносить изменения, но уже готовы обсудить текущие, выберите Create draft pull request, чтобы создать черновик Pull Request.

Смена статуса на черновик

После открытия Pull Request, ваши изменения будут рассмотрены, прокомментированы и в случае одобрения, приняты в основную документацию.

При открытом Pull Request вы можете продолжать вносить изменения в ваш fork, и они автоматически будут добавлены в открытый Pull Request. Не забывайте делать Commit и Push ваших изменений.

Assets locality

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

.../edit-docs/
    ├─ index.md
    └─ assets/
        ├── image.png
        └── code.py

Как работать с Markdown

Документация написана с помощью VitePress, который использует расширенный синтаксис Markdown, все возможности которого описаны в официальной документации.

Из основных возможностей, которые могут пригодиться:

Заголовки

# Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня

Якоря для заголовков

## Заголовок 2 уровня {#header-2}

Параграфы

Это первый параграф.

Это второй параграф.

Выделение текста

**Жирный текст**
*Курсивный текст*
~~Зачёркнутый текст~~

Жирный текстКурсивный текстЗачёркнутый текст

Ссылки

[Текст ссылки](https://example.com)

Текст ссылки

Изображения

![Название картинки](./assets/image.png)

Изображение должно находиться в папке assets, которая лежит рядом с файлом страницы.

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

![Название картинки](./assets/image.png){width=400}

Блоки кода

```python
print("Hello, World!")
```

print("Hello, World!")

Вставки кода

Вставки `кода`

Блоки с подсветкой

::: tip СОВЕТ
Это блок с подсветкой для советов.
:::

::: warning ВНИМАНИЕ
Это блок с подсветкой для предупреждений.
:::

::: details ПОДРОБНЕЕ
Это блок с возможностью сворачивания.
:::

СОВЕТ

Это блок с подсветкой для советов.

ВНИМАНИЕ

Это блок с подсветкой для предупреждений.

ПОДРОБНЕЕ

Это блок с возможностью сворачивания.

Списки

- Пункт списка 1
- Пункт списка 2
  - Вложенный пункт списка

• Пункт списка 1
• Пункт списка 2
  • Вложенный пункт списка

Нумерованные списки

1. Первый пункт
2. Второй пункт

1. Первый пункт
2. Второй пункт

Таблицы

| Заголовок 1 | Заголовок 2 |
| ----------- | ----------- |
| Ячейка 1    | Ячейка 2    |

Заголовок 1	Заголовок 2
Ячейка 1	Ячейка 2

Авторы

Andrei Soprachev

История изменений

Последнее редактирование 3 месяца назад

Показать историю

da48d91-AI typos fix

5e1ab64-add pr info

1685eed-how to edit docs

27e7808-Добавить шаг редактирования страницы в документацию

ee18e1c-implement all pages