mojavelinux/docs.asciidoctor.org

My working copy of the Antora playbook project (i.e., site manifest) for the future Asciidoctor documentation site.

Asciidoctor Documentation Site

This repository contains an Antora playbook project for building the (future) documentation site for the Asciidoctor ecosystem.

You can find a preview of the site at asciidoctor-docs.netlify.com. Keep in mind this URL is only temporary.

Documentation Structure

The documentation site is built using Antora. The content is pulled from various source repositories in the Asciidoctor organization on GitHub. These sources are defined in the Antora playbook file, antora-playbook.yml. Each content source points to a folder in one or more branches that is structured as a documentation component, which Antora consumes.

The UI for the site is hosted in a separate repository, asciidoctor-docs-ui.

Quickstart

To generate the Asciidoctor Docs site, you first need to install Antora. Follow the installation instructions in the Antora documentation. We recommend installing it globally, if possible.

Once Antora is installed, run the antora command on the playbook file hosted in this repository.

$ antora antora-playbook.yml

This command will generate a site into public/. Navigate to public/index.html in your browser to view the site offline.

How to Upgrade Antora in CI

This section provides instructions for how to upgrade Antora used in the Netlify CI build.

1. Set the version of the Antora packages @antora/cli and @antora/site-generator-default in netlify/package.json. Both packages should be set to the same version. The version should be an exact number so we have control over exactly when it gets upgraded.

2. Switch to the netlify directory and run the following command to update package-lock.json:

   $ npm i --no-optional

3. If there are new options in Antora we want to take advantage of, update the antora command defined in netlify.toml. Otherwise, leave this file alone.

4. Commit the changes to the main branch.

Netlify will take it from there.

Hosting

This site is hosted on Netlify. It’s managed by the account info [at] this domain.

Deployment is triggered via a webhook to any branch in the git repository (configured as URL: https://api.netlify.com/hooks/gitlab, events: Push Events, Merge Requests Events).

The deploy job on Netlify is configured by the file netlify.toml. This configuration files defines certain environment variables that control the behavior of Yarn and Antora. When the job runs, it switches to the netlify/ directory, runs npm i --no-optional, then invokes antora.

The Netlify deploy logs for docs.asciidoctor.org can be viewed at app.netlify.com/sites/asciidoctor-docs/deploys.

The site is also built nightly on Travis CI to pick up any updates to the content made during the day. The nightly CI job, configured in .travis.yml, triggers the Netlify job by pinging the $NETLIFY_BUILD_HOOK url. The $NETLIFY_BUILD_HOOK environment variable is defined in the Travis CI settings.

Domain Name

The domain name for this site is configured using the following A record:

docs 3600 IN A 104.198.14.52

The certificate for this site was generated by Let’s Encrypt and is shared with the certificate for asciidoctor.org. See the README for asciidoctor.org to find details about how it was generated and configured.

TLS Certificate (HTTPS)

The TLS certificate for docs.asciidoctor.org was issued by Netlify using Let’s Encrypt and is renewed automatically.

You can verify the certificate is valid using:

$ curl -vI https://docs.asciidoctor.org

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

Netlify redirects all traffic to HTTPS automatically (i.e., it forces HTTPS).

Copyright and License

Copyright © 2012-2020 Dan Allen, Sarah White, and the individual contributors to Asciidoctor. Except where otherwise noted, the content of the documentation and websites is licensed under a Creative Commons Attribution 4.0 International License. The use of the Asciidoctor projects are granted under the terms of each software project’s license.