Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/manoelcampos/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
https://github.com/manoelcampos/asciidoctor-ghpages-action

adoc asciidoc asciidoctor automation ci continuous-integration documentation gh-pages github-actions github-pages publishing website workflow

Last synced: 8 days ago
JSON representation

📄⚙️ 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

Awesome Lists containing this project

README 

        
:icons: font

:numbered:

:title: AsciiDoctor GitHub Pages Action

ifdef::env-github[:outfilesuffix: .adoc]



ifdef::env-github,env-browser[]

// Exibe ícones para os blocos como NOTE e IMPORTANT no GitHub

:caution-caption: :fire:

:important-caption: :exclamation:

:note-caption: :paperclip:

:tip-caption: :bulb:

:warning-caption: :warning:

endif::[]



ifdef::env-github[]

= {title} image:https://img.shields.io/github/actions/workflow/status/manoelcampos/asciidoctor-ghpages-action/asciidoctor-ghpages.yml[GitHub Pages Publish,link=http://manoelcampos.com/asciidoctor-ghpages-action/]

endif::[]



ifndef::env-github[]

= {title}

endif::[]



ifndef::backend-pdf[]

pass:[Buy Me A Coffee]

endif::[]



ifndef::env-github,env-browser[]

IMPORTANT: An always updated version of this document is https://github.com/manoelcampos/asciidoctor-ghpages-action/blob/gh-pages/ebook.pdf[available here] as a PDF e-book.

endif::[]



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 https://antora.org[Antora], this action might be the way to go to publish a simple AsciiDoc website.

But if you need a more structured website, maybe https://github.com/asciidoctor/jekyll-asciidoc-quickstart[Jekyll AsciiDoc QuickStart] is for you.



After configuring the action, your GitHub Pages will be available at `http://your-username.github.io/your-repository`.



WARNING: 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.



ifdef::env-github[]

== Live Demo



We taste our own medicine by publishing this repository to https://manoelcampos.github.io/asciidoctor-ghpages-action[GitHub Pages].

endif::[]



ifndef::env-github[]

== Project on GitHub



View the https://github.com/manoelcampos/asciidoctor-ghpages-action[project on GitHub] and take the chance to give it a star.

endif::[]



== 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 https://github.com/manoelcampos/asciidoctor-ghpages-action/blob/main/.github/workflows/asciidoctor-ghpages.yml[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.



=== Troubleshooting 



If you get the error "remote: Permission to git denied to github-actions[bot]",

access `Settings > Actions > General` and select `Read and write permissions`.



=== 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:



[source, yml]

----

pdf_build: true

----



ifdef::env-github,env-browser[]

A sample PDF ebook is https://github.com/manoelcampos/asciidoctor-ghpages-action/blob/gh-pages/ebook.pdf[available here].

endif::[]



=== AsciiDoctor Reveal.js Slides



You can also build https://github.com/asciidoctor/asciidoctor-reveal.js/[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)



== Other examples



If you want to check how to create a website from multiple AsciiDoc documents,

check this https://github.com/manoelcampos/asciidoc-github-template[sample repository].

It's only in Portuguese, but you can get the structure.



ifdef::backend-pdf[]

include::how-action-works.adoc[]

endif::[]



ifndef::backend-pdf[]

== How the action works



// The syntax below creates a link such as the link::[] command,

// but that point to the: (i) adoc file if we are in the GitHub web page

// or (ii) respective html page otherwise.



The action is simple, but to show how you can create a website with multiple pages from different AsciiDoc files,

the <>.

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. 



endif::[]



== FAQ



=== How can I configure a custom domain?



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`.