Turtles Product Documentation

Build the Documentation site

The repository uses Antora Playbooks to locally or remotely build the AsciiDoc content into a static website.

Prerequisites

git

You need git to get the source code of this repository. Run the command below to check whether git is installed on your machine.

git --version

If you don’t have git installed on your machine, download and install it for your operating system from the git downloads page.

Node.js

Antora requires an active long term support (LTS) release of Node.js. Run the command below to check if you have Node.js installed, and which version. This command should return an active Node.js LTS version number

node -v

If you don’t have Node.js installed on your machine, install it, preferably via nvm

Clone the Playbook repository

Run the git command to clone this repository.

git clone https://github.com/rancher/turtles-docs.git

Install node modules

Open a terminal at the root of the git repository. Run the command below.

npm install

Build the Static Website

You can use the make command to build the documentation site locally or remotely. The Makefile defines various tasks for building the site using different playbooks.

Build the site locally using the GitHub Pages playbook:

To build the site locally using the GitHub Pages playbook, run the following command:

make gh-pages

This will generate the static website using the turtles-gh-pages-playbook.yml playbook.

Build the site remotely:

To build the site remotely using the remote playbook, run:

make remote

This will use the playbook-remote.yml to generate the site remotely.

Build the site using the development playbook:

For development purposes, you can build the site using the development playbook by running:

make dev

This will use the turtles-dev-playbook.yml to generate the site with development settings.

Clean up the build:

To remove the build and temporary directories, use the following command:

make clean

This will delete the build and tmp directories.

Preview the site locally:

To preview the site locally, use the preview task:

make preview

This will serve the site locally, allowing you to view it in your browser.

Watch for changes and rebuild:

To watch for changes in the content and rebuild the site automatically, use the watch task:

make watch

This will watch the content and documentation files for changes, rebuild the site, and preview it with hot reload.

Continuous Integration (CI):

To run the build process for continuous integration, use the ci task:

make ci

This will run the build using the GitHub Pages playbook and the development playbook in sequence.