asciidoctor ghpages action

Asciidoctor GitHub страницы действия

Действие GitHub, которое строит страницы GitHub Asciidoc в вашем рабочем процессе CI. Он рекурсивно преобразует каждый файл adoc в html , переименуя, в результате чего README.html в index.html затем нажимает все сгенерированные HTML и существующие файлы в ветвь gh-pages . Если вам не нужно ничего необычного, такого как Antora, это действие может быть способом опубликовать простой веб -сайт Asciidoc. Но если вам нужен более структурированный веб -сайт, возможно, Jekyll Asciidoc Quickstart для вас.

После настройки действия ваши страницы GitHub будут доступны по адресу http://your-username.github.io/your-repository .

️	Имейте в виду, что каждый раз, когда действие выполняется, филиал gh-pages уничтожена. Если вы вручную добавите в это что -нибудь, за пределами рабочего процесса CI, контент будет потерян.

1. Живая демонстрация

Мы пробуем наше собственное лекарство, публикуя это хранилище на страницы GitHub.

2. Конфигурация

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

Вы можете проверить полный файл рабочего процесса здесь. Если вы не хотите использовать интерфейс Action GitHub и просто копировать этот файл в одно и то же место в вашем репозитории, он может работать из коробки.

2.1. Поиск неисправностей

Если вы получите ошибку «Удаленное: разрешение на GIT отказано в GitHub-Actions [BOT]», Settings > Actions > General и выберите Read and write permissions .

2.2. Строительство электронной книги

Действие позволяет обеспечить автоматическую генерацию файла ebook.pdf из файлов asciidoc. PDF также подтолкнут к филиалу gh-pages . Чтобы включить это, просто добавьте следующую конфигурацию:

 pdf_build : true

Образец PDF -электронная книга доступна здесь.

2.3. Asciidoctor выявляется. JS Slides

Вы также можете построить Asciidoctor Specuit.js слайды с этим действием. Это генерирует файл Slides.html в ветвь gh-pages . Вы можете использовать следующую конфигурацию для этого:

• slides_build: boolean - позволяет создавать файл SLIDES.HTML (по умолчанию false)

• slides_main_adoc_file: string - определяет имя исходного файла Asciidoc для создания слайдов (по умолчанию 'readme'). Не включайте расширение файла.

• slides_skip_asciidoctor_build: boolean - чтобы включить скиппиг на сборку обычных файлов HTML, используя команду Asciidoctor, если вы просто хотите генерировать слайды (по умолчанию false)

3. Другие примеры

Если вы хотите проверить, как создать веб -сайт из нескольких документов Asciidoc, проверьте этот пример репозитория. Это только на португальском языке, но вы можете получить структуру.

4. Как работает действие

Действие простое, но чтобы показать, как вы можете создать веб -сайт с несколькими страницами из разных файлов Asciidoc, данные предоставляются здесь на отдельной странице. И осознайте ссылку выше указывает на: (i) файл adoc при открытии этой страницы из репозитория GitHub и (ii) html -файла при открытии этой страницы со страниц GitHub.

5. FAQ

5.1. Как я могу настроить пользовательский домен?

Страницы GitHub нуждаются в файле CNAME в филиале gh-pages . Но при каждом действии, филиал gh-pages уничтожена. Чтобы сделать пользовательскую работу домена, просто добавьте файл CNAME в корневую каталог вашего main или master ветви, и он будет автоматически скопирован в филиал gh-pages . Если у вас настроен source_dir , файл CNAME должен находиться внутри вашего настроенного source_dir .