Deploy a MkDocs-based static website to GitHub Pages.
This is the version of the workflow for projects using the Poetry dependency management tool.
Install the deploy-mkdocs-poetry.yml GitHub Actions workflow to .github/workflows/
mkdocs.yml- base MkDocs configuration file.- Install to: repository root
icon_mac_light.png- Arduino logo for the website. NOTE: only for use in official Arduino projects. Community projects should use the Community Logo.- Install to:
docs/img/
- Install to:
The website build dependencies are managed by Poetry.
Install Poetry by following these instructions:
https://python-poetry.org/docs/#installation
If your project does not already use Poetry, you can initialize the pyproject.toml file using these commands:
poetry init --python="^3.9" --dev-dependency="mkdocs@^1.2.1" --dev-dependency="mkdocs-material@^7.2.8" --dev-dependency="mdx_truly_sane_lists@^1.2"
poetry install
If already using Poetry, add the tool using this command:
poetry add --dev "mkdocs@^1.2.1" "mkdocs-material@^7.2.8" "mdx_truly_sane_lists@^1.2"
Commit the resulting pyproject.toml and poetry.lock files.
The workflow is configured for repositories that host the website source content in a branch named main. If the project uses a different branch, adjust the on.push.branches[] value in deploy-mkdocs-poetry.yml.
Fill in all blank field in mkdocs.yml with the project-specific information.
Add entries for each website source file to the nav array in mkdocs.yml, or remove nav to have MkDocs auto-generate the navigation panel.
Reference: https://www.mkdocs.org/user-guide/configuration/
Markdown badge:
[](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/deploy-mkdocs-poetry.yml)Replace the REPO_OWNER and REPO_NAME placeholders in the URLs with the final repository owner and name (example).
Asciidoc badge:
image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-mkdocs-poetry.yml/badge.svg["Deploy Website status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-mkdocs-poetry.yml"]Define the {repository-owner} and {repository-name} attributes and use them throughout the readme (example).
Add CI workflow to deploy a MkDocs-based website to GitHub Pages
On every push to the repository's default branch, deploy the repository's MkDocs-based static website to GitHub Pages.
On every push to the repository's default branch, deploy the repository's [MkDocs](https://www.mkdocs.org/)-based static website to [GitHub Pages](https://pages.github.com/).