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
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_BRANCHvariable. - You can also configure the branches which you want to run this workflow, with
brancheskey. - 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 (
.pipdirectory) - Install dependencies with
pip - Build documentations with Mkdocs
- Synchronize built files with deployment branch
- Push build into the deployment branch
- 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_BRANCHvariable. - You can also configure the branches which you want to run this workflow, with
brancheskey. - To configure the Github pages, you can go to settings > pages > Source and choose the documentation branch.
Top comments (0)