Nojekyll зачем

Неправильно отображается верстка на GitHub Pages

Добрый день подскажите пожалуйста, я сверстал страничку и залил ее на GitHub Pages. На локальном сервере все смотрится годно, однако на гитхабе все слетает непонятно как. Подскажите как решить проблему? Ссылка на страничку на GitHub Pages

Отслеживать
задан 23 дек 2017 в 9:23
53 6 6 бронзовых знаков

Проверьте все ли у вас подключено. Я имею ввиду фреймворки если такие имеются и т. д. jQuery судя по рабочему слайдеру подключен и работает.

– user262779
23 дек 2017 в 9:28

откройте консоль, там половина файлов не подключена,` _main.css` стоит заменить на просто main.css так же и все остальные файлы, проверить пути, имена файлов

23 дек 2017 в 9:29

Нужны ли вам все библиотеки в папке /libs ? Такое количество будет лишь замедлять работу. Там у многих дублирующиеся функции. Пересмотрите, может получиться оптимизировать как-то, что-то вообще убрать. Но это лишь мое мнение. У вас своя задумка. Просто обратите на это внимание.

Создаем свой персональный сайт на Github.

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

Введение

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

• Первое, что вам потребуется — это создать на Github репозиторий с именем вида: username.github.com , где username ваш логин на сервисе. Например для этого блога создан репозиторий http://github.com/klen/klen.github.com
• Вторым шагом мы создадим локальный репозиторий и привяжем его к удаленному:

В дальнейшем я буду приводить примеры для своего сайта: klen.github.com

mkdir ~/Projects/klen.github.com cd ~/Projects/klen.github.com git init echo 'Hello world!' > index.html git add . git commit -m 'Initial commit' git remote add origin git@github.com:klen/klen.github.com.git git push -u origin master

Отлично, ваш статический сайт уже готов! В течении 10 минут он появится по адресу: username.github.com . В дальнейшем он будет обновляться при коммитах в удаленный репозиторий.

Использование генераторов статических сайтов

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

Существует масса проектов генерации статических сайтов и блогов. При работе с ними фактически вы пишете страницы и статьи в удобном для вас формате, а затем генератор обновляет структуру сайта. По-умолчанию Github уже поддерживает написанный на ruby генератор Jekyll. То есть вам необязательно использовать только HTML синтаксис, из коробки вы можете писать в ваш сайт на Markdown. Подробнее читайте в документации Github Pages и Jekyll.

Я предпочитаю генерировать страницы локально и проверять результат без выгрузки содержания на Github. Мне привычнее работать с Python поэтому в качестве генератора сайта мной используется Pelican. Ниже я покажу как поставить его и настроить для работы.

Если вы предпочитаете ruby дальше можете не читать.

Установка и настройка Pelican

Предполагается, что вы знакомы с Python и VirtualEnv.

1. Так как мы будем использовать Pelican нам необходимо выключить встроенный в Github генератор Jekyll. Это делается добавлением в корень репозитория файла .nojekyll .

touch .nojekyll git add . git commit -m 'Disable Jekyll' 

1. Теперь создадим и активируем виртуальное окружение для модулей нашего сайта:

virtualenv .ve_blog source .ve_blog/bin/activate

1. Установим в созданный нами VirtualEnv генератор Pelican и необходимый для него движок шаблонов Jinja2:

easy_install pelican easy_install jinja2

1. Мы будем держать исходники сайта в поддиректории source, а созданные статические страницы в корне репозитория, чтобы Github их видел. Создадим файл source/hello.rst с нашей первой статьей:

Hello world! ############ :slug: hello Hello from Pelican!

Я использую синтаксис RST, но вы можете использовать Markdown для своего сайта. Просто сохраняйте файлы с расширением *.md Pelican поддерживает и другие форматы, но надо ставить соответствующие модули.

1. И соберем статику:

pelican source -o .

Опция -o . заставляет Pelican производить сборку статики в корне проекта.

Если все прошло успешно в корне проекта вы увидите несколько HTML файлов. Откройте index.html в браузере и посмотрите на ваш сайт.

1. Теперь наши изменения можно сохранить в Git и отправить на Github.

git add . git commit -m 'Add virtualenv and setup pelican.' git push origin master

Автоматизация

Настроим наш сайт и немного автоматизируем рутинные операции.

1. Создадим файл настроек нашего сайта source/settings.py :

AUTHOR = 'Kirill Klenov' SITENAME = 'klen.github.com' SITEURL = 'http://klen.github.com' 

