mihaiginta / asciidoctor-ghpages-action

📄⚙️ GitHub Action to build AsciiDoc GitHub Pages: recursively converts every adoc file to html, renaming resulting README.html to index.html. It also enables generating an ebook.pdf or AsciiDoctor Reveal.js slides

AsciiDoctor GitHub Pages Action

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.

1. Live Demo

We taste our own medicine by publishing this reposiroty in GitHub Pages.

2. Configuration

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.

2.1. Building an e-book

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.

2.2. AsciiDoctor Reveal.js Slides

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)

3. Other examples

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.

4. How the action works

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.