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

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

1. Live Demo

We taste our own medicine by publishing this repository to 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. 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.

2.2. 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.3. 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.

5. FAQ

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

asciidoctor-ghpages-action's Issues

Introduce input parameter to enable building PDF

The parameter will enable building the adoc files to a PDF ebook, besides the HTML files.

The asciidoctor-pdf can be installed with:

gem install asciidoctor-pdf

The asciidoctor-pdf should be installed only if the option is enabled.

Introduce input parameter to enable building Reveal.js Slides

Slides should be built using AsciiDoctor Reveal.js.
The user should define if he/she wants to build the just the Reveal.js slides or the regular html files too (using the html backend). This can be done by setting another parameter, which by default, should build both.
The slides entry files should be README.adoc by default, but the user may change that.

The asciidoctor-revealjs can be installed with:

gem install asciidoctor-revealjs

The asciidoctor-revealjs should be installed only if the option is enabled.

Related Issues

• #1

Feature Request: Any chance we could add asciibuild?

asciibuild seems like a really good option if one wants to do literate programming, I suspect that in order to add it to this action the easiest thing would be to ask asciidoctor/docker-asciidoctor to include it in their dockfile?

Here is asciibuild's dockfile from the building instructions

FROM alpine
RUN apk add --no-cache bash make build-base ruby ruby-rdoc ruby-irb ruby-bundler ruby-dev py-pip docker
RUN pip install pygments

RUN mkdir -p {{workdir}}
COPY . {{workdir}}/
WORKDIR {{workdir}}
RUN bundle install
RUN gem build asciibuild.gemspec
RUN gem install ./asciibuild-*.gem -l
RUN rm -Rf {{workdir}}
RUN apk del build-base make ruby-dev

VOLUME /usr/src
WORKDIR /usr/src

ENTRYPOINT ["asciibuild"]

One issue I could see arising is that in order to execute the pieces of code in a literate programming document is that environment needs to have installed that programming language, and so there would need to be a way to configure the docker image so that it includes the programming languages that are used by the literate programming document.

Passing --signoff flag through to git commit.

Hello, our project is using your action to publish the our documentation, so first off, thank you for the action.

We'd like to adopt DCO our project with automated enforcement (https://probot.github.io/apps/dco/).

I notice that the git commit used by asciidoctor-ghpages-action doesn't pass the --signoff flag, I'm expecting the action to break once the switch is thrown.

Would you be open to PR that allows --signoff to be enabled?

Introduce input parameter to define asciidoc files extension

Currently, the action just considers that files have .adoc extension.
Introduce an input parameter to define the extension to use.
The default value should be .adoc.

Enable running arbitrary shell command after build

A new optional parameter should be included to enable the user to perform any post-processing task after the asciidoc build is completed. That parameter will accept an arbitrary shell command to be executed before the changes are committed to the gh-pages branch.

Support for repositories with git LFS

The current "[email protected]" fails with following error in case it is applied to repository with git LFS enabled:

  Checking out the gh-pages branch (keeping its history) from commit ...
  git-lfs filter-process: line 0: git-lfs: not found
  fatal: the remote end hung up unexpectedly

The issue is that the base alpine docker image doesn't installs the git-lfs, so it is not available.

Proposals:

• Option 1: add something like following into the Dockerfile

  RUN apk add --no-cache \
          git-lfs

• Option 2: add the git-lfs install into the entrypoint.sh

  # Install git-lfs since it is not in alpine base image.
  echo "Install git LFS"
  apk update
  apk add --update git-lfs

Enable running arbitrary shell command before build

A new optional pre_build parameter should be included to enable the user to execute any arbitrary shell command (such as packages installation and environment setup), after checking out the latest commit to gh-pages branch and before the asciidoc build is started.

Unable to post-process HTML produced by AsciiDoctor

I've got a table that needs to be wider than the hard width limit imposed by the AsciiDoctor conversion, so I've added a post_build command to update the HTML file, but it doesn't work (I've tried it locally, so I know the command is fine). I still have to manually edit the HTML file on the gh-pages branch.

Is there something else that I need to add?

Action fails if source dir is set

Hey there,

since the last update, our company is experiencing issues when running the action.
It seems line 40 of entrypoint.sh (the find command) returns a non-zero exit code if there are folders with subdirectories to delete, as the parent folder might be deleted first and subsequent calls to remove the child directories cause errors.
This would not really be a problem as the deletion succeeds de facto, but the non-zero exit code of find results in a termination of the action. This might be, because -e is set.

The Problem could be countered by using

find . -not -path './.git*' -not -name '.' -exec rm -rf {} \; || true

instead

Best regards

🧩 Introduce input parameter to enable building epub and mobi e-book files

The parameter will enable building the adoc files to epub/mobi, besides the HTML files.

Related Issues

• #1

Parse AsciiDoc files with any extension by default, following a Convention over Configuration approach

If the adoc_file_ext param is not provided, the action should build all AsciiDoc files
using find . -name "*.adoc" -or -name "*.ascii" -or -name "*.asciidoc".

If the param is given, build just files with provided extension.
The param must not have a default value anymore.

asciidoctor-chart and gnuplot support

I would like to use https://github.com/asciidoctor/asciidoctor-chart or gnuplot to draw charts. Could you please clarify how to make them work?

I've tried it with the config:

