Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/asciidoctor/docs.asciidoctor.org

The Antora playbook project (i.e., site manifest) for the Asciidoctor documentation site.
https://github.com/asciidoctor/docs.asciidoctor.org

antora asciidoctor documentation

Last synced: about 2 months ago
JSON representation

The Antora playbook project (i.e., site manifest) for the Asciidoctor documentation site.

Awesome Lists containing this project

README 

        
= Asciidoctor Documentation Site

// Settings:

:hide-uri-scheme:

ifdef::env-github[:badges:]

// Project URIs:

:url-project: https://asciidoctor.org

:url-site: https://docs.asciidoctor.org

:url-org: https://github.com/asciidoctor

:url-docs-ui: https://github.com/asciidoctor/asciidoctor-docs-ui

// External URIs:

:url-antora: https://antora.org

:url-antora-install: https://docs.antora.org/antora/latest/install/install-antora/

:url-letsencrypt: https://letsencrypt.org

:url-netlify: https://www.netlify.com

:url-netlify-deploys: https://app.netlify.com/sites/asciidoctor-docs/deploys



ifdef::badges[]

image:https://api.netlify.com/api/v1/badges/26d47a9c-82b9-4a7c-92fd-9bdbee16585f/deploy-status[Deploy Status,link={url-netlify-deploys}]

endif::[]



This repository contains an Antora playbook project for building the documentation site for the Asciidoctor ecosystem at {url-site}.



== Documentation Structure



The documentation site is built using {url-antora}[Antora].

The content is pulled from various source repositories in the https://github.com/asciidoctor[Asciidoctor organization on GitHub].

These sources are defined in the Antora playbook file, [.path]_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, {url-docs-ui}[asciidoctor-docs-ui].



== Quickstart



To generate the Asciidoctor Docs site, you first need to install {url-antora}[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 {url-antora-install}[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 [.path]_public/_.

Navigate to [.path]_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.



. Set the version of the meta Antora package `antora` in [.path]_netlify/package.json_.

The version should be an exact number so we have control over exactly when it gets upgraded.



. Switch to the netlify directory and run the following command to update [.path]_package-lock.json_:



 $ npm i --no-optional



. If there are new options in Antora we want to take advantage of, update the `antora` command defined in [.path]_netlify.toml_.

Otherwise, leave this file alone.



. Commit the changes to the *main* branch.



Netlify will take it from there.



== Hosting



This site is hosted on {url-netlify}[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 [.path]_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 [.path]_netlify/_ directory, runs `npm i --no-optional`, then invokes `antora`.



The Netlify deploy logs for docs.asciidoctor.org can be viewed at {url-netlify-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 [.path]_.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 {url-letsencrypt}[Let's Encrypt] and is shared with the certificate for asciidoctor.org.

See the https://asciidoctor.og#dns[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 {url-netlify}[Netlify] using {url-letsencrypt}[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 (C) 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 https://creativecommons.org/licenses/by/4.0/[Creative Commons Attribution 4.0 International License] (CC BY 4.0).



Use of the {url-org}[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.