OpenCue documentation

Welcome to the repository for the OpenCue documentation and website. This repository hosts all the code and resources to build the OpenCue documentation and website. We welcome contributions to the docs.

Contributing to the documentation

This section describes the process you need to follow, and the tools you need to run, to propose changes to the OpenCue documentation.

Before you begin

To learn about the process for contributing to OpenCue, see Contributing to OpenCue. This page provides additional help and information about contributing to the OpenCue documentation.

As with all changes to OpenCue, you also need to be familiar with common Git workflows.

Website infrastructure

We run Hugo to generate the OpenCue website. The site implements the Hugo Docsy theme to provide site structure and styling. The OpenCue website is managed and hosted on Netlify.

OpenCue documentation is written in Markdown. To publish the site, we run Hugo to generate HTML content.

Proposing changes

On most existing website pages, click Edit this page to propose simple changes to the documentation. You can then edit the Markdown for that page using the GitHub online editor and create a new branch to commit your changes and start a pull request.

For larger changes, such as proposing a new page, or proposing changes to the site homepage, you can clone and set up a local copy of the repository. To preview your changes locally on your development machine, you need to install a number of dependencies, such as Git and the extended version of Hugo. For more information, see the Docsy documentation.

To set up a local copy of the OpenCue website:

1. Make sure NPM (Node Package Manager) is installed on your system.

2. Follow these steps to install Hugo for your operating system. Or, you can follow these steps to install from binaries.

3. Clone the opencue.io repository:

   git clone https://github.com/AcademySoftwareFoundation/opencue.io.git

4. Change to the opencue.io directory:

   cd opencue.io

5. Recursively update all Git submodules in the repository to install Docsy and related dependencies:

   NOTE: Docsy relies on additional submodules, such as Bootstrap. If you skip this step, the hugo command fails.

   git submodule update --init --recursive

6. Run the npm command to install any required Node.js dependencies:

   npm install
   

7. Install AutoPrefixer to parse the CSS files:

   npm install autoprefixer

8. Install PostCSS so that the site build can create the final CSS assets:

   npm install postcss-cli

9. Run the hugo command to verify the installation steps were successful:

   hugo
   

10. Run the hugo server command to serve the static content and view it in your browser:

    hugo server
    

You can now create a Git branch in your copy of the repository to experiment with making changes. To preview your changes in a browser, run the hugo server command. When you're ready to push your changes to the opencue.io repository, create a pull request.

Writing guidelines

The OpenCue documentation follows the Google Developer Documentation Style Guide. As with changes to the primary OpenCue repository, all changes to the documentation and website are peer-reviewed by project contributors.