Skip to content

Contributing

These docs are Markdown, reviewed as a merge request, and published from main. If something is wrong, unclear or missing, the fix is a merge request — including from you.

Where the source lives

Development happens on the internal GRN GitLab. A public mirror at grncloud/docs-grn-cloud is being set up; until it is live, external contributions come through support or your GRN contact.

Set up

git clone <docs-repo-url>
cd docs-grn-cloud

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Preview while you write

mkdocs serve

Open http://127.0.0.1:8000. The site rebuilds as you save.

Check it builds cleanly

mkdocs build --strict

--strict turns warnings into errors — a broken internal link or a page missing from the navigation fails the build. CI runs the same command, so run it before you push.

Open a merge request

git checkout -b docs/short-description
git add docs/
git commit -m "docs: describe what changed"
git push -u origin docs/short-description

Then open the merge request against main.

What a good merge request looks like

  • One topic. A typo fix and a restructure are two merge requests.
  • Says what changed and why. The description is what a reviewer reads first.
  • Builds with --strict. No broken links, no orphaned pages.
  • Real commands only. If you documented a command, you ran it. Never paste output you did not see — mark unverified flows with a scaffold-status note instead.
  • Uses oc, not kubectl. The GRN cluster repositories use oc and these docs match.
  • Follows the style guide.

Adding a page

  1. Create the Markdown file under the right directory in docs/.
  2. Add front matter with title and description.
  3. Add it to nav: in mkdocs.yml — a page not in the nav is unreachable and fails --strict.
  4. Link it from the section index page.
  5. Add it to docs/llms.txt.

Review

A maintainer reviews for technical accuracy, structure and style. Once approved, the merge to main publishes the site automatically.