pingou / centos / sig-guide

Forked from centos/sig-guide 2 years ago
Clone
Blob 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](https://squidfunk.github.io/mkdocs-material/) (an enhanced version of [mkdocs](https://www.mkdocs.org/).  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](https://pagure.io/centos-infra/new_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](https://git.centos.org/centos/sig-guide/blob/master/f/mkdocs.yml) 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