Part 1 Getting Started

Most users will prefer the Advanced Usage over the Quick Start.

Quick Start

1.

Create a new repository from the public template github.com/ravirajani/ravirajani.github.io.
2.

Modify the index.adoc file to include your custom content for the landing page.
3.

Create AsciiDoc files for additional pages or for includes to be shared among pages.
4.

Modify the config.yml file. List additional pages under chapters or appendices as appropriate.
5.

Under your repository’s Settings, navigate to the Pages tab, and enable GitHub Actions as your Build and Deployment Source.
6.

Commit and push your changes. The site will get built and deployed on GitHub’s servers.

Advanced Usage

Prerequisite

You have Ruby installed on your system.

1Create a repo

You may start with a clean repo or clone the template repo.

2Install gems

•

Jekyll is a Ruby gem that includes a lightweight webserver that will automatically reload pages when it detects changed files.
•

The executable adoctohtml that comes with asciidoctor-html has a --watch option that will regenerate the HTML for modified AsciiDoc sources.

The above two tools can be used together to instantly view an HTML preview when you change a source file. They can be installed with:

gem install bundler ①
bundle init         ②
bundle add logger jekyll asciidoctor-html ③

Skip this if you already have Bundler installed.
Creates a default Gemfile. Skip this if you are using the template repo.
Adds the required dependencies to the Gemfile and installs them.

3Run the live preview

Open a terminal window and, in the working directory, run

adoctohtml --watch

In another terminal, run

cd wwww ①
jekyll serve --livereload

This is the output directory, and can be changed in the configuration file.

This will serve a preview on localhost:4000 which automatically refreshes when you change a source file.

The adoctohtml script only listens to changes to the source files listed under chapters and appendices in config.yml. If you change the configuration file itself, or any includes or assets, you will need to restart the script to see the effect of your changes.

Configuration

The adoctohtml script loads its configuration from a file whose location can be specified on the command line.

The available configuration options are shown in the config.yml for this documentation site which we reproduce below.

config.yml

# displayed in the header
title: Documentation for asciidoctor-html

# when space is tight
short_title: asciidoctor-html

# displayed in the footer
# overrideable in the document's author line
authors:
  - Ravi Rajani

# chapters and appendices are lists of AsciiDoc
# documents to be converted to HTML
chapters:
  - index.adoc
  - getting-started.adoc
  - lists.adoc
  - numbered-blocks.adoc
  - macros.adoc
  
appendices:
  - tests.adoc

# how to refer to a page
chapname: Part    # default: Chapter

# these directories are relative to this file
srcdir: .         # default: .
outdir: ../html   # default: www

# provide a base_url if you want to generate
# a sitemap
base_url: https://ravirajani.github.io/asciidoctor-html/

LaTeX

You can insert inline LaTeX code within single $ signs or using the inline stem macro. Displaymath code can be inserted within \[ and \] delimiters or inside a passthrough block with the stem style.

If you want to display a dollar sign, use the {dollar} variable.

Navigation Menus and Submenus

asciidoctor-html will automatically generate a navigation menu if the site contains multiple pages. Furthermore, a navigation submenu will be displayed below the active navigation item provided the active page contains multiple level 1 (==) sections with an ID attribute.

Assets

Images should be added to the folder $srcdir/assets/img and referred to in the AsciiDoc sources by just the name of the file.

Subfolders img, css, favicon of $srcdir/assets will get copied over to $outdir. You may use this feature to replace the default assets included with asciidoctor-html.

« Welcome Part 2 »