README.md

Huddo Docs Website

This site is hosted on github pages and is generated by mkdocs and mkdocs-material

The static files for the website are served out from the gh-pages branch. They are automatically generated and committed by mk-docs.

A Jenkins hook automatically builds and deploys this repository on any push to the master branch. Therefore removing the need to set up local dev environments for contributing to the documentation.

Making Changes, adding pages, etc

Directly commit any changes to the master branch to publish a new version of the website. This includes editing md files or config (in mkdocs.yml) and adding new pages and assets.

Admonitions

We use a plugin to show nice Warning/Danger/Info/Note etc

To style your comment use the following syntax

!!! info

    This is an information admonition

For more styles and examples please see the documentation.

Setting Up Local Dev For Previews

1. Run in Docker

   docker compose up
   
   # Previously this was command, but addition of plugins breaks
   # docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
   

2. Open Preview

   http://127.0.0.1:8000
   

Deploying Changes Manually

1. Make sure you've previewed the changes with mkdocs serve

2. Make sure your local repo is up to date

3. Run this command

   mkdocs gh-deploy

More info

1. See the file mkdocs.yml for site config
2. Check out the docs for mkdocs and mkdocs-material

test jenkins on master

Adding Plugins

Make sure you add to the Dockerfile and the ci.yml