Jenkins Documentation

This repository hosts parts of the documentation of jenkins.io.

• Developer Guide

• User Guide

• Tutorials

• Solutions Pages

• Books

How to Build the Versioned Documentation Locally with Antora

The documentation site for Jenkins is split into two parts:

1. Version-controlled documentation (managed using Antora)

2. Non-versioned documentation (using Gatsby for rendering the current website)

This guide focuses on building the version-controlled documentation using Antora.

Overview of Gatsby

Gatsby is a React-based framework that allows developers to create fast and optimized websites. It leverages GraphQL for data handling and provides a plugin ecosystem for extended functionality. This project utilizes Gatsby for rendering the non-versioned documentation of Jenkins, enhancing performance and user experience.

Project Structure

The Gatsby site is structured as follows:

• src/: Contains the source files for the site, including components, templates, and styles.

• static/: Static files that are directly served, such as images or fonts.

• gatsby-config.js: Configuration file for Gatsby where you can customize settings and plugins.

Installing the Prerequisites

1. Install Node.js and npm

   It is recommended to install Node.js and npm using the Node Version Manager (nvm): * NVM repository: [https://github.com/nvm-sh/nvm](https://github.com/nvm-sh/nvm)

   + Alternatively, you can download and install Node.js from the official Node.js website:

   • Node.js official website: [https://nodejs.org](https://nodejs.org)

     After the installation, verify that both node and npm are correctly installed:

     node --version
     npm --version

2. Install Antora CLI

   Antora is used for generating versioned documentation. Install it globally via npm:

   npm install -g @antora/cli @antora/site-generator-default

Installing Project Dependencies

Once Node.js, npm, and Antora are installed, install the dependencies by running the following command at the root of the repository:

npm i

Building the Versioned Docs

To build and serve the site locally, use the provided Makefile. Run this command at the root of the repository:

make all

Once the site is up and running, it should be available locally at:

• http://127.0.0.1:8080

Documentation Structure

• Antora Documentation: This version-controlled documentation covers different guides (e.g., Developer Guide, User Guide).

• Gatsby Documentation: Non-versioned content managed via Gatsby. This forms the basis of the current https://jenkins.io/ site, which will be replaced in the future. For more details on how to work with the Gatsby site, refer to its dedicated README documentation at:

  • https://github.com/jenkins-infra/docs.jenkins.io/tree/main/site#readme/[https://github.com/jenkins-infra/docs.jenkins.io/tree/main/site#readme/]

For more details on running the project, refer to the detailed documentation in the README.md file:

Running the Project Documentation

Contributing

If you have any queries or contributions or updates for the documentation, feel free to create an issue and/or submit a pull request.