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.3.0" --dev-dependency="mkdocs-material@^8.2.11" --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.3.0" "mkdocs-material@^8.2.11" "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.
Replace all TODO_* placeholders 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/TODO_REPO_OWNER/TODO_REPO_NAME/actions/workflows/deploy-mkdocs-poetry.yml)Replace the TODO_REPO_OWNER and TODO_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 the following to the project's development documentation (templates available here):
## Documentation
The [Markdown](https://www.markdownguide.org/basic-syntax/) files under the `docs` subfolder of the repository are the source content for the project's documentation website.
When working on the documentation, it may be useful to see the effect the changes will have on the generated documentation website. You can build the documentation website and serve it from your personal computer by running this command from the project root:
```text
task website:serve
```
The website will now build. If you don't see any error, open `http://127.0.0.1:8000` in your browser to load the local copy of the documentation site.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/).