🌐 Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
_archive initial Awestruct-based site and build Mar 21, 2013
_config update list of contributors Oct 25, 2018
_ext configure user manual and migration page to link to CSS instead of em… Aug 16, 2018
_layouts add favicon made from new logo Oct 11, 2018
_partials build tags if Awestruct is run in development mode w/ generate-on-acc… Aug 18, 2017
docs switch page for Asciidoctor Reveal.js to jsDelivr Nov 16, 2018
fonts upgrade to Font Awesome 4.7.0 May 11, 2018
images revise the Taming SVG chapter Oct 4, 2018
javascripts resolves #664 add "view result" link to table examples in quick ref (PR May 5, 2017
man use docs layout for man page Dec 23, 2016
news load iframe securely on blog Oct 22, 2018
release-notes fix malformed close tag in 1.5.0 release notes May 10, 2018
stylesheets change background color of example block back to white Sep 30, 2018
.awestruct_ignore add Dockerfile for creating an image to build the site Aug 28, 2016
.editorconfig Remove trailing whitespace from docs. (PR #214) Dec 26, 2016
.gitignore Add `.idea` Directory to `.gitignore` File Mar 1, 2016
.travis.yml change lint task to check for trailing whitespace only Sep 30, 2018
Dockerfile add Dockerfile for creating an image to build the site Aug 28, 2016
Gemfile upgrade to Asciidoctor 1.5.7 May 11, 2018
README.adoc update wording in README Apr 1, 2018
Rakefile change lint task to check for trailing whitespace only Sep 30, 2018
contributors.html.slim Adds navigation pane (TOC) to documentation pages Mar 27, 2016
favicon.ico update favicon Oct 18, 2018
humans.txt credit Netlify in humans.txt Sep 26, 2018
index.adoc upgrade home page to use README from 1.5.8 release; switch to jsDelivr Nov 6, 2018
netlify.toml move netlify configuration into repository Aug 17, 2018
news.html.slim Adds navigation pane (TOC) to documentation pages Mar 27, 2016
robots.txt initial Awestruct-based site and build Mar 21, 2013
supporters.html.slim fix styling / URL for okta on supporters page Apr 20, 2018


Asciidoctor Project Site

Build Status Deploy Status

This is the project site for the Asciidoctor project. The site is composed in AsciiDoc, styled by Foundation 4, baked with Awestruct, and hosted on Netlify.

For instructions on how to install Awestruct and its dependencies, refer to the Install Awestruct section below.

Preview the site locally

To preview the site locally, simply run the default rake build task:

$ rake

The default rake build task is preview, so you’re effectively typing:

$ rake preview

The preview task is just a short way of invoking Awestruct in development mode directly:

$ awestruct -d

Now visit http://localhost:4242 to preview the site.

To rebuild the site from a clean state, pass the --force flag to the preview task:

$ rake preview[--force]

You can pass any flag through to Awestruct using the syntax in the previous command.

If you just want to generate the site, run:

$ rake gen

Add and commit files

Add new files (such as a new blog entry or image):

$ git add news/news-slug.adoc

or all new files present in a directory (it only affects new files, skips files already committed)

$ git add news/

Commit all files marked to be committed, including new files that were just added:

$ git commit -m 'your message here'

Commit all files that have changed, even if not marked to be committed:

$ git commit -a -m 'your message here'

Make sure there are no files that are "untracked" or "modified":

$ git status

You should see:

nothing to commit (working directory clean)

Now you are ready to deploy.

Install Awestruct

First, install RVM. Trust me on this.

$ curl -#L https://get.rvm.io | bash -s stable --ruby

Next, setup an RVM gemset for working with the Asciidoctor site:

$ rvm use 2.4 --create

At this point, you could install Awestruct directly, but since the site build has some additional dependencies, it’s best to let bundler handle the installation. Bundler will also ensure that you are using the correct versions of each gem when you run Awestruct.

$ bundle --path=.bundle/gems

You’re now Awestruct!


This website is hosted on Netlify at the domain name asciidoctor.org. It’s managed by the account docbot [at] asciidoctor [dot] org and other Asciidoctor administrators.


Netlify also handles generating and deploying the site. Deployment is triggered via a webhook on the master branch of the git repository. The deploy job executes the following command:

$ rake deploy:netlify

The version of Ruby is set using an environment variable in the Netlify configuration.

The deploy logs for asciidoctor.org can be viewed at https://app.netlify.com/sites/asciidoctor/deploys.


There are two DNS records that point asciidoctor.org and www.asciidoctor.org to the Netlify servers:

@ 3600 IN A
www 3600 IN CNAME asciidoctor.netlify.com.

The Netlify server automatically sets up a redirect that points from www.asciidoctor.org to asciidoctor.org.

TLS Certificate (https)

The TLS certificate for asciidoctor.org and www.asciidoctor.org was issued using Let’s Encrypt and is managed by Netlify.

Verify the certificate is valid using:

$ curl -vI https://asciidoctor.org

Look for CN=asciidoctor.org under the “Server certificate” section.

Thanks to Netlify, the certificate will be regenerated automatically when it nears its expiry date.