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.
But if you need a more structured website, maybe Jekyll AsciiDoc QuickStart is for you.
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 repository to 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.
If you get the error "remote: Permission to git denied to github-actions[bot]",
access Settings > Actions > General
and select Read and write permissions
.
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.
GitHub Pages need a CNAME
file on the gh-pages
branch. But on every action run, the gh-pages
branch is wiped out. To make a custom domain work, just add the CNAME
file in the root directory of your main
or master
branch instead and it will be copied over to the gh-pages
branch automatically. If you have a source_dir
configured, the CNAME
file must be inside your configured source_dir
.