Skip to content

Latest commit

 

History

History
120 lines (78 loc) · 5.53 KB

README.adoc

File metadata and controls

120 lines (78 loc) · 5.53 KB
Raw

Asciidoctor Documentation Site

Deploy Status

This repository contains an Antora playbook project for building the documentation site for the Asciidoctor ecosystem at docs.asciidoctor.org.

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. We recommend installing and running the antora command on demand using npx. npx installs Antora the antora package into a global cache, then runs the corresponding antora command.

$ npx antora antora-playbook.yml

To ensure documentation updates are fetched from each content repository, add the --fetch flag when invoking antora:

$ npx antora --fetch antora-playbook.yml

If you prefer, you can install Antora globally. To learn how, refer to the installation instructions in the Antora documentation. You can then run the antora command directly on the playbook file hosted in this repository.

$ antora antora-playbook.yml

The 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 meta Antora package antora in netlify/package.json. 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 © 2020-present Dan Allen, Sarah White, and individual contributors to the docs.asciidoctor.org repository. The source and configuration files in this repository are licensed under the terms of the MIT License.

The build for this documentation site sources content from various repositories within the Asciidoctor organization on GitHub. All the content the build retrieves is free and open source and licensed according to the terms specified in each repository.

Unless otherwise noted, the documentation content is licensed under a Creative Commons Attribution 4.0 International License (CC BY 4.0).

Use of the Asciidoctor projects are granted under the terms of each software project’s open source license. Those licenses include MIT, Apache-2.0, and CC BY 4.0.