Automatic build and publish documentations on Github Pages

Build documentations workflow

With any project you work on, especially an open source project, documentation should be one of the most important things to do. It helps the end-users understand how to use the application, it helps the new developers understand how to work with the project, ...

With MkDocs, we can maintenance the documents easily. Just write documentations in Markdown, and it will build it into HTML static pages for you. Beside it, with the help from GitHub workflows, we can also build the documentations automatically on every push into our GIT repository.

I'd like to share with you my workflow to build documentations. It will listen for changes on documentation files (*.md), then build it and publish it into Github Pages.

Submission Category: DIY Deployments

Yaml File or Link to Code

ActionsHackathon21 / build-documentations

Build documentations

This project follows the DEV.to #ActionsHackathon21 hackathon.

Use GitHub Actions and Workflows to build your documentations with MkDocs, then publish to Github Pages.

Check the complete workflow here (build-documentations.yml)

Actions used

• actions/checkout@v2 To checkout the source code from the repository
• actions/cache@v2 To cache the dependencies, allow us to re use them for future builds

Configurations

• You can config the branch which holds the documentations with DOCUMENTATIONS_BRANCH variable.
• You can also configure the branches which you want to run this workflow, with branches key.
• To configure the Github pages, you can go to settings > pages > Source and choose the documentation branch.

Flows

• Use actions/checkout@v2 to checkout source code from the repository
• Use actions/cache@v2 to cache dependencies (.pip directory)
• Install dependencies with pip
• Build documentations with Mkdocs
• Synchronize built files with deployment branch
• Push build into the deployment branch

View on GitHub

• README: https://github.com/ActionsHackathon21/build-documentations/blob/main/README.md
• Workflow file: https://github.com/ActionsHackathon21/build-documentations/blob/main/.github/workflows/build-documentations.yml
• License: https://github.com/ActionsHackathon21/build-documentations/blob/main/COPYING

Configuration

• You can config the branch which holds the documentations with DOCUMENTATIONS_BRANCH variable.
• You can also configure the branches which you want to run this workflow, with branches key.
• To configure the Github pages, you can go to settings > pages > Source and choose the documentation branch.