diff --git a/README.md b/README.md index d745879..3722b1f 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,88 @@ # 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. +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/