docs-site

docs-site copied to clipboard

= Couchbase Documentation Site :idprefix: :idseparator: - // Settings: :hide-uri-scheme: // URLs: :url-docs: https://docs.couchbase.com :url-contribute: {url-docs}/home/contribute/ :url-org: https://github.com/couchbase :url-ui: {url-org}/docs-ui :url-license: https://creativecommons.org/licenses/by-nc-sa/4.0/

This is the Antora playbook project (aka site build) for the Couchbase documentation site published at {url-docs}.

== Prerequisites

You must have Node.js 16 installed to generate the site.

node -v

If that command does not report a version that is 16 or greater, head over to https://nodejs.org to download the latest LTS release of Node.js.

== Playbook

The playbook, defined in the playbook file [.path]antora-playbook.yml, configures the build for this site. The playbook specifies the content sources (repository and branches), site URL, UI bundle URL, global AsciiDoc attributes, and Asciidoctor extensions.

The production site is built for each change to the master branch. A deploy preview of the site is also published for each pull request, though without any of the private content sources (unless the pull request comes from a trusted source). The configuration for the deploy preview build is located in the [.path]netlify folder.

If you're building a local version of the Couchbase docs for testing, and want a reduced-scope playbook that just builds Server docs with the components that you are editing locally, https://github.com/couchbase/docs-site/blob/master/home/modules/contribute/examples/local-staging-antora-playbook.yml[here is an SDK-based playbook file] -- use it as a basis for your own local playbook.

== Home Docs Component

The [.path]home/ directory in this repository contains the source for the Home documentation component. All other content is sourced from separate repositories and branches.

== Custom Asciidoctor Extensions

The custom extensions in the [.path]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 that watches .adoc and antora.yml files in the author workspace (as defined by local-antora-playbook.yml) and triggers 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.

. Install dependencies.

$ npm ci

. If you're using Chrome, install the LiveReload https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei?hl=en[chrome extension]. Firefox has built-in support for LiveReload. . Start the build. +

$ LIVERELOAD=true npx gulp

The build first generates the site using Antora, analgous to the npx antora local-antora-playbook.yml command. It then serves the files in the output directory using a local web server.

The web server's host URL is printed to the console after the watch task completes.

.... [17:43:27] Starting server... [17:43:27] Documentation Site Preview started http://localhost:5000 [17:43:27] LiveReload started on port 35729 [17:43:27] Running server ....

TIP: To skip the initial build, use npx gulp serve as the Gulp command.

. The console output will print status information every time a change is detected. + .... [17:33:59] Starting 'generate'... [17:34:02] Finished 'generate' after 3.35 s ....

. Make changes to your AsciiDoc files locally. The browser tab should automatically reload after a short while. . Use Ctrl+C to stop the process.

== Reference Validation

Reference validation, which covers xrefs, includes, and images, is performed automatically when Antora runs. The validation errors will be shown in the log output.

Currently, validation is not enforced, meaning the build will not fail if an invalid reference is detected.

=== Reading the Log Output

If there are reference violations (e.g., broken xrefs), a report of those violations will be printed to the terminal or CI log. Here's an excerpt from that report:

.... [03:39:51.926] ERROR (asciidoctor): target of xref not found: csharp:gs-prereqs.adoc file: modules/csharp/pages/querybuilder.adoc source: https://github.com/couchbaselabs/docs-couchbase-lite (refname: release/3.0) [03:26:50.579] ERROR (asciidoctor): target of xref not found: server:fts:fts-using-analyzers.adoc#token-filters file: docs/public/modules/clusters/pages/search-service/create-full-text-indexes.adoc source: https://github.com/couchbasecloud/couchbase-cloud (refname: main, start path: docs/public) ....

Each message shows the repository source, the refname, and the path from the root of that repository.

== Contributing

To learn how to use the playbook and generate the docs site locally, see our {url-contribute}[contributing guide].

== License

Couchbase Server Documentation © 2024 by Couchbase Inc. is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.

See the LICENSE file or the {url-license}[Creative Commons CC BY-NC-SA 4.0 license page] for details.