pingou / centos / sig-guide

Forked from centos/sig-guide 2 years ago
Clone
Text Blame History Raw

Documentation

There is a possibility to also host your documentation under https://sigs.centos.org, following a workflow based on Material for MkDocs (an enhanced version of mkdocs. This SIG Guide is itself following the same workflow, built from .md files hosted in a git repository.

If you want to use the same workflow, proceed like this:

  • create a git repository somewhere (it can be hosted on centos infra - gitlab or pagure - but no limitation)
  • locally test material for mkdocs (see below)
  • create CentOS Infra tracker issue that would contain the SIG name, public git url to clone/pull from
  • once you commit to your upstream git project, it will be rendered in the next minutes and pushed to sigs.centos.org dedicated folder

How to test locally material for mkdocs

The easiest way is just to use podman and a container:

podman pull docker.io/squidfunk/mkdocs-material:latest

Prepare your mkdocs.yml (see ours as quick reference and your docs folder containing your markdown (.md) files. Write documentation and once you have your skeleton, just test locally like this :

podman run --rm -it -p 8000:8000 -v ${PWD}:/docs:z squidfunk/mkdocs-material

You can now open your browser to http://localhost:8000 and you'll be able to see live your edit/changes. Once happy, you can commit to git and see the rendered result in the next minutes going live