Написание руководств

Создание гайд файла

Чтобы начать писать гайд, необходимо создать файл с расширением .mdx. Вам нужно создать этот файл внутри папки /content/docs/ru, теперь это зависит от того, в каком разделе вы хотите сделать гайд, так что вы можете решить, какую папку вы должны положить его после этого.

Предположим, я хочу создать руководство по основам java, тогда я помещу его в /content/docs/ru/guides/java-basics. Вам придется немного поискать, чтобы понять, где именно вы хотите это разместить.

Info

Если в разделе, о котором вы хотите написать, уже есть руководство, вы можете просто нажать кнопку "Edit On GitHub" на нашем сайте. Это перенаправит вас в нужную папку, и вы сможете писать в ней же, чтобы ваше руководство появилось в том же разделе.

Frontmatter

Frontmatter — это метаданные вашего руководства; они сообщают нашему сайту, как отображать ваше руководство. Это должно быть в самом верху файла, который начинается с --- и заканчивается ---.

Вот пример:

---
title: "Java Basics"
description: "Learn the basics of Java programming."
authors:
    - name: "Your Name"
      url: "https://yourwebsite.com"
icon: YourIcon 
---

Как видите, здесь всё довольно очевидно: вам просто нужно заполнить данные для вашего конкретного руководства. Если у вас нет URL-адреса, на который вы хотели бы ссылаться, просто не пишите эту строку целиком. Кроме того, раздел authors (авторы) является необязательным. Если вы не хотите его добавлять, можете просто пропустить его, хотя мы рекомендуем указать себя как автора.

Отступы в Frontmatter важны, поэтому убедитесь, что они соответствуют примеру.

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

Вы должны структурировать содержание вашего руководства четко и организованно. Вот несколько советов, как это сделать:

Введение: Начните с обзора темы и того, чему читатель сможет научиться.
Требования: Перечислите все предварительные требования или базовые знания, которыми должен обладать читатель перед изучением руководства.
Пошаговые инструкции: Разделите контент на четкие, действительные шаги. Используйте заголовки и подзаголовки для организации информации.
Примеры кода: Включите фрагменты кода для иллюстрации ключевых моментов. Обязательно подробно объясняйте каждый пример.
Заключение: Подведите итог основным моментам и побудите читателя изучать тему дальше или опробовать то, чему он научился.

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

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

Форматирование

Мы используем Markdown для форматирования наших гайдов. Вот несколько ключевых моментов, о которых следует помнить:

Используйте заголовки (#, ##, ###), чтобы упорядочить содержимое.
Используйте маркированные и нумерованные списки для наглядности.
Use code blocks (```) for code snippets.
Используйте ссылки для упоминания других руководств или внешних ресурсов.

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

Links

Everyone knows what a link is. However, there is a difference between linking to an external resource and linking to an internal one.

In general, in Markdown they are written like this: [Your Text](Your link)

External

Nothing to explain, just https://example.com.

Internal

You cannot use regular links here. Let's say your link to another guide is https://hytalemodding.dev/en/docs/quick-start. You can't write it like that because you are not only referring to the page but also to the language, which is not correct. Instead, type ./quick-start which is correct and links to the page in the user's language.

Accessing files

Current Folder: ./
Folder above: ../ as many times as this folder is higher in the hierarchy.

Icons

If you want to add an icon for your page then you should use Lucide.

Go to the site and find an icon you like.
Once you have selected an icon, click on it, then click "See in action"
Next, click on "React" which we are using. You will only need the text in the curly brackets on the first line.
Next, simply paste icon: YourIcon into Frontmatter.

Callout

Вы также можете использовать выноски (Callouts), чтобы выделить важную информацию или советы. Используйте следующий синтаксис:

<Callout>
    Сообщение с выноской.
</Callout>

Info

Это сообщение выноски (callout)

Вы можете изменить цвет выноски (callout), добавив атрибут 'type'. Например:

<Callout type="info">
    Это выноска с информацией.
</Callout>

Доступные типы: info, warning, error и success.

Difficulty levels

These are types of callouts, they are optional, they show how complex your page can be. There are 3 main levels of complexity.

Level: Beginner

Use lvl_beginner. This page contains information for those who are starting out with modding.

Level: Intermediate

Use lvl_intermediate. This page contains information for those who want to deepen their knowledge.

Level: Advanced

Use lvl_advanced. This page contains information for those who already know how to make quality mods, and contains something additional.

Their usage is the same as in callout, but we would advise not to change the title. Inside, you write why your page is classified as this level and what the user should know.

Заключение

Вот и все! Теперь вы --- гайд мастер. Главное помните, вам не нужно в совершенстве владеть английским, пишите руководство так, как объясняли бы тему кому-либо и не стесняйтесь просить обратную связь или помощь, если она вам понадобится.

Удачи в написании!

Написание руководств

On this page