Подробнее про настройки Pelican, можно прочитать в его документации.

1. Для упрощения сборки создадим sh-файл .compile

#!/bin/sh PRJ_DIR=/home/klen/Projects/klen.github.com VE_DIR=$PRJ_DIR/.ve_blog # Modify path OLD_PATH=$PATH PATH="$VE_DIR/bin:$PRJ_DIR:$PATH" export PATH # Compile static files pelican $PRJ_DIR/source -o $PRJ_DIR -s $PRJ_DIR/source/settings.py -v # Return PATH PATH=$OLD_PATH export PATH

И дадим ему права на исполнение:

chmod +x .compile

Теперь в директории проекта можно вызывать ./.compile и собирать статику даже без активации виртуального окружения.

1. Следующим шагом создадим Git хук для автоматической генерации сайта при коммитах. Создадим и отредактируем файл .git/hooks/pre-commit :

#!/bin/sh PRJ_DIR=/home/klen/Projects/klen.github.com $PRJ_DIR/.compile

Не забудьте сделать его исполнемым.

При каждом коммите изменений в репозиторий, проект будет пере-собран автоматически.

На этом нашу предварительную работу по созданию github-сайта можно считать оконченной. В дальнейшем стоит поподробнее прочитать документацию Pelican, модифицировать стандартную или создать собственную тему оформления и подключить какой нибудь сервис комментариев.

Sphinx-документация на GitHub Pages

GitHub Pages — это такая классная шизофреническая штука, которая может а)показывать созданную при помощи встроенного редактора страничку, б)генерировать Jekyll-блог и в)отображать html-файлы на произвольном домене.
В последнем образе она нас и интересует для размещения документации, написанной с использованием Sphinx.

Технически, в любом случае создаётся ветка gh-pages (за исключением), из которой отображается контент.
Итак, проект — это один репозиторий, документация к нему — другой, нет смысла смешивать их.
В master репозитория документации у нас хранятся исходники в формате ReStructuredText и конфигурационные файлы вместе с историей изменений. В gh-pages мало того, что история лишена смысла, так ещё и логически эта ветка существует параллельно master . Из таких предпосылок я исходил, создавая следующий скрипт.

#!/bin/sh shopt -s extglob dotglob CURR_DIR="$(pwd)" TMP_DIR="$CURR_DIR"-gh-pages sh build.sh rm -rf "$TMP_DIR" cp -r . "$TMP_DIR" cd "$TMP_DIR" git branch -D gh-pages git checkout --orphan gh-pages rm -rf !(.git|.gitignore) cp -r "$CURR_DIR"/_build/html/* . touch .nojekyll echo "droidparts.org" > CNAME git add -A git commit -m "published" git push origin :gh-pages git push origin gh-pages rm -rf "$TMP_DIR" 

1. Запускаем скрипт, собирающий документацию.
2. Копируем репозиторий во временную папку, переходим в неё.
3. Удаляем gh-pages , создаём её снова. Параметр —orphan отвечает за то, что ветка будет создана без родительского комита. Т.е. без привязки к master , что и требовалось. Также очищаем папку.
4. Копируем сгенерированные на первом шаге файлы.
5. Добавляем .nojekyll , чтобы GitHub Pages не подпускал Jekyll к папкам с подчёркиванием.
6. Создаём файл CNAME с доменом, с которого всё будет отдаваться. Естественно, также нужно настроить DNS.
7. Наконец, комитим, удаляем gh-pages с сервера, делаем push.

Новая документация Docsvision ч. 2 — Antora

Привет всем читающим! Меня зовут Владимир, я — технический писатель в компании Docsvision и я здесь, чтобы опубликовать вторую часть статьи и надрать задницу всем, кто ставил дизлайки к первой части. Статью вы можете найти ниже.

В первой статье я рассказал, как мы выбирали SSG для создания новой документации и как нам пришлось конвертировать DITA сначала в HTML, а потом в AsciiDoc.

В этой статье я расскажу, как я начал работать с SSG Antora, как я настраивал UI и добавлял сквозной поиск по сайту.

С чего начать работу с Antora?

С раздела на сайте документации Antora, который так и называется «с чего начать».

В статье я не буду подробно описывать то, как организовать файлы по папкам, в чём отличие playbook от component version descriptor и т.д. — это всё прекрасно описано в документации Antora. Опишу базовые шаги, необходимые для понимания работы:

