openssl/openssl-docs

docs.openssl.org

The OpenSSL Documentation website is based on Material for MkDocs and this repository contains the required configuration files and build scripts. docs.openssl.org is hosted on GitHub Pages.

Deployment

The website is automatically rebuilt on changes in doc directory of openssl/openssl. Then a new commit is pushed to gh-pages branch which triggers pages-build-deployment GitHub Actions workflow.

To deploy documentation website manually trigger Deploy site GitHub Actions workflow.

Local development

All required dependencies are packed into a container image ghcr.io/openssl/openssl-docs, built from the Containerfile by the Build and deploy container image GitHub Actions workflow. To start playing around you can spin up a container and run commands:

1. Clone the repository:

   git clone https://github.com/openssl/openssl-docs.git
   

2. Run the container:

   podman run -it -v $(pwd)/openssl-docs:/mnt -w /mnt -p 8000:8000 --userns=keep-id ghcr.io/openssl/openssl-docs:latest bash
   

3. Build the docs:

   python build.py <OPENSSL BRANCH>
   

4. Run the development web server:

   mike serve -a 0.0.0.0:8000
   

build.py

A small wrapper script to clone a specific OpenSSL branch and build a documentation website with mike. Run it to build the website:

python build.py <OPENSSL BRANCH>

mike puts generated content into a separate branch gh-pages. Please refer mike documentation for the details.

hooks.py

All pre- and post- processing is done via MkDocs hooks. Please refer MkDocs documentation for the details.

References

• MkDocs
• Material for MkDocs
• mike