ClusterLabs.org website

Dependencies

ClusterLabs.org is primarily generated by Hugo, a static website generator. The site's only dependencies are Go >= 1.18.0 and Hugo >= 0.128.0. (Hugo 0.136.0 and 0.136.5 are specifically known to work.)

If your OS does not provide Hugo, you can download an architecture-specific tarball from https://github.com/gohugoio/hugo/releases/latest, extract it, and move the binary to somewhere on your $PATH.

Building the site

The hugo command must be run from the src directory.

To generate a live preview in a checkout, run hugo server. To generate final content on disk (whether in a checkout or on the production site), run hugo.

Hugo will put the generated files in the html directory (which is excluded from version control). Existing files there will be overwritten but not deleted, so anything removed from the source has to be removed from a previously generated html directory manually. For testing a checkout, it's fine to simply erase html entirely before regenerating, but on the live server, there are non-version-controlled files that must be kept (including html/images and much of html/projects/pacemaker).

If you want to test the PHP pages in the site, hugo server will not be sufficient. You'll have to install a PHP-enabled local webserver (such as Apache or Nginx) and use your checkout's html directory as the document root.

Using Hugo

ClusterLabs uses Hugo's Congo theme, as a Go module. When you create a checkout, run hugo mod get once. To update the site to the latest version of the theme, run hugo mod get -u.

Hugo does not follow symbolic links.

Configuration files and front matter are in TOML format.

The source is in Goldmark (CommonMark and GitHub Flavored Markdown with extensions).

Source directory layout

• archetypes/default.md: This initializes the front matter of pages created with the hugo new content command.

• config/_default/: Configuration for Hugo and Congo.

• content/: Page source lives beneath here (as .md files). URL paths will mirror this directory hierarchy. The home page is content/_index.md; each other page should have its own subdirectory.

  If a page directory has subdirectories, the page source should be _index.md and will get an automatic listing of all subpages unless layout = "single" is added to its front matter. With no subdirectories, the name should be index.md.

  If a page directory contains an image whose name starts with cover, it will be used as a splash image and should be 1320 pixels wide. You can also provide a 160-pixel-wide by 120-pixel-high thumbnail named starting with thumb which will be used in automatically generated page listings.

• layouts/: Page templates. layouts/_defaults/ contains layouts for PHP pages (copied from the theme's layouts for HTML pages). layouts/partials/ contains snippets that can be included by pages or other layouts (these also were copied from the theme, then customized).

• resources/: Automatically maintained cache

• static/: Files that will be copied as-is rather than generated (images, CSS, etc.) and can be used on any page. Like content/, the URL paths will mirror the directory hierarchy.

Web server configuration

The clusterlabs.org web server is configured to redirect certain old URLs to their new locations, so be careful about renaming files. A helpful feature is the ability to put aliases = ["/some/url/path", ...] in a page's front matter with URL paths that will be redirected to the page's main URL.

For more information

• Hugo: https://gohugo.io/documentation/
• Goldmark: https://gohugo.io/content-management/formats/#markdown
• Congo theme: https://jpanther.github.io/congo/docs/