Skip to content

Redesigning Docs Websites

The documentation of my projects is Open Source and managed by Material for MkDocs.

All projects will have in future days their own GitHub repository documentation accessible at https://llaville.github.io/<project_name>

Documentation websites are hosted by Github Pages

After many search, and read article Custom GH Pages deploys made easy, I've adopted the peaceiris/actions-gh-pages GitHub Action.

Similar articles

My Workflow

Build steps

  • The first part of the workflow (<1>, <2>, <3>) set up environment to builds the site.
  • The second part of the workflow (<4>) builds the site contents.
  • The last part of the workflow (<5>) deploy the site on gh-pages branch of the repository.

<1> Checkout Project Source Code. 

-   # Git Checkout
    name: Checkout Code
    uses: actions/checkout@v2
    with:
        persist-credentials: false

<2> Set up your GitHub Actions workflow with a specific version of python. 

-   # Setup Python version
    name: Set up Python runtime
    uses: actions/setup-python@v2
    with:
        python-version: 3.x

<3> Install Material for MkDocs with pip. 

-   # Install Material for MkDocs
    name: Install Material for MkDocs
    run: pip install mkdocs-material

<4> Build documentation with MkDocs one of the most famous static site generators 

-   # Build Documentation
    name: Build Docs
    run: mkdocs build

<5> Deploy documentation to Github Pages 

-   # Deploy Documentation
    name: Deploy Docs
    if: ${{ github.ref == 'refs/heads/master' }}
    uses: peaceiris/actions-gh-pages@v3
    with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./site
        full_commit_message: "Deployed ${{ github.sha }} with MkDocs"
        force_orphan: true
        user_name: 'github-actions[bot]'
        user_email: 'github-actions[bot]@users.noreply.github.com'

Back to top