A GitHub Action that builds AsciiDoc GitHub Pages in your CI workflow. It recursively converts every adoc
file to html
, renaming resulting README.html
to index.html
then pushing all generated html and existing files to the gh-pages
branch.
If you donโt need anything fancy like Antora, this action might be the way to go to publish a simple AsciiDoc website.
After configuring the action, your GitHub Pages will be available at http://your-username.github.io/your-repository
.
|
Keep in mind that every time the action is executed, the gh-pages branch is wiped out. If you manually add anything to it, outside of the CI workflow, the content will be lost.
|
We taste our own medicine by publishing this reposiroty in GitHub Pages.
You have to just add the action to your yml workflow file and that is it. You can optionally customize the build by giving extra parameters to the action, which will be handed to the asciidoctor tool.
You can check a complete workflow file here. If you donโt want to use the GitHub Action interface and just copy that file to the same place inside your repository, it may work out of the box.
The action allows enabling the automatic generation of an ebook.pdf
file from the AsciiDoc files. The pdf is pushed to the gh-pages
branch too.
To enable that, just add the following configuration:
pdf_build: true
A sample PDF ebook is available here.
You can also build AsciiDoctor Reveal.js slides with this action.
That will generate a slides.html file into the gh-pages
branch. You can use the following configuration for that:
-
slides_build: boolean
- enables building a slides.html file (default false) -
slides_main_adoc_file: string
- defines the name of the AsciiDoc source file to build the slides (default 'README'). Do not include the file extension. -
slides_skip_asciidoctor_build: boolean
- to enable skippig the build of regular html files using the asciidoctor command, if you just want to generate the slides (default false)
If you want to check how to create a website from multiple AsciiDoc documents, check this sample repository. Itโs only in Portuguese, but you can get the structure.
The action is simple, but to show how you can create a website with multiple pages from different AsciiDoc files,
the details are provided here in a separeted page.
And realize the link above points to a: (i) adoc
file when openning this page
from the GitHub repository and (ii) html
file when openning this page from the GitHub Pages.