Antora Navigator Extension

Форк расширения Antora с небольшими изменениями. Расширение экспортирующее навигационные данные в JavaScript, что позволяет строить дерево навигации в браузере.

Warning

ПО в состоянии разработки! Расширение является экспериментальным и может быть изменено в любое время без предварительного уведомления. Вы можете протестировать данное ПО и предоставить обратную связь. Полагаться на расширение в производственной среде следует с осторожностью.

Копирайт и лицензия

Использование данного ПО предоставляется на условиях o Mozilla Public License версии 2.0 (MPL-2.0). См. полный текст лицензии по ссылке LICENSE.

Настройка расширения Antora Navigator

Расширение Antora Navigator позволяет создать навигационные группы компонентов Antora в меню. Группы компонентов Antora и их порядок можно задать в файле antora-navigator.yml.

antora-navigator.yml:

groups:
- root: true (1)
components: home
- title: Demo (2)
components: 'component-*' (3)
- title: Asciidoctor
components: ['*', '!asciidoctorj'] (4)
output_file: site-navigation-data.js (5)
subcomponents: (6)
- parent: connectors (7)
  components: ['number*-connector', '*-connector'] (8)

Регулирует наличие корневой группы, которая отображается в меню первой. По умолчанию это группа со ссылкой на главную страницу.
Название группы компонентов в формате glob pattern. Аналогичный формат используется при указании версий в Antora playbook.

Имя компонента — строковое значение, необходимо указывать в кавычках.
Если необходимо указать несколько компонентов, возьмите диапазон компонентов в квадратные скобки. Разделяйте имена компонентов запятой. Аналогичные правила исключения и включения компонентов используются при указании веток в Antora playbook.
Имя и расположение результирующего файла с данными навигации.
Объявляет группу субкомпонентов.
Указывает родительский компонент, который будет включать подчинённые компоненты.
Указывает диапазон компонентов, которые будут являться подчинёнными родителю.

Требования к навигационным файлам в формате AsciiDoc

Расширение Antora Navigator накладывает определённые условия на формат файла навигации для компонентов Antora. Требования перечислены ниже.

Требования к первой строке навигации

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

.xref:title.adoc[Title] (1)
* xref:title.adoc[] (2)

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

Если формат не соответствует данному требованию, в навигационном меню будут пропущены все строки, не являющиеся ссылками.

Подобный формат должен использоваться только один раз для каждого компонента. Например, если в файле antora.yml для компонента первым указан навигационный файл для модуля ROOT, требование относится только к данному файлу:

antora.yml

nav:
- modules/ROOT/nav.adoc

Использовать подобный формат строк навигации разрешается только один раз.

Подобные заголовки не допускаются нигде, кроме первой строки данного навигационного файла (включая следующие строки).

.Title
* xref:title.adoc[]

Требование не распространяется на файлы навигации для последующих модулей.

Требования ко второй и следующим строкам навигации

Во втором и следующих файлах навигации версии компонента запрещается использовать заголовки вида:

.Title
* xref:title.adoc[]

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

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

* Title
** xref:title.adoc[]

Локализация элементов навигации

Расширение по умолчанию использует следующие формулировки для элементов навигационного меню:

Название корневой группы в меню навигации. По умолчанию: На главную.
Подсказки для версий: Последняя версия, Предрелизные версии, Предыдущие версии.

Локализовать или изменить эти значения можно в файле nav.js.

На главную — строки 133 и 134.
Последняя версия — line 243
Предрелизные версии — line 245
Предыдущие версии — line 247

Настройка пользовательского интерфейса

В репозитории расширения в директории "supplemental-ui/partials" располагаются файлы с шаблонами страниц. Эти файлы заменяют одноимённые в проекте пользовательского интерфейса. Например, в пользовательском интерфейсе сайта Docsvision.

Если вы используете пользовательский интерфейс, производный от пользовательского интерфейса сайта Docsvision, добавьте в файл footer-scripts.hbs следующие строки:

<script src="{{{siteRootPath}}}/site-navigation-data.js"></script>
<script src="{{{uiRootPath}}}/js/nav.js"></script>
<script src="{{{uiRootPath}}}/js/site.js"></script>

