CloudNativePG Website

Welcome to the CloudNativePG Website Project! Are you interested in helping improve the CloudNativePG website or documentation? We’d love your support!

Join the conversation and collaborate with us in the #cloudnativepg-www Slack channel.

Requirements

• HUGO
• Node.js

On macOS with brew type: brew install hugo node

Branches

The most important branches are:

• main: trunk
• production: the one visible in Github Pages

So, if you want to see the changes on cloudnative-pg.io you need to merge them in the production branch.

Building

Build locally (once you've installed Hugo & npm):

With drafts:

npm install && npm run dev

As the GH Action builds (excludes draft content):

npm install && npm run prod

This will compile the css file into assets/css/output.css. This file is ignored by git, so it is generated each build. If you make changes to assets/css/main.css you will need to restart the hugo server (e.g. stop it and run npm run prod) to pick up the changes. This is a temporary fix while Hugo & Tailwind JIT learn how to play nicely together.

CSS

CSS is partly built by hugo & partly built outside of hugo by npm run css, which is called by npm run dev|prod. If you start to use a new Tailwind class restarting hugo is required (stop the server and npm run dev), if you edit assets/style.css it should compile in correctly without restart. This is to mitigate this issue.

Adding content

Blogs

Before you write a blog, you should add yourself to the list of authors:

hugo new authors/$your_github_handle

and edit the resulting files (authors/$your_github_handle/index.md & authors/$your_github_handle/temp-avatar.png - you'll want to replace & rename the avatar image!) to fill in your name.

For example:

hugo new authors/drsm79

Add a draft blog post by running:

hugo new blog/first-post

This will make the necessary files and duplicate a header image. Find an openly available one to replace it with on Unsplash or similar, and include the attribution.

Edit the file, and once happy remove the draft: true - it should now show up for npm run prod.

Documentation

Documentation lives alongside the operator code, inside the docs/src folder. It is written in Markdown using mkdocs.

The website contains a static copy of the HTML files generated from the Markdown sources, inside the assets/documentation/$version_number folder (where $version_number is a minor release of CloudNativePG).

The hack/import_docs.sh script has the logic to import the files from a release branch, generate the HTML and save the files in the appropriate folder.

Below you find instructions on how to update the docs for a new minor release or a patch release.

New minor release

Create a new file called X.Y.md (X.Y matching the minor release branch in the operator repo) inside the content/docs folder, with the following content:

---
release:  X.Y.0
location: /documentation/X.Y
release_date: DD Mon Year
release_notes: https://github.com/cloudnative-pg/cloudnative-pg/releases/tag/vX.Y.0
---

Then run:

hack/import_docs.sh X.Y

This will import all the files under assets/documentation/X.Y. Open the top-level ./assets/documentation/X.Y/index.html page with your browser and verify everything is OK, then add the folder to the Git repo (in a development branch).

New patch release

Modify the X.Y.md file inside content/docs folder by updating the version and the release date.

Then run:

hack/import_docs.sh X.Y

Apply all changes in the development branch and push. If you are adding a new patch release to the latest minor version, you will need to update the current branch (which at the moment is a copy of the folder).

Publishing on the website

Changes that have been merged into main are not yet visible on the website. To publish them, they need to be merged into the production branch.

Please publish to production by doing a direct merge into the branch from main. This needs to be done by an administrator.

If you try to merge or cherry-pick into production and you don't have the right permissions, git will alert you about the branch protections.

remote: error: GH006: Protected branch update failed for refs/heads/production.
remote: error: Changes must be made through a pull request.

Please don't make a pull request. Instead, get an administrator to make the needed changes, or to make you an administrator. A pull request would create unnecessary discrepancies between main and production.

Once a commit is merged to production, github will trigger the necessary hugo_build and pages-build-deployment workflows that will update cloudnative-pg.io.