requirements.adoc
requirements.es.adoc
requirements.ru.adocДля лучшего понимания того, как работать с нашими файлами документации, вам необходимо как минимум иметь общее представление о 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.