Antora Default UI

Данный репозиторий содержит файлы пользовательского интерфейса сайта help.docsvision.com, которые могут быть:

• Объединены в пакет, который используется для сайта документации.

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

Дизайн пользовательского интерфейса сайта help.docsvision.com был разработан на основе Antora Default UI.

Использовать интерфейс по умолчанию

Интерфейс по умолчанию можно посмотреть на сайте Antora.

Чтобы использовать данный интерфейс:

1. Найдите следующие строчки в файле antora-playbook.yml:

   ui:
     bundle:
       url: ./build/ui-bundle.zip

2. Замените их строчками ниже:

   ui:
     bundle:
       url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
       snapshot: true

Использовать интерфейс Docsvision

Пользовательский интерфейс сайта help.docsvision.com требуется упаковать, а затем сохранит в доступном месте. Пользовательский интерфейс по умолчанию не требует таких действий.

Если вы хотите видеть на собственном сайте тот же интерфейс, что и на help.docsvision.com, ознакомьтесь со следующими пунктами инструкции.

Инструкция

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

С более подробными инструкциями можно ознакомиться на сайте документации Antora: docs.antora.org.

Требования

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

• git (команда: git)

• Node.js (команды: node and npm)

• Gulp CLI (команда: gulp)

git

Убедитесь, что на вашем компьютере установлена программа git.

$ git --version

В противном случае скачайте и установите ПО git для вашей системы.

Node.js

Следующим шагом убедитесь, что у вас установлено ПО Node.js. Node.js также включает в себя ПО npm.

$ node --version

Если выполнение данной команды завершается ошибкой, на вашем компьютере не установлено ПО Node.js. Для работы с пользовательским интерфейсом подходит только Node.js версий LTS. В данном руководстве в качестве примера устанавливается Node.js 10.

Рекомендуется устанавливать Node.js не из официальных пакетов, а при помощи программы nvm (Node Version Manager), позволяющей управлять различными установленными версиями Node.js. Выполните инструкции, указанные по ссылке, чтобы установить nvm на ваш компьютер.

После установки nvm, откройте новое окно командной строки и установите Node.js 10 при помощи следующей команды:

$ nvm install 10

При помощи следующей команды можно переключиться к этой версии Node.js в любое время:

$ nvm use 10

Чтобы сделать Node.js 10 версией по умолчанию в новых сессиях командной строки, введите:

$ nvm alias default 10

Когда вы успешно установили Node.js, вы можете продолжить с установкой Gulp CLI.

Gulp CLI

Чтобы запустить сборку пользовательского интерфейса, вам понадобится программа для командной строки (CLI) Gulp. Пакет Gulp CLI предоставляет команду gulp, которая запускает версию Gulp, заявленную в проекте.

Gulp CLI можно установить глобально, на уровне всей файловой системы, следующей командой:

$ npm install -g gulp-cli

Убедитесь, что Gulp CLI установлен и доступен в качестве переменной среды PATH:

$ gulp --version

Если вы предпочитаете устанавливать глобальные пакеты с использованием Yarn, выполните следующую команду:

$ yarn global add gulp-cli

Также вы можете использовать команду gulp, установив её через зависимости проекта.

$ npx --offline gulp --version

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

Клонировать и инициализировать проект

Клонируйте проект пользовательского интерфейса сайта документации Docsvision, используя git:

$ git clone https://github.com/Docsvision/antora-ui-default.git &&
  cd "`basename $_`"

Команда из примера выше клонирует репозиторий с проектом пользовательского интерфейса сайта документации Docsvision, а затем переходит в папку проекта в файловой системе. Оставайтесь в папке проекта при выполнении всех последующих команд.

Используйте npm, чтобы установить зависимости внутри проекта. В командной строке выполните следующую команду:

$ npm install

Данная команда устанавливает зависимости, указанные в файле package.json в папку node_modules/ проекта. Данная папка не включается в пакет пользовательского интерфейса и должна быть исключена из репозитория системы контроля версий.

Tip	Если вы предпочитаете устанавливать пакеты при помощи Yarn, выполните следующую команду: $ yarn

Предварительный просмотр пользовательского интерфейса

Для проекта пользовательского интерфейса предусмотрена возможность предварительного просмотра без сети. Файлы в папке[.path]preview-src/ предоставляют организовать просмотр пользовательского интерфейса в действии. В этой папке вы найдёте в основном страницы, написанные в AsciiDoc. Эти страницы дают достоверный пример, соответствующий реальному сайту.

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

$ gulp preview

Вы увидите URL, указанный в выводе команды:

[12:00:00] Starting server...
[12:00:00] Server started http://localhost:5252
[12:00:00] Running server

Перейдите по указанному URL, чтобы просмотреть сайт локально.

Пока команда выполняется, любые изменения, вносимые в исходные файлы будут мгновенно отражены в браузере. Команда отслеживает изменения в проекте и запускает задачу preview:build, если изменения обнаружены, а затем отправляет обновления в браузер.

Нажмите Ctrl+C, чтобы остановить сервер предварительного просмотра и завершить непрерывную сборку.

Пакет для использования с Antora

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

$ gulp bundle

Если lint сообщает об ошибках, исправьте их.

Когда команда завершается успешно, пакет пользовательского интерфейса будет доступен по пути build/ui-bundle.zip. Направить Antora на данный пакет можно при помощи параметра команды командной строки --ui-bundle-url.

Например, так:

$ npx antora --fetch --ui-bundle-url antora-playbook.yml

Если у вас запущен предварительный просмотр, и вы хотите одновременно собрать пакет интерфейса, не испортив предварительный просмотр, используйте команду:

$ gulp bundle:pack

Пакет пользовательского интерфейса будет доступен по пути build/ui-bundle.zip.

Карты источников

Сборка объединяет все CSS и клиентские скрипты JavaScript в общие файлы site.css и site.js соответственно. Это делается с целью уменьшения размера пакета. Карты источников сопоставляют эти объединённые файлы с их исходными источниками.

Данное "картирование источников" достигается за счёт создания дополнительных файлов-карт, которые задают данную ассоциацию. Файлы карт располагаются рядом с объединёнными файлами в папке сборки. Картирование, обеспечиваемое данными файлами позволяет ПО для поиска ошибок указывать на оригинальный источник, а не на объединённый файл.

В режиме предварительного просмотра, карты источников автоматически включены, дополнительных действий для их использования от вас не требуется. Если вам требуется включить карты источников в пакет, вы можете это сделать, установив переменную среды SOURCEMAPS в значение true во время запуска команды:

$ SOURCEMAPS=true gulp bundle

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

Защита прав и лицензия

Copyright © 2017-н.в. OpenDevise Inc. и Antora Project.

Данное ПО предоставляется на условиях Mozilla Public License Version 2.0 (MPL-2.0).

Авторы

Разработка Antora производится и и спонсируется компанией OpenDevise Inc.