amarantha-k / docs-site

The Antora playbook project, contributing documentation, and home page for the new Couchbase Docs site.

Couchbase Documentation Site

Antora playbook project for the Couchbase documentation site published at docs.couchbase.com.

Playbook

The playbook, antora-playbook.yml, provides Antora with the site URL, docs component repository and branch locations, site UI location, global AsciiDoc attributes, and Asciidoctor extensions.

Home Docs Component

The home directory contains the Home documentation component.

Custom Asciidoctor Extensions

The custom extensions in the lib directory process the manpage macro (Couchbase CLI and Backup components), Swagger UI macro, and multi-row table headers.

File watcher and LiveReload

This repository contains a script to watch .adoc/.yml files and trigger a new Antora build when it detects changes to those files. The script also starts a web server and can use LiveReload to reload the browser tab after the Antora build completes. To use the script, run the following.

1. Install dependencies.

   npm install gulp-cli -g
   npm install

2. Install the LiveReload chrome extension.

3. Start the script. The web server’s host URL is printed to the console after the watch task completes.

   gulp

4. The console output will print status information every time a change is detected.

   [16:24:28] Starting 'build'...
   [16:24:32] Finished 'build' after 3.6 s
   [16:24:32] Starting 'preview'...
   [16:24:32] Finished 'preview' after 1.17 ms

5. Make changes to your AsciiDoc files locally. The browser tab should automatically reload after a short while.

Contributing

To learn how to use the playbook and generate the docs site locally, see our contributing guide.