TheLazy.Dev
Portfolio GitHub

Blog

actionshackathon21 |github |mkdocs |python

Automatic build and publish documentations on Github Pages

martinpham

Martin Pham

Posted on November 15, 2021

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.

Result

Submission Category: DIY Deployments

Yaml File or Link to Code

GitHub logo 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.

Screenshot

Result

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

Actions used

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.

Config

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


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.
💖 💪 🙅 🚩
martinpham
Martin Pham

Posted on November 15, 2021

Join Our Newsletter. No Spam, Only the good stuff.

Sign up to receive the latest update from our blog.

Related

Automatic build and publish documentations on Github Pages
actionshackathon21 Automatic build and publish documentations on Github Pages

November 15, 2021