Build

The OpenNebula documentation build requires the following prerequisites (these can be installed using the setup.sh script, see below):

• The Hugo static site generator and web server: extended version 0.155.3
• Go
• Node.js LTS
• npm
• PostCSS
• The documentation uses the Docsy theme

Build the Documentation Locally

To build the documentation locally first clone or fork this repository:

• If you are an OpenNebula developer or partner and have write access to the repository: Clone the repository
• If you are an external contributor or collaborator and do not have write access to the repository: Create a fork

Whether you have cloned or forked the repository, create a new branch from an up-to-date version of the branch you are targetting for the documentation update and work on this new branch. Do not work in the version branches (e.g. one-7.4, one-7.2) or the master branch.

Bootstrap the environment by running the setup.sh script located in the top level of the repository. This will download and install Hugo 0.155.3 along with all other build requirements.

Then build and serve the documentation locally:

• From the repository root folder, run hugo server in a terminal.

Hugo will build the site and expose it locally on localhost:1313/X.Y/ for a version branch (e.g. localhost:1313/7.4/ on branch one-7.4) or localhost:1313/devel/ on the master branch. While editing the markdown, keep referring to the rendered site in a browser to ensure your documentation is formatted properly.

You will see output similar to the following once the documentation is built and is viewable on the URL given in the command line output. The site may take some minutes to build the first time, or upon branch changes.

hugo server
hugo: downloading modules …
hugo: collected modules in 31780 msWatching for changes in /home/adm/opennebula/website-version_5/{assets,content,layouts,package.json}
Watching for config changes in /home/adm/opennebula/website-version_5/hugo.toml, /home/adm/opennebula/website-version_5/go.mod
Start building sites … 
hugo v0.145.0-666444f0a52132f9fec9f71cf25b441cc6a4f355+extended linux/amd64 BuildDate=2025-02-26T15:41:25Z VendorInfo=gohugoio

                   | EN   
-------------------+------
  Pages            | 508  
  Paginator pages  |   0  
  Non-page files   |   2  
  Static files     |  30  
  Processed images |   2  
  Aliases          |   0  
  Cleaned          |   0  

Built in 6508 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)

Tip

Useful options for running Hugo in server mode:
--disableFastRender - Enables full renders on changes
--noHTTPCache - Prevent HTTP caching

Basic Hugo Site Structure

Directory Structure

The docs repo contents are similar to this:

assets/  content/  go.sum     layouts/  node_modules/  package-lock.json  README.md   static/
CNAME    go.mod    hugo.toml  LICENSE   package.json   public/            resources/

The docs markdown files are stored in content/, this is where you should edit or create new documentation files.

Images

Images are contained in the assets/images/ directory. See the Images Guide for details on how to add and reference images. New images should be placed in subdirectories within assets/images to group images related to specific documents or sections.