GitHub Pages with Asciidoctor

GitHub Pages is a static site hosting service that allows you to publish content directly from a GitHub repository. It supports Markdown by default and does not natively support Asciidoctor. So you need to create static HTML files from Asciidoctor files on your local machine and push them to the local build branch of your repository. When merging the local build branch to the main branch, the GitHub Action will automatically deploy the static HTML files to the main branch. Technically, Jekyll is doing nothing on GitHub side since rendering is done locally. So you need to turn off Jekyll on GitHub Pages.

To enable GitHub Pages, go to your repository settings and scroll down to the "Pages" section. Select the main branch as the source for your GitHub Pages site.

Given that your GitHub username is nsalexamy and your repository name is service-foundry, your GitHub Pages URL will be:

Install ruby using homebrew:

Add the following line to your shell profile like .zprofile

/opt/homebrew/lib/ruby/gems/3.4.0/bin comes from the output of the command gem env and it may be different for you. You can check the output of gem env to find the correct path.

Example Output

verify the installation:

The _config.yml file is the configuration file for Jekyll. You can customize it to fit your needs. Here is an example of _config.yml file for the local-build branch.

Here is a sample Asciidoctor file that you can use to test your Jekyll site. Create a new file named index.adoc in the root directory of your project and add the following content:

Here is a sample HTML layout file that you can use to render your Asciidoctor files. Create a new file named default.html in the _layouts directory and add the following content:

By Jekyll configuration, the generated HTML files will be saved in the pages directory.

The _config.yml file of 'local-build' branch is different from the one in the 'main' branch. So you need to add the _config.yml file to .gitignore file. You can use the following command to do this:

On GitHub Pages, Jekyll will process only index.html file and the files in the 'pages' directory which are generated from Asciidoctor files. So you need to create a new _config.yml file in the root directory of your project and add the following content:

_config.yml

You can use SCSS to style your Jekyll site. Create scss files in the _scss and create the main.scss file in the assets/css directory.

This file will be rendered to main.css in the pages/assets/css directory.

Add the line below to use the main.css file in the default.html file.

You can use data files to store data in your Jekyll site. Create a new file named navigation.yml in the _data directory and add the following content:

Here is an example of how to use data files in your Jekyll site. Create a new file named nav.html in the _includes directory and add the following content:

Jekyll layout files use Liquid templating language. You can use Liquid tags to include data files in your Jekyll site. For example, you can use the include tag to include the nav.html file in your layout file:

You can use the rouge highlighter to highlight code in your Jekyll site. Add the following line to your _config.yml file:

Add the lines below to your layout file to include the rouge CSS file:

If you do not want to use source highlighting from your Asciidoc files, you can add the following line to at the top of your code block:

The screenshot below shows the source highlighting in the Asciidoctor file. The code block is highlighted using the rouge highlighter.

Asciidoc files are rendered to HTML with a table of contents by default on the left side. You can hide the table of contents by adding the following line to the top of your Asciidoctor file:

In a layout file, you can use the show_toc variable to hide the table of contents. For example, you can use the following code in your layout file:

And add lines below to your SCSS file to hide the table of contents when show_toc is set to false.

Here is an example of included file with arguments.

In this example, topic and category_url are variables that are passed to the document-topic.html file.

To pass variables to the document-topic.html file, you can use the following syntax in your layout file:

'{% include documents-topic.html topic=topic category_url=category.url %}' shows that the topic variable is passed to the document-topic.html file and the category.url variable is passed to the category_url variable in the document-topic.html file.