mhausenblasmhausenblas
271

Mkdocs Deploy Gh Pages

screenshot of Mkdocs Deploy Gh Pages

GitHub Action to deploy an MkDocs site to GitHub Pages

Github

Overview

If you're looking to streamline the deployment of your MkDocs site to GitHub Pages, this GitHub Action is an essential tool. Designed to work seamlessly with the Material theme, it automates the entire deployment process, assuming that your configuration file (mkdocs.yml) is located in your repository's top-level directory and that your source files reside in the docs/ folder. With straightforward setup instructions, you can have your documentation live on the web in no time.

This action provides flexibility in how you authenticate, offering two methods: using a personal access token or the automatically generated GITHUB_TOKEN. Whether you're managing a personal project or coordinating with a team, this tool accommodates various deployment scenarios, making it a robust addition to your development toolkit.

Features

  • Easy Deployment: Simplifies the process of deploying MkDocs sites directly to GitHub Pages with minimal configuration.

  • Two Authentication Methods: Choose between using a PERSONAL_TOKEN for broader access or the more secure GITHUB_TOKEN for repo-specific operations.

  • Custom Domains: Supports deploying with a custom domain by specifying a CUSTOM_DOMAIN variable, automatically creating a CNAME file in the appropriate directory.

  • Flexible File Pathing: Allows customization of file paths using a CONFIG_FILE environment variable, catering to various project structures.

  • Support for Extra Packages: Facilitates the installation of additional Python packages that may be required during the build process through the EXTRA_PACKAGES variable.

  • Integration with GitHub Actions: Leverages the built-in GitHub Actions framework for seamless and efficient deployment workflows.

  • Github Enterprise Compatibility: For enterprise users, the GITHUB_DOMAIN variable can be used to specify a custom GitHub Enterprise domain.

  • User-Friendly Setup: Clear instructions for enabling GitHub Pages and necessary permissions ensure that even newcomers can set up the action without hassle.