Руководство по внесению вклада в документацию Fabric

Этот сайт использует VitePress для генерации статического HTML-кода из различных Markdown-файлов. Вы можете ознакомиться с Markdown-расширениями для VitePress здесь.

Содержание

• Руководство по внесению вклада в документацию Fabric
  • Как внести свой вклад
  • Вклад в фреймворк
  • Вклад в содержимое
    • Стандарты оформления
    • Справка по дополнениям
    • Проверка содержимого
    • Полировка
  • Перевод документации

Как внести свой вклад

Рекомендуется создавать новые ветки в вашем форке репозитория для каждого pull request'а, который вы делаете. Это упрощает управление несколькими pull request'ами одновременно.

Если вы хотите предварительно просматривать свои изменения локально, вам нужно будет установить Node.js версии 18 или выше.

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

Запуск сервера для разработки:

Это позволит вам предварительно просматривать ваши изменения локально по адресу localhost:3000 и автоматически перезагрузит страницу при внесении изменений.

npm run dev

Компиляция веб-сайта:

Это преобразует все файлы Markdown в статические HTML-файлы и разместит их в папке .vitepress/dist

npm run build

Предварительный просмотр собранного веб-сайта:

Это запустит локальный сервер на порту 3000, отображающий содержимое, найденное в .vitepress/dist

npm run preview

Вклад в развитие фреймворка

Под фреймворком понимается внутренняя структура веб-сайта; любые pull request'ы, изменяющие фреймворк сайта, должны быть помечены меткой framework.

К вашему сведению, вы должны делать pull request'ы, касающиеся фреймворка, только после консультации с командой документации на Discord-сервере Fabric или через issue.

Примечание: Изменение файлов боковой панели и конфигурации панели навигации не считается pull request'ом, касающимся фреймворка.

Вклад в содержимое

Вклад в содержимое является основным способом внести свой вклад в документацию Fabric.

Все материалы должны соответствовать нашим стандартам оформления.

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

Все страницы веб-сайта документации Fabric должны следовать стилевому руководству. Если вы в чем-то не уверены, вы можете спросить в дискорде Fabric или в обсуждениях в GitHub.

Стандарты по стилю выглядит следующим образом:

1. Все страницы должны иметь заголовок и описание.

   ---
   title: This is the title of the page
   description: This is the description of the page
   authors:
     - GitHubUsernameHere
   ---
   
   # ...

2. Если вы создаете или изменяете страницы, содержащие код, разместите код в исходных файлах мода с примерами (находится в папке /reference репозитория). Затем используйте функцию отображения кода в VitePress для встраивания кода, либо функцию transclude из markdown-it-vuepress-code-snippet-enhanced.

   Пример:

   <<< @/reference/latest/src/main/java/com/example/docs/FabricDocsReference.java{15-21 java}

   Это выведет все линии с 15 по 21 из файла FabricDocsReference.java из мода с примерами.

   Фрагмент кода будет выглядеть следующим образом:

     @Override
     public void onInitialize() {
       // This code runs as soon as Minecraft is in a mod-load-ready state.
       // However, some things (like resources) may still be uninitialized.
       // Proceed with mild caution.
   
       LOGGER.info("Hello Fabric world!");
     }

   Пример с Transclude:

   @[code transcludeWith=#test_transclude](@/reference/.../blah.java)

   Таким образом будут вставлены фрагменты из blah.java, помеченные тегом #test_transclude.

   Пример:

   public final String test = "Bye World!"
   
   // #test_transclude
   public void test() {
     System.out.println("Hello World!");
   }
   // #test_transclude

   Код между тегами #test_transclude будет выведен.

   public void test() {
     System.out.println("Hello World!");
   }

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

4. Если вы создаете новую категорию, вам следует создать новую боковую панель в папке .vitepress/sidebars и добавить её в файл config.mts. Если вам нужна помощь с этим, спросите в дискорде Fabric в канале #docs.

5. При создании новой страницы вы должны добавить ее на соответствующую боковую панель в папке .vitepress/sidebars. Опять же, если вам нужна помощь, спросите в дискорде Fabric в канале #docs.

6. Любые изображения должны находиться в соответствующем месте в папке /assets.

7. ⚠️ Ссылки на другие страницы должны быть относительными. ⚠️

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

   Например, для страницы в папке /players, ссылка на страницу installing-fabric по пути /players/installing-fabric.md, вы должны сделать следующее:

   [Ссылка на другую страницу](./installing-fabric.md)

   Вы НЕ должны делать так:

   [Ссылка на другую страницу](/player/installing-fabric.md)

Все материалы проходят три этапа:

1. Справка по дополнению (если возможно)
2. Проверка содержимого
3. Очистка (грамматика и т.д.)

Справка по дополнениям

Если команда документации сочтёт, что вы могли бы дополнить свой реквест, член команды добавит пометку expansion к вашему реквесту вместе с комментарием, объясняющим, что, по их мнению, вы могли бы дополнить. Если вы согласны с этим предложением, вы можете дополнить свой реквест.

Не чувствуйте давления от просьбы дополнить ваш реквест. Если вы не хотите дополнять свой реквест, вы можете просто попросить удалить пометку expansion.

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

Проверка содержимого

Все реквесты, добавляющие содержимое, проходят проверку. Это самый важный этап, поскольку он гарантирует, что контент является точным и соответствует стандартам стиля документации Fabric.

Полировка

На этом этапе наша команда исправит любые грамматические ошибки и внесёт некоторые изменения, которые она сочтёт необходимыми, прежде чем объединить реквест с основным проектом!

Перевод документации

Если вы хотите перевести документацию на свой язык, вы можете сделать это на странице Fabric на Crowdin.