При необходимости аналогичным образом отредактируйте файлы head-meta.hbs и nav.hbs.

Если вы используете изменённые файлы js или сss в пользовательском интерфейсе, приведите их в соответствие с файлами данного проекта: js сss.

Настройка иконок компонентов навигационного меню

Расширение Antora Navigator позволяет использовать специальные иконки для групп компонентов в навигационном меню.

По умолчанию для всех навигационных групп используется одна иконка. Для сайта документации Docsvision были разработаны специальные иконки компонентов.

Иконки можно изменить в файле icondefs.js.

icondefs.js

;(function () {
  /* eslint-disable max-len */
  // prettier-ignore
  var defs = [
    {
      id: 'icon-nav-component', (1)
      viewBox: '0 0 30 30',
      path: { d: 'M19.9035 16.7957L22.0559 24.8282C19.8893 25.7545 17.5053 26.2702 15 26.2702C12.4947 26.2702 10.1107 25.7545 7.94414 24.8282L10.0965 16.7957C7.16563 15.0998 5.19232 11.9329 5.19232 8.30324C5.19232 6.65115 5.6026 5.09557 6.32406 3.72984L12.9574 13.2033H17.0426L23.676 3.72984C24.3974 5.09557 24.8077 6.65115 24.8077 8.30324C24.8077 11.9329 22.8344 15.0998 19.9035 16.7957Z', fill: '#00A2DF' }, (2)
    },
    {
      id: 'icon-nav-component-ROOT', (3)
      viewBox: '0 0 14 15',
      paths: [
        { d: 'M1.36278 0L1.36787 3.94183L7.40742 3.95558L7.40236 0.0376971L8.73519 0.00265382L8.6981 5.27362L0 5.28486L0.0369378 0.0348597L1.36278 0Z', transform: 'translate(2.8598 6.64626)', fill: '#00A3E0' },
        { d: 'M6.00319 0L11.7143 4.23063V5.86337L5.97677 1.61317L0 5.5623L0.137638 3.91056L6.00319 0Z', transform: 'translate(1.198 1.32681) scale(0.999808) rotate(-1.50596)', fill: '#087299' }, (4)
      ],
    },
  ]
  var icondefs = Object.assign(document.createElement('div'), { id: 'icondefs', hidden: true })
  icondefs.appendChild(
    defs.reduce(function (parent, icondef) {
      var symbol = Object.assign(document.createElementNS('http://www.w3.org/2000/svg', 'symbol'), { id: icondef.id })
      symbol.setAttribute('viewBox', icondef.viewBox)
      var contents = icondef.contents || icondef.paths || [icondef.path]
      if (Array.isArray(contents)) {
        contents.forEach(function (props) {
          symbol.appendChild(
            Object.entries(props).reduce(function (tag, prop) {
              tag.setAttribute(prop[0], prop[1])
              return tag
            }, document.createElementNS('http://www.w3.org/2000/svg', 'path'))
          )
        })
      } else {
        symbol.innerHTML = contents
      }
      parent.appendChild(symbol)
      return parent
    }, document.createElementNS('http://www.w3.org/2000/svg', 'svg'))
  )
  document.body.appendChild(icondefs)
})()

Корневая навигационная группа, а также любой другой компонент, для которого не указана специальная иконка.
Иконка для корневой навигационной группы в формате SVG path.
Компонент с именем ROOT (name: ROOT) в файле antora.yml.
Иконка для компонента с именем ROOT в формате SVG path.

Если вы хотите управлять иконками, добавьте файл icondefs.js в свой проект пользовательского интерфейса в папку src/js/vendor/.

Также зарегистрируйте файл icondefs.js в шаблоне footer-scripts.hbs следующим образом:

footer-scripts.hbs

<script src="{{siteRootPath}}/site-navigation-data.js"></script>
<script src="{{uiRootPath}}/js/vendor/icondefs.js"></script>

Caution

Файл icondefs.js должен быть вторым в списке после site-navigation-data.js.

mojavelinux / antora-navigator-extension