Contributing

Разработка сайта

Инструменты

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

npm — можно установить через пакетный менеджер, например apt install node (обычно поставляется в пакете node)
IDE с плагином для asciidoctor
- Для JetBrains IDE советую установить плагин https://plugins.jetbrains.com/plugin/7391-asciidoc

Склонируйте проект и из его корня исполните:

npm install

Проект использует сабмодули, поэтому используйте флаг --recurse-submodules при клонировании.

Просмотр сайта

Чтобы запустить сборку сайта, исполните:

npx antora --stacktrace antora-playbook.yml

Чтобы увидеть полученный результат, нужно использовать докер (иначе могут не подгружаться иконки):

$ docker compose up -d

Сайт будет доступен на http://localhost:3333. Чтобы посмотреть результат на других устройствах, например, телефоне, подключите их внутри одной сети и узнайте адрес компьютера в ней через hostname -I. После этого можно заменить localhost на полученный адрес (например, 10.207.104.188) и сайт будет доступен для просмотра с телефона.

Если на устройстве настроен файервол, то могут быть проблемы с доступом.

Настройка плейбука

При локальной разработке советую использовать следующую модификацию antora-playbook.yml:

site:
  title: DevTools Book
  start_page: book::index.adoc
content:
  sources:
    - url: .
      branches: [ '*' ]
ui:
  bundle:
    url: https://github.com/progtech-course/antora-ui/releases/download/latest/ui-bundle.zip
    snapshot: true
  supplemental_files: ./supplemental-ui
antora:
  extensions:
    - require: '@antora/lunr-extension'
      languages: [en, ru]

# runtime:
#   fetch: true

Изменения:

url: . — используется локальный репо, а не исходники в гитхабе. Это необходимо обязательно сделать, иначе локальные изменения будут не видны.
runtime: fetch: true — если обновился исходник с UI, то эта настройка перескачает его, иначе будет использоваться закэшированный

Не нужно это коммитить в репозиторий!

Возможности asciidoctor

Посмотреть, как можно оформить материалы, можно на превью UI. Исходники аскидоктора лежат здесь.

Также поддерживается кастомная стилизация TODO:

// TODO
[TIP.todo]
====
Нужна ссыль на mounting process
====

При ее использовании просьба оставлять выше комментарий // TODO — так IDE сможет трекать тудушки в проекте.

При написании страницы добавляйте параметр :description: с кратким описанием, о чем написано на странице, а также указывайте себя в :page-authors:. При указании авторства пишите так же, как в заголовке authors.adoc — иначе не сработают автоматические ссылки.

Для длинных тире используйте два минуса: --. Оборачивайте в два пробела, иначе будут сбиты отступы.

Рекоммендации по оформлению

Красивая диаграмма лучше текста, старайтесь добавлять пояснительные рисунки
Если пример использует несколько файлов, то в конце приложите ссылку на репозиторий, где все лежит вместе. Не забудьте приложить README с описанием, как с этим работать
Если на английском языке используется иной термин, то обязательно укажите его
В конце статьи делается блок Read More, где перечисляются ссылки как на материалы с более детальным изучением, так и на связанные темы. Используйте xref: для ссылки на другие статьи в рамках сайта. Старайтесь избегать отсутствия этого блока
Выделяйте названия файлов через обратные кавычки `` и используйте форматирование текста для улучшения читаемости
Встраиваемый код должен иметь подсветку. Если ее нет в списке поддерживаемых, то надо либо создать самостоятельно, либо обратиться к маинтейнерам для добавления поддержки необходимому синтаксису

Git hook

Чтобы установить хуки с нашими линтерами исполните ./scripts/install-hooks.

Для игнорирования хуков используйте опцию гита --no-verify.

Подключиться к проекту

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