Как писать гайды

Из чего состоит гайд

Каждый гайд на сайте — это не только текст, а набор полей, которые вместе формируют карточку на главной странице и страницу раздела.

• Название — заголовок гайда. Используется в карточке, оглавлении и адресе страницы (/guides/...).

• Тип — «Мод» или «Система сервера». Влияет только на подпись на карточке.

• Краткое описание — одна фраза, видна на карточке на главной странице ещё до перехода в гайд.

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

• Автор раздела — необязательное поле, отображается внизу раздела как благодарность.

• Цвет акцента и иконка — визуально отличают гайд на карточках и в оглавлении.

• Тэги — до 5 штук, по ним ищут и фильтруют гайды на главной странице.

• Содержание — сам текст гайда в Markdown.

Как заголовки превращаются в оглавление

Оглавление сбоку строится автоматически из заголовков внутри содержания:

• # — раздел верхнего уровня оглавления.

• ## — подраздел, вложенный в ближайший # выше.

• ### и глубже — тоже отображаются на странице, но в оглавление не попадают.

Ориентируйтесь на уже готовые гайды (Witchery, Blood Magic, Thaumcraft) — везде примерно одинаковая глубина: один # на крупную тему, ## — на механику или предмет внутри неё.

Где всё находится в админке

Управление гайдами — в разделе Гайды админ-панели. Здесь виден список всех гайдов, статус публикации, порядок на главной странице (меняется перетаскиванием) и просмотры.

Новый гайд создаётся кнопкой + Новый гайд. Форма просит только основные поля — содержание и картинки добавляются сразу после создания, на странице редактирования.

Пошаговое создание гайда

Шаг 1. Название и тип

Впишите название так, как оно должно выглядеть на сайте — используется как есть, без автоматических правок регистра. Выберите тип: «Мод» — если гайд про конкретный мод, «Система сервера» — для кастомных механик самого MagicRPG.

Шаг 2. Описание, вступление, автор

Краткое описание — то, что читатель увидит на карточке ещё до перехода в раздел, поэтому оно должно объяснять суть за одну фразу, а не повторять название. Вступление — отдельный абзац уже внутри гайда, перед оглавлением: здесь можно раскрыть мысль из описания подробнее, но всё ещё коротко.

Поле «Автор раздела» заполняйте, если у гайда есть конкретный автор — оно появится внизу раздела как благодарность.

Шаг 3. Цвет и иконка

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

Шаг 4. Тэги

До 5 тэгов через запятую. Уже существующие тэги предлагаются автодополнением при вводе — используйте их вместо похожих по смыслу новых, иначе фильтр на главной странице дробится на дубли («pvp» и «пвп» — для сайта это два разных тэга).

Шаг 5. Содержание

Основная работа — в поле «Содержание» на странице редактирования. Это Markdown-редактор с панелью инструментов:

Кнопки панели:

• B / I — жирный текст и курсив.

• H1 / H2 — заголовок раздела и подраздела (именно они попадают в оглавление, см. выше).

• Списки, таблица, цитата, ссылка — стандартные элементы Markdown.

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

• Вставить изображение — загружает картинку и спрашивает размер (значок / маленький / средний / большой). Изображение всегда пережимается сервером, поэтому не нужно заранее сжимать файл — подойдут PNG, JPEG, WebP и GIF.

• Вставить видео — принимает ссылку на YouTube, RuTube или VK и превращает её во встроенный плеер. Ссылки на другие хостинги не встраиваются и остаются обычной текстовой ссылкой.

Шаг 6. Публикация

Пока не отмечен чекбокс «Опубликован», гайд виден только администраторам по прямой ссылке (кнопка «Смотреть на сайте» открывает страницу даже для черновика). Публикуйте только тогда, когда содержание готово — черновики не появляются в списке гайдов на главной странице ни при какой сортировке.

Стиль письма: единый стандарт

Чтобы гайды не отличались друг от друга по тону, придерживайтесь того же стиля, что уже есть у Witchery, Blood Magic, Botania и Thaumcraft.

Тон

Пишите сразу по делу, без вступлений вроде «в этом гайде мы расскажем». Обращение — на «вы», действия — в повелительном наклонении («создайте», «кликните», «поместите»). Не пересказывайте очевидные вещи и интерфейс игры — только то, что без гайда не понятно.

Термины

Используйте общепринятые сокращения: ПКМ и ЛКМ — правая и левая кнопки мыши. Названия предметов и блоков — как в игре, с заглавной буквы, если это собственное имя.

Структура

Один # на крупную тему раздела, ## — на механику или предмет внутри неё. Не уходите глубже без необходимости: чем ровнее вложенность, тем удобнее оглавление читателю.

Абзацы короткие — 2-4 предложения. Для перечислений (интерфейс, шаги, характеристики предметов) — списки, а не сплошной текст.

Таблицы

Для сравнений и характеристик используйте настоящие Markdown-таблицы, а не текст с ручным выравниванием пробелами — так уже случалось в старых гайдах и ломало вёрстку: без |-разделителей это рендерится как один сплошной абзац, а не таблица.

Формат обычный, GFM: строка заголовков, под ней строка из ---, дальше строки данных — все ячейки разделены |. Готовые примеры уже есть в Witchery и Blood Magic.

Скриншоты

Добавляйте скриншот там, где текстом описывать интерфейс дольше, чем один раз показать: сложное меню, редкая иконка, результат крафта. Подписывайте по шаблону «Что на скриншоте — скриншот MagicRPG» — так подписаны все изображения на сайте.

Тэги, поиск и оценки

Тэги и голоса читателей — часть того, как гайд находят и оценивают на сайте, поэтому они не менее важны, чем сам текст.

На главной странице гайды можно отфильтровать по тэгу и отсортировать по порядку, оценке (лайки минус дизлайки) или просмотрам. Тэги гайда также показываются прямо на его странице:

Голосовать может только авторизованный читатель, один голос на гайд. Повторный клик по той же кнопке снимает голос.

Если у вас нет доступа в админку

Предложить гайд может любой зарегистрированный пользователь — через страницу «Предложить гайд», ссылка на неё есть в шапке сайта после входа. Текст можно написать прямо в форме или прикрепить файлом (.md или .docx).

Заявка попадает на проверку администраторам. Одобренный гайд не публикуется автоматически — админ донастраивает его в обычном редакторе (иконка, картинки, тэги) и публикует отдельным шагом. Изображения из .docx не переносятся — если они нужны, добавьте их заново через редактор уже после одобрения.

Чек-лист перед публикацией

• Описание и вступление не повторяют друг друга дословно.

• Заголовки #/## отражают реальную структуру, без лишней вложенности.

• Таблицы — настоящие Markdown-таблицы, не текст с пробелами вместо |.

• Скриншоты подписаны и стоят рядом с текстом, который описывают.

• Тэгов не больше 5, и они уже существуют в списке (или обоснованно новые).

• Гайд открыт кнопкой «Смотреть на сайте» и проверен вживую до того, как ставить галочку «Опубликован».