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

Для лучшего понимания того, как работать с нашими файлами документации, вам необходимо как минимум иметь общее представление о Hugo (движок рендеринга) и быть знакомым с основными правилами синтаксиса Asciidoc (используемый упрощённый язык разметки). Тем, кто заинтересован в улучшении внешнего вида сайта документации, рекомендуется ознакомиться с Learn (используемая в Hugo тема оформления).

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

В конце статьи даны ссылки на популярные справочные материалы по синтаксису Asciidoc.

Размещение файлов

В основном все файлы, которые необходимо отредактировать, находятся в папке content. Здесь расположены основные разделы руководства, такие как user (Руководство пользователя), admin (Руководство администратора), community (Развитие проекта), developer (Руководство разработчика) и blog (Блог разработчиков).

При необходимости вы можете создавать новые каталоги и файлы внутри перечисленных разделов. В данный момент Hugo использует пути к каталогам и файлам для создания контента. Сейчас мы не используем технологию Page Bundles, хотя и планируем задействовать её в будущем.

Именование файлов

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

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

Даже если файлы и каталоги содержат пробелы и специальные символы, Hugo заменяет их символами тире. Например, путь к файлу Downloading & Installing в каталоге Installation Guide будет заменён на installation-guide/downloading-installing.

Именование файлов перевода

Для файлов перевода мы сохраняем английское имя файла (именно так Hugo получает информацию о том, что это переведённые версии того же самого файла), но добавляем код языка перед расширением .adoc.

Таким образом, два последних файла в списке (испанский, русский) являются переводом первого файла (английский):

requirements.adoc
requirements.es.adoc
requirements.ru.adoc

Мы не используем формат requirements.en.adoc для английской версии файла. Мы сохраняем язык по умолчанию (английский) без указания кода языка в имени файла.

Заголовок файла

Каждый файл в формате Asciidoc начинается с заголовка, например:

---
title: Руководство по созданию документации
weight: 50
---

И хотя в заголовке может быть использовано множество различных переменных, нам потребуются только две их них: title и weight.

  • title - определяет название статьи

  • weight - определяет позицию (вес) статьи в оглавлении, при помощи этой переменной можно указывать порядок следования статей в разделе

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

Атрибуты

Атрибуты Asciidoc оформляются в тексте двоеточиями, ниже перечислены некоторые атрибуты, которые можно использовать в начале файла, сразу после текста заголовка:

Рисование кнопок со специальным графическим оформлением:

:experimental:

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

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

Установка базового каталога изображений:

:imagesdir: /images/ru/admin

К каталогу должен быть указан абсолютный путь (начиная с /), а не относительный (например, ../../images). В случае указания базового каталога ссылки на изображения можно задавать в следующем формате:

image:Имя_файла.png[Альтернативный текст]

Вставка оглавления, автоматически сгенерированного из названий разделов файла:

:toc:

Указание названия оглавления, автоматически сгенерированного из названий разделов файла:

:toc-title: Название_оглавления

Указание уровней оглавления, автоматически сгенерированного из названий разделов файла:

:toclevels: 3

По умолчанию в оглавлении отображаются разделы первого и второго уровня.

Специальные коды

Hugo использует специальные коды для использования различных шаблонов:

Вставка оглавления, автоматически сгенерированного из имён файлов, находящихся в подкаталогах

Для этого используется специальный код, добавленный в индексный файл каталога (_index.ru.adoc), например:

{{% children depth="3" showhidden="true" %}}

Вставка сообщений

При необходимости в текст могут быть вставлены оформленные сообщения различного типа:

  • Информационное сообщение

{{% notice info %}}
Пример информационного сообщения.
{{% /notice %}}

Пример информационного сообщения.

  • Примечание

{{% notice note %}}
Пример примечания.
{{% /notice %}}

Пример примечания.

  • Совет

{{% notice tip %}}
Пример совета.
{{% /notice %}}

Пример совета.

  • Предупреждение

{{% notice warning %}}
Пример предупреждения.
{{% /notice %}}

Пример предупреждения.

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

Создание контента

При создании контента мы следуем этим правилам:

  • Не писать текст на одной строке, если он длиннее ~80 символов. При обычных условиях Asciidoc игнорирует символ переноса строки и объединяет отдельные строки в единый абзац. Мы используем это правило для облегчения редактирование исходного кода на стандартной 80-символьной консоли. Если в конечном html-документе необходимо отобразить принудительный разрыв строки, необходимо использовать символы " +" (пробел и плюс) в конце строки, либо разделять контент пустой строкой.

  • Обрамлять пути, имена файлов, имена переменных и другие выражения, которые могут быть использованы в операциях копирования-вставки косыми кавычками (`):

Вот пример разметки, позволяющий легко скопировать /некий/путь в ваш редактор.

Рекомендации

  • Используйте обычные ссылки Asciidoc для навигации между файлами.

  • На страницах всегда, где это возможно, используйте относительные ссылки. Это необходимо для того, чтобы переведённые страницы могли использовать ту же схему навигации, что и английские страницы. Так что ваши ссылки будут выглядеть так:

link:../../admin/my-page[текст ссылки].

При этом расширение файла в ссылке не указывается.
При использовании ссылок на родительский каталог .. используйте максимально короткий путь, при переходе по каталогам с помощью .. никогда не заходите выше каталога content - это никогда не требуется.

  • Для изображений используйте атрибут :imagesdir: (см. описание выше), а затем используйте ссылку на изображения без указания пути.

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.