name: GitHub Pages Publish

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: write
  pages: write
  id-token: write

  # Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  build_and_deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v3

      - name: install rouge
        run: sudo apt-get install -y ruby-rouge

      - name: install gnuplot
        run: sudo apt-get install -y gnuplot

      - name: install asciidoctor-chart
        run: sudo gem install asciidoctor-chart --pre

      # Includes the AsciiDoctor GitHub Pages Action to convert adoc files to html and publish to gh-pages branch
      - name: asciidoctor-ghpages
        uses: manoelcampos/[email protected]
        with:
          pdf_build: true
          asciidoctor_params: -r asciidoctor-diagram --attribute=nofooter
          # adoc_file_ext: .ascii # default is .adoc
          # source_dir: docs/ # default is .
          # slides_build: true
          # pre_build:
          # post_build:
      - name: Setup Pages
        uses: actions/configure-pages@v2
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # Upload entire repository
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

but it throw the error:
Could not find the 'gnuplot' executable in PATH; add it to the PATH or specify its location using the 'gnuplot' document attribute
Then I made asciidoctor_params: -r asciidoctor-diagram --attribute=nofooter a gnuplot=/usr/bin/gnuplot but it throws the same error.
So I made asciidoctor_params: -r asciidoctor-diagram -r asciidoctor-chart --attribute=nofooter -a gnuplot=/usr/bin/gnuplot but it throws asciidoctor: FAILED: 'asciidoctor-chart' could not be loaded error

Publishing only single HTML file to gh-pages

I'm using your action in my project: https://github.com/Gamadril/lightoros/blob/master/.github/workflows/doc_publisher.yml but I'm not sure if I'm doing it right.
When I check the gh-pages branch: https://github.com/Gamadril/lightoros/tree/gh-pages I see the content of the master branch, but with generated HTML doc in the doc folder. But actually what I would like to see there is only one single index.html file and nothing else. Is it possible to achieve that behaviour with your action?

Support publish_dir support for publishing a subdirectory to ghpages

gh-pages support a publish_dir parameter which is not available for this action, please provide support for that input parameter so a subdirectory of the branch can be published

I have a manual in subdirectory which needs the source code outside that folder to be included hence need to publish the manual/book folder from my branch after build.

https://github.com/tusharjoshi/design-patterns-workshop

Title not available in PDF Document Properties

I'm adding the following information in the adoc file but the title is not available as PDF Document Property

// Document properties
:title: Technical Guidance for the implementation of INSPIRE dataset and service metadata based on ISO/TS 19139:2007
:creator: Temporary MIWP 2021-2024 sub-group 2.3.1
:revdate: 2022-01-31
:author: INSPIRE Maintenance and Implementation Group (MIG)

Do you know why?

Action execution is failing

i tried adding header using docinfo https://docs.asciidoctor.org/asciidoctor/latest/docinfo/ but build fails with
"Configure git
fatal: --local can only be used inside a git repository"

Thanks,

How can I publish different page to gh-pages

As of now, I see it's picking up README.md and renaming to index.html and later publishes to gh-pages. Can I point different file, maybe a generated asciidoc html to gh-pages.

How to add a `CNAME` file to the `gh-pages` branch

I use asciidoc and the asciidoctor-ghpages-action to publish a documentation website with a custom domain. The custom domain on GitHub needs a CNAME file in the root of the gh-pages branch. If I put the file there manually, it gets deleted at the next action run.

Include parameter to define the source directory

Add a source_dir parameter to indicate where AsciiDoc files will be built and gh-pages published from.

The runs.using key in action.yml must be one of: [docker node12], got composite

When running the job locally using https://github.com/nektos/act I get the following error:

[asciidoctor-ghpages/build] ⭐  Run manoelcampos/[email protected]
[asciidoctor-ghpages/build]   ☁  git clone 'https://github.com/manoelcampos/asciidoctor-ghpages-action' # ref=v1.3.0
[asciidoctor-ghpages/build]   ❌  Failure - manoelcampos/[email protected]
Error: The runs.using key in action.yml must be one of: [docker node12], got composite

Would be good to have support for act since it would allow for easy local before-commit testing.

Provide a configuration for the output branch

In some cases, we do not want to publish to github pages.

Configure file extensions?

Is there a way to configure which file extensions this action will recognize? I often use .asciidoc which is not captured and converted.

Live Demo Unavailable

It appears that workflow deployment https://manoelcampos.com/asciidoctor-ghpages-action/ is unreachable.

Don't have a screenshot but a few days ago I noticed it being redirected to a gambling site. Perhaps we should move it to github hosted pages ?

Links to local files

I have a README.adoc file that links to another local adoc file example.adoc. In the gh-pages branch they are converted to html files as intended (README.html and example.html), although the link still refers to an adoc file example.adoc.

link:example.adoc[my local file]

is there anyway to automatically update all the links so that they refer to the html files instead?

Action keeps failing after latest update

I've been using lately this workflow without any issue but today i'm starting to see the failures as soon as is try to build the adocs to generate the gh-page contetnt. This is the latest run i did.

https://github.com/mumuki/cspec/runs/5696563693?check_suite_focus=true

The yml i'm currently using is on https://github.com/mumuki/cspec/blob/fix-pipeline/.github/workflows/asciidoctor-ghpages.yml

STEM and diagrams enabling

How to enable the https://asciidoctor.org/docs/asciidoctor-diagram/ and https://docs.asciidoctor.org/asciidoc/latest/stem/stem/ ?

I tried to do it by adding the 'Install plantuml' and 'Install gnuplot' steps into asciidoctor-ghpages.yml but it seems doesn't work:

name: asciidoctor-ghpages

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2

      - name: Install plantuml
        run: sudo apt-get install -y plantuml

      - name: Install gnuplot
        run: sudo apt-get install -y gnuplot

      - name: asciidoctor-ghpages
        uses: manoelcampos/asciidoctor-ghpages-action@v2
        with:
          asciidoctor_params: --attribute=nofooter
          pdf_build: true