1. Сперва нужно установить Antora. Проверить NODE LTS: node —version Установить Антору: npm i -g @antora/cli @antora/site-generator-default
2. Затем прочитать документацию. Лучше прочитать всю целиком, а не только Quick start guide, чтобы лучше понять Antora в целом.
3. Адрес сайта будет выглядеть следующим образом: url сайта — например, https://dv-docs.com; name of component — модуль, например, webclient; name of version — версия, например, 16 или 17 — указывается в antora.yml; name of module — тип руководства, например, user, admin, layouts; name of page — например, intro.

Структурирование файлов

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

Разные модули ДВ = разные компоненты анторы.

Разные руководства модулей ДВ = разные модули анторы.

Разные компоненты анторы версионируются и отображаются в отдельном меню.

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

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

Отсюда у нас два варианта: создавать каждое руководство в качестве отдельного компонента с одним-единственным модулем или смириться с общим содержанием и делать руководства по модулям.

Я остановил выбор на втором варианте.

Сначала мы переводим на новую документацию web-клиент. Следующая релизная версия web-клиента будет под номером 17, пока она в разработке, то есть в ветке develop.

Так и поступим. Исходники я организовал следующим образом:

Я решил сделать для документации каждого модуля ДВ свой репозиторий, а версии хранить в разных ветках.

Ветка Develop — ветка документации для ВК17.

antora.yml — файл, расположенный в корне каждой ветки. Для каждой новой ветки нужно будет создать свой уникальный antora.yml файл, указывающий на версию и её свойства.

