Skip to main content
Plugins / MkDocs


by Woodpecker Authors

Plugin to build mkdocs sites


Add the following to your woodpecker file's steps section to build docs using the default installation (See Bundled libraries below) and settings of this plugin.
Make sure to replace {version} with the latest release available or with latest for the latest commit made.

  image: woodpeckerci/plugin-mkdocs:{version}

A minimal version without any bundled libraries is offered too. Use the following to use the minimal version:

  image: woodpeckerci/plugin-mkdocs:minimal

Settings can be defined using the settings option for woodpecker plugins. All available settings and their defaults are listed below.


Settings Name Default Description
clean true remove old files from the site_dir before building
site_dir site_dir config option or site directory to output the result of the documentation build, if also not set in config site is used
directory_urls true use directory URLs when building pages
config mkdocs.yml provide a specific MkDocs config
strict false will cause MkDocs to abort the build on any warnings
theme mkdocs theme to use when building your documentation (mkdocs or readthedocs). Other themes need to be installed manually using pip_install
verbose false enable verbose mode
pip_install_file none Add a file to install dependencies from using pip install -r <file> before mkdocs is exec
pip_install none Add comma separated packages to be installed by pip before mkdocs is exec

Bundled libraries

The plugin base is squidfunk/mkdocs-material. For all the non-minimal images, the following additional dependencies are bundled:

  • mkdocs-enumerate-headings-plugin
  • mkdocs-git-authors-plugin
  • mkdocs-git-revision-date-localized
  • mkdocs-glightbox
  • mkdocs-print-site-plugin