Part 1 Getting Started

Ravi Rajani

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

Quick Start

1.

Create a new repository from the public template repo.
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

The best way to create a repo is to clone the template repo. If you prefer to start from a clean repo, then you will have to modify and supplement the steps below accordingly.

2Install gems

In the root directory, run

gem install bundler ①
bundle install      ②

Skip this if you already have Bundler installed.
Installs the required Ruby dependencies.

3Build the site

Open a terminal window and run

adoctohtml --watch ①

Builds an HTML site in the www directory, automatically regenerating the output when an AsciiDoc source is modified. The output directory can be changed in the configuration 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.

Use a live preview local development server to view your changes instantly as you work.

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

# provide a repl_url if you want to embed
# a JupyterLite REPL
repl_url: jupyterlite/repl/index.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.

You can prevent a section with an ID appearing in a navigation submenu with the skipnav option on a section.

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.