README.md

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 quay.io/openssl-ci/docs. 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 quay.io/openssl-ci/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