> . В пути до файла antora.yml не должно быть посторонних символов, кроме латинских букв, цифр, короткого тире (-). Пробелы не разрешаются, решётки (#) тоже. Иначе ничего не будет собираться.

Таким образом обеспечиваются component versions, т.е. разбивка на версии.

В корне репозитория нужно создать папку modules (регистр важен).

В папке modules можно создать сколько угодно подпапок. Каждая папка — отдельный модуль antora. В нашем случае каждый модуль Antora — отдельное руководство пользователя, админа, конструктора разметок.

Для каждого модуля нужно создать свой файл навигации. Файл навигации представляет собой обычный многоуровневый список. Создавать содержание с нуля для больших руководств не очень хочется. К счастью, после конвертации получается файл index.adoc, он отлично подходит в качестве файла навигации. Но есть «но»:

• Имена папок в структуре Antora отличаются от сконвертированных. В пути до файла нужно убрать topics/ , но оставить всё, что после.
• Ссылки link: нужно заменить на xref: .
• Расширение html заменить на .adoc .

Переделки под Антору

По ходу конвертации и подстраивания документации под Антору выяснилось, что нужно переделать ещё многое.

По тексту добавить перекрёстные ссылки на другие модули и компоненты в формате:

Одинаковые страницы в модулях можно добавить в навигацию аналогичным образом: xref:version@component:module:filename.adoc[] . Но лучше делать include всей страницы полностью: include::version@component:module:filename.adoc . Иначе будут ситуации, например, когда пользователь смотрит документацию модуля web-клиент, а потом переходит по ссылке в навигации и внезапно попадает на документацию модуля Платформа. Пользователю потребуется время, чтобы осознать, где он и как вернуться назад.

Ещё одна важная мелочь — заголовки страниц. После конвертации все заголовки страниц второго уровня и дальше. Потребуется вычесть один уровень из каждого заголовка вручную. Есть, конечно, обходной путь — использовать :leveloffset: . :leveloffset: можно даже задать для компонентов, то есть в antora.yml файлах, но лучше всё же делать по-красоте сразу и без костылей.

Есть ещё блоки с исходным кодом. Они выделяются знаками равно после конвертации: ==== , такое надо заменить на —- .

Исходный код должен выглядеть так:

[source,yaml] ---- code here ---- 

Нужно будет ещё исправить путь до изображений — убрать img/ из img/image.png , иначе изображения не будут работать.

Если делать по-красоте, то хорошо бы переделать имена файлов с нижнего подчёркивания на дефис: a_file_name.adoc заменить на a-file-name.adoc .

Добавить kbd:[Ctrl+Shift+N] для клавиш и сочетаний клавиш.

Работы ещё много, но в итоге всё окупится.

Разбивка на версии (antora.yml)

Честно говоря, я боялся, что мне придётся изучать ещё и YAML во всех подробностях, но оказывается, что нет.

Оказывается, файлы antora.yml и playbook.yml сочиняются на YAML, очень просто. Процесс составления antora.yml описан в документации Antora.

Файл уникален для каждой ветки репозитория (main, WC17 и т.д.), лежит в корне репозитория, в каждой ветке.

Содержимое примерно такое:

name: webclient version: '16' title: Web Client 16 asciidoc: attributes: toclevels: 10 sectids: '' sectlinks: '' sectanchors: '' toc-title: Содержание figure-caption: Рисунок appendix-caption: Приложение wc: WebClient dv: Docsvision nav: - modules/user/nav.adoc - modules/admin/nav.adoc start_page: user:Capabilities.adoc 

Порядок ключей не имеет значения.

Playbook

Процесс составления описывается в документации Antora. Я ожидал больших сложностей. Но всё оставались вопросы, которые мне были не совсем очевидны. Но сейчас я уверенно могу на них ответить:

• Куда сохранять книгу?
  • Рекомендуется держать под книгу отдельный репозиторий.
  • Можно запустить сайт на локальном сервере в тестовых целях. Можно просто посмотреть страницы сайта в офлайне. С доменом уже потом разбираться будут специально обученные люди.

  keys: google_analytics: XX-123456 

  • Специально обученные люди разберутся.
  • Специально обученные люди разберутся. Нужно уметь разделять обязанности и не взваливать лишнее на себя.
  • В UI, там будет понятно.
  • Всё делается в UI bundle. Он легко кастомизируется, после чего его надо упаковать и добавить в playbook вот так:

   ui: bundle: url: /home/user/projects/docs-ui/build/ui-bundle.zip 

  Готовый файл playbook выглядит примерно вот так:

  site: title: Docsvision Docs url: https://docsvision.github.io/docs-playbook/ start_page: webclient:user:welcome.adoc robots: allow content: sources: - url: https://github.com/Docsvision/docstest.git branches: [main, WC*] ui: bundle: url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable snapshot: true asciidoc: attributes: toclevels: 10 sectids: '' sectlinks: '' sectanchors: '' toc-title: Содержание icons: font figure-caption: Рисунок appendix-caption: Приложение wc: WebClient dv: Docsvision urls: html_extension_style: indexify output: dir: ./site runtime: fetch: true 

  Порядок ключей не имеет значения. Подробное описание ключей читайте в документации Antora.

  Сборка сайта

  

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

  • Созданы исходники в формате .adoc, включая навигацию (можно и без навигации, но зачем?).
  • Создан файл с описанием версий компонента.
  • Создан playbook.

  Убедившись, что все требования выполнены, достаточно просто натравить Антору на файл playbook вот так: antora the-playbook.yml .

  После выполнения команды Антора получит информацию из указанных источников:

  content: sources: - url: https://github.com/Docsvision/docstest.git //где хранятся исходники branches: [main, WC*] //какие ветки обрабатывать 

  И опубликует их по адресу, указанному вот тут:

  site: url: https://docsvision.github.io/docs-playbook/ 

  Если есть какие-то ошибки в исходниках, Антора выведет их прямо в консоли. Также нужно помнить, что по умолчанию Антора кэширует UI. Чтобы такого не было, нужно ставить snapshot: true :

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

  А ещё Антора кэширует исходники. Чтобы потом не было так: «Но как же! Я же исправлял эту ошибку! В чём дело? Что ещё нужно исправить?». Делайте вот так:

  runtime: fetch: true 

  Сайт готов. Остаётся только сделать commit/push.

  А также при желании:

  • изменить текст страницы 404
  • изменить текст ссылки «Edit this page»

  Об этом чуть ниже, через три небольших пункта.

  GitHub Pages

  GitHub Pages работают с Jekyll, который удаляет все файлы и папки, начинающиеся с _ . Антора в этой папке хранит весь UI. То есть по умолчанию весь UI будет удалён этим самым Jekyll. Решение простое, нужно только добавить в корень репозитория сайта файл .nojekyll .

  Я поместил всю документацию в корень репозитория тоже на всякий случай. Иначе у меня сайт не хотел заводиться. Но так даже лучше, потому что адрес вышел короче.

  .html to .adoc

  При изначальной конвертации из dita в html в adoc остались html артефакты. Например, любая перекрёстная ссылка превращалась в link:ololo.html[trololo] . IntelliJ нормально съедала такие ссылки и не ругалась, нормально делала превью и т.д. Но после создания сайта через Antora все ссылки ломались.

  Требовалась замена всех таких ссылок на правильные: xref:ololo.adoc[trololo] . Проблема легко решается заменой всех .html на .adoc, например через ту же IntelliJ.

  Из HTML в AsciiDoc подчёркивание конвертируется как +++по дате создания+++ . Если очень нужно подчёркивание, то должно быть [.underline]#по дате создания# . Если подчёркивание не нужно, то такие артефакты можно удалить или использовать какой-то другой формат.

  Пустая строка перед началом документа

  Ещё один нюанс — это пустая строка перед началом документа .adoc. На месте этой строки был какой-то ID, который присваивался всем страницам. То есть однинаковый ID [[ariaid-title1]] для каждой страницы. Asciidoc ругался ещё из IntelliJ плагина, поэтому я удалил этот ID. Образовалась пустая строка в начале каждой страницы. Их можно смело удалять, если вы конвертировали из .html в UTF без BOM.

  Настроить UI

  Сайт собран, остаётся только настроить UI. Все артефакты, что остались на английском, дополнительные ссылки в разворачивающихся меню, изменить стиль страниц и т.д. Стиль CSS обработан при помощи PostCSS. Чистый CSS, без предпроцессоров, а только с пост-обработкой.

  Настройка UI описана в документации Antora. UI настривается очень просто, инструкция очень понятная. Я сам переделал UI на русский за пару часов.

  Клонируем репозиторий, лезем в папку src\partials\ , а там уже лежат файлы .hbs. Открываем, видим код вперемешку с английским и человекочитаемыми фразами, переводим. Скрипты и стили можно найти выше уровнем, в папках src\js и src\css соответственно.

  Завершили редактирование, собрали UI командой gulp bundle .

  Если нужно навертеть ещё что-нибудь, что не предусмотрено стандартным UI, можно нацепить усы и почитать документацию для handlebars

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

  Настройка поиска Algolia

  

  Самый очевидный вариант — Algolia Docsearch. Это бесплатный поиск, который можно поднять, написав запрос в Algolia вот тут , или развернуть поиск вручную по инструкции.

  Чтобы подать заявку на подключение к crawler\scraper от Algolia, чтобы они сами сделали все настройки поиска, нужно отвечать требованиям:

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

  Если требования не удовлетворяются, то можно попробовать настроить поиск самостоятельно по инструкции. Но сложность в том, что официальная инструкция Algolia написана без учёта развёртывания сайта через Antora, поэтому немного не такая, как надо.

  Правильную инструкцию я нашёл случайно на GitLab Antora. Следуя этой инструкции, можно настроить индексирование контента. Однако, если нужен не пробник, а работающий поиск и на своём сайте, необходимо заменить репозиторий на свой, а также отдельно скопировать файл config.json отсюда и изменить его в соответствии со своим сайтом. Главное, грамотно изменять, чтобы json остался целым, иначе ничего не получится. Также потребуется аккаунт Algolia, который просто так даётся только на пробный период. Ну, либо я что-то не догнал.

  Я попробовал настроить индексирование контента самостоятельно и вот, что я выяснил:

  • Если настраивать из-под Linux, то проблем не будет совсем.
  • Если настраивать из-под Windows, придётся немного потанцевать с бубном (ну, либо я ничего не умею).

  На сайте поиск сам по себе не появится, поэтому его нужно как-то добавить на страницы. Здесь инструкций нет вообще. Единственное, что отдалённо можно назвать инструкцией — вот эта страница в документации Algolia. Один кусок кода нужно встроить перед закрывающим , а вторую часть перед закрывающим . Но есть тонкости:

  1. Stylesheet для поиска доступен по ссылке https://cdn.jsdelivr.net/npm/docsearch.js@>/dist/cdn/docsearch.min.css . Естественно, > нужно заменить на точную версию. Но, во-первых: где узнать эту точную версию? И, во-вторых: что будет, когда версия обновится? Я нашёл последнюю версию простым подбором, это оказалась версия 2.6. Хотелось бы иметь ссылку на последнюю версию, но я не знаю, как и где её получить. Возможно, я просто что-то упускаю из виду.
  2. Во второй части кода нужно не забыть раскомментировать часть //appId: » , потому что поиск мы запускаем самостоятельно. После этого заполнить всё данными из личного кабинета Algolia, а также добавить CSS Selector. С этим селектором они такие классные — ни слова о том, что это и, где искать. Кое-как нашёл информациюна форуме, что на самом деле, блин, всё просто. Но даже там сказано «любой front-end разработчик знает, что это такое». Ага, но я-то не front-end разработчик. Не каждый, кто настраивает поиск — разработчик. Впрочем, всё оказалось ещё проще, чем сказано на форуме — CSS селектор — это просто ID или HTML-элемент в позиции по отношении к другим (например, body > header > nav > div.navbar-brand > a ). С ID я хорошо знаком, но вот термин «селектор» для меня был новый. Блин.
  3. Затем самое интересное — вставить поисковую строку в UI сайта. Берём репозиторий Antora UI, находим .hbs-файлы и добавляем в них куски вот с этой страницы. Для удобства я создал два отдельных .hbs-файла, с двумя частями кода. Один файл назвал search-head.hbs , другой search-body.hbs . search-head.hbs я добавил последним в файл head.hbs из папки partials , а search-body.hbs я добавил в файл default.hbs в папке layouts . Как? По аналогии с другими включениями: >
  4. После всех операций, нужно построить UI. Он собрался без ошибок с первого раза, что очень порадовало меня. Затем я натравил Антору на playbook — она мне сделала сайт с поиском. Какой я молодец! Теперь можно заняться стилизацией поиска. Если вы настраиваете стили поиска самостоятельно, Algolia даже разрешает вам убрать логотип Algolia из поиска. Какая великая щедрость!
  5. На этом месте поиск отвалился. Пробный период закончился и всё сломалось. Такой расклад меня совсем не радует.

  Если вы задумываетесь о более глубокой настройке поиска, которая позволяла бы выбирать определённый компонент, версию компонента и т.д., то мы мыслим похоже. Я тоже задумывался об этом, но реализация оказалась не такой простой. Поиск с выбором области поиска используется на сайте docs.couchbase или docs.asciidoctor

  И тот, и другой сайт созданы самим создателем AsciiDoc, исходники открыты, подробности можно узнать, например здесь: antora.zulipchat

  А что если попробовать Elasticsearch?

  

  В том же чате Antora кто-то говорил, что давно подключил полнотекстовый Elasticsearch к Анторе и пользуется им. Подключали решение Fess Site Search. По их собственным заявлениям Fess Site Search является заменой больше не поддерживаемому Google Site Search.

  Я подумал, что, раз я такой успешный и справился с Algolia, то грех не попробовать и Elastic.

  Устанавливаем Fess Site Search + Elastic Search

  Делюсь алгоритмом действий, если кто-то захочет повторить:

  • Проверяем: установлена ли Java, если нет — ставим.
  • Ставим Elastic, скачав .deb по ссылке: https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.13.2-amd64.deb,
  • Не запускаем, просто ставим.
  • Потом ставим плагины для него:

   sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install org.codelibs:elasticsearch-analysis-fess:7.13.0 sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install org.codelibs:elasticsearch-analysis-extension:7.13.0 sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install org.codelibs:elasticsearch-minhash:7.13.0 

  • Опять же, ничего не запускаем, не перезагружаем,
  • Ставим elastic-configsync: Скачиваем по ссылке, выполняем команды:

   sudo mkdir -p /usr/share/elasticsearch/modules/configsync sudo unzip -d /usr/share/elasticsearch/modules/configsync Downloads/elasticsearch-configsync-7.13.0.zip 

  • Открываем /etc/elasticsearch/elasticsearch.yml , добавляем строчку:

   configsync.config_path: /var/lib/elasticsearch/config 

  • Скачиваем Fess по ссылке,
  • Ставим его.
  • Добавляем Fess и Elastic как сервисы:

   sudo /bin/systemctl daemon-reload sudo /bin/systemctl enable elasticsearch.service sudo /bin/systemctl enable fess.service 

  • Запускаем:

   sudo systemctl start elasticsearch.service sudo systemctl start fess.service 

  • Fess доступен по адресу http://localhost:8080/ , админская панель по адресу http://localhost:8080/admin/ , по умолчанию данные для входа (логин/пароль): admin/admin .
  • Можно переходить к администрированию. Правда перед администрированием лучше назначить для Elastic Search какое-нибудь неприлично больше количество оперативки в зависимости от ваших потребностей. Вы спросите «но какое же?», а я отвечу: «хрен знает, нигде не сказано». Искал в интернете, обыскался. на нашей виртуалке Ubunbtu процесс Elastic Search перестал отваливаться при 8 гигах оперативки. Когда потребности увеличатся (с увеличением количества пользователей и поисковых запросов), возможно, потребуется больше.

  Но как же добавить этот поиск в UI? Для этой цели имеются крупицы информации тут и ещё тут.

  Добавляем Fess Site Search в UI сайта

  Сначала генерируем скрипт, кастомизируем его внешний вид (при необходимости), добавляем в .hbs с правильным адресом. Добавляем в .hbs туда, где хотим видеть поисковую строку. Например, в шапку сайта — header-content.hbs .

  Создаём в playbook страницу поиска способом аналогичным созданию файла .nojekyll.

  Придётся написать полный html-код страницы search.html в playbook. На странице указать правильные пути к скрипту и к сайту. Проверить, что в Playbook указан правильно ключ url: с корректным адресом сайта. Также на корректность нужно проверить путь до скрипта. Нужно учитывать, что страница поиска располагается в корне сайта и путь тоже должен быть относительно корня сайта.

  Добавить на страницу поиска в удобное место тэг скрипта:

  Очень важно указать в URL of FSS JS to src путь до автоматически сгенерированного скрипта на сайте. Например, http://127.0.0.1:5000/_/js/vendor/fess-ss.min.js . В URL of Fess search API to fess-url указать адрес Fess сервера. Именно сервера, а не сайта. Например, если сайт развёрнут на том же сервере, что и fess, это будет выглядеть вот так: http://localhost:8080/json . Указать адрес интерфейса Fess и не забыть в конце /json . Если это будет сервер доступный всем в интернете, настройки понадобится изменить соответственно. Ещё желательно будет настроить https. Вот пускай разработчики и занимаются этим, я мало что понимаю в этом.

  И тогда у вас на сайте будет работать поиск Elastic Search, точнее fess Site Search. Ну, вы поняли.

  Lunr — ещё один поиск

  

  Можно добавить ещё третий поиск — Lunr. Добавить его проще всего, он уже интегрирован в Антору, но только в другую. Antora with Lunr уже имеет в себе поиск, её нужно только поставить и натравить на playbook.

  • PDF эта Антора делать не умеет, а нам очень нужна эта функция.

  С тех пор как я выполнял настройку поиска, прошло несколько месяцев. В Анторе появились расширения, позволяющие подключать различные функции прямо из playbook. Теперь можно одновременно подключить и PDF (об этом ниже), и Lunr.

  HTML lang

  Ещё один нюанс настройки UI — язык html-страниц сайта. Сначала я думал, что его нельзя менять, но оказалось, что можно сделать это в файле src\layouts\default.hbs .

  Pagination

  Антора позволяет сделать ссылочки на следующую/предыдущую страницу. Но эта фича хитро спрятана! В playbook, component version или на странице надо добавить специальный атрибут page-pagination: » , тогда будет пагинация.

  Для пагинации нужна как минимум одна свободная строка в конце документа!

  Проблемки

  Небольшой упс с breadcrumbs, когда страница становится узкой, а название длинное.

  

  Финальные штрихи и доработки

  Ручная доработка AsciiDoc

  Есть ещё несколько доработок, которые необходимо выполнить после конвертации. Отличие этих доработок от всех предыдущих в том, что их необходимо выполнять вручную.

  По сути — это обычная вычитка документа:

  

  • Потребуется найти ещё ошибки, например, с блоками-примерами исходного кода. Они конвертируются неправильно.
  • В прошлой части я говорил про вот такое: [.ph .menucascade]#[.ph .uicontrol]#Документ# > [.ph .uicontrol]#Документ УД# > [.ph .uicontrol]#Акт## И про то, что в идеале это бы надо заменить на menu:Документ[Документ УД > Акт] . Я решил делать по красоте и переделать все подобные случаи и даже найти новые.
  • Переделать примечания, убрав Прим.: и Важное замечание: . Прим.: можно просто убрать, а Важное замечание: заменить на IMPORTANT вместо NOTE . Если при импорте из DITA в топиках не уделялось внимание такой несущественной мелочи, как язык документа, то работа осложняется ещё тем, что вместо Прим.: и Важное замечание: могут быть Note: Important notice и всякое такое. И вообще, AsciiDoc Предлагает широкую палитру примечаний. Грех — не использовать доступные возможности. Нужно вручную перелопатить все примечания, отредактировать и поменять их тип.
  • Избавиться от пустых страниц только со ссылками, заменив их заголовками.
  • Переименовать файлы топиков, чтобы все были через нижнее подчёркивание или все были через тире, или все были через camelCase.
  • Избавиться от :leveloffset: и лучше его не использовать.

  В силах технического писателя подумать над некоторыми из пунктов: подчёркивания, кастомные роли, переделать используемые примечания, добавлять ли новые, лишние страницы, пробелы, содержание, формулировки, [.ph]/[.cmd]. В идеале надо продумать style guide и придерживаться его при написании документации. «То-то будет расчудесно!»

  Что ещё?

  • Подумать про мультиязычность.
    • Однажды будет реализована нативными средствами анторы — issue 208, issue 377. Если у нас необходимость возникнет раньше, можно держать как отдельный компонент, например. Или как отдельный сайт.

    PDF

    Если вас по каким-то причинам не устраивает использовать расширение для создания pdf, можно использовать альтернативные методы:

    1. Нативный конвертер AsciiDoctor. Для работы этого метода нужно будет установить дополнительные компоненты, а потом использовать только команду asciidoctor-pdf basic-example.adoc . Можно генерировать как один исходный файл = один результирующий pdf или много исходных = одно большое руководство. Но сложность в том, что потребуется переделать файл содержания. Буквально из левого файла получить правый: Левый – это обычный рабочий файл, который создаёт многоуровневое меню страницы. Правый файл собирает каждую строку в один большой документ. Количество звёздочек в правом файле соответствует цифре после :leveloffset: . Перед следующим уровнем содержания, нужно ещё раз добавить :leveloffset : (закрывающий). Алгоритм логичный и вроде бы несложный, но этот процесс хорошо бы автоматизировать, чтобы каждый раз вручную не переделывать. Нужно, чтобы левый документ конвертировался в правый. По команде или ещё как-то.
    2. А ещё можно использовать конвертер в Web PDF прямо из IDE. Щадящий PDF конвертер. Но это экспериментальная функция, её нужно включить специально.
    3. Ещё один вариант — это использовать Asciidoctor Web PDF. Потребует установки или распаковки, но может быть использован для создания PDF.
    4. Четвёртый вариант — кастомная версия Анторы. Использует Asciidoctor PDF. На момент написания — это ещё экспериментальная функция, но она должна стать расширением Анторы версии 3.0, за изменениями в реальном времени можно следить тут.

    Доработки UI

    • Поля шире
    • Вместо note, tip, warning должны быть просто иконки, возможно с фирменными цветами.
    • Определиться, что использовать: якоря или полностью ссылка-заголовок.
    • Жирный 700.
    • Курсив более курсивный.
    • Мне не совсем нравится курсив в моноширинном. Возможно, стоит использовать другой шрифт.
    • Fallback font
    • Добавить диаграммы и схемы.
    • Javadoc
    • Кнопка домой при наведении, её бы заCSSить, чтобы лучше работала.
    • div > (заголовки списков и изображений) выделить как-то получше?
    • Создать красивую стартовую страницу сайта.
    • Переделать стили под корпоративные.
    • Автоматизировать сборку (уже сделано, через TeamCity. Если интересно, ткну нашего DevOps, попрошу поделиться опытом).
    • Окончательно определиться с поиском и доработать его.
    • Избавиться от [.ph], [.cmd], за которыми ничего не следует.
    • Насчёт других кастомных ролей. Гипотетически, их можно использовать, чтобы придать стиль элементам. Но 1) каждый раз их вводить не очень удобно 2) их слишком много. Например, есть keyword, а есть uicontrol и то и то жирное с font weight 700. Какая разница? Или parmname и term — и то и другое курсивом. Зачем тогда два варианта? Мы решили не использовать. Но, если решитесь повторить, вам нужно будет подумать и решить, использовать ли их и, если да, то в каком количестве. И решить, кто будет решать.
    • Убрать убогое Parent topic: , а вместе с ним и На уровень выше: . Есть же прекрасная пагинация!
    • Найти способ получать ошибки из консоли при автоматической сборке (тоже сделано, тоже могу ткнуть коллегу, если интересно).
    • Добавить трекеры на сайт, чтобы знать, как читают документацию, что вызывает затруднения и прочую статистику.

    Заключение

    

    Картинка тюремного заключения в заключении, как ловко придумано, да?

    Писать документацию в AsciiDoc гораздо проще и приятнее, чем в DITA. При том, что функциональность этих двух языков сопоставима, многие вещи реализованы в AsciiDoc гораздо более дружелюбно. Чтобы создать ключ в DITA, нужно немного постараться — в AsciiDoc достаточно обозвать его как-нибудь и использовать повсюду, только называется это атрибут.

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

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

    В общем, я благодарен Docsvision за возможность работать в смелой компании и коллегам за то, что они всегда поддержат. Кстати, мы нанимаем в СПб и Орле. Смотрите также вакансии нашей группы компаний.

    Похожие публикации:

    1. Gitlab как скачать файл
    2. Как выйти из nano
    3. Как понять что пора менять работу
    4. Сколько выходных слоев может присутствовать в нейросети