Simple check/command-line tool that parses, validates and loads configuration, builds the mkdocs project documentation, and serves it via a web server
Project description
check-mkdocs
Check if MkDocs is configured correctly
This is a simple .pre-commit-config.yaml hook to check if MkDocs is configured correctly.
Installation via Pip
You can install this tool via pip:
pip install check-mkdocs
Local Installation
This tool is packaged with Poetry. To install it, you can clone the repository and use Poetry to install the dependencies:
git clone https://github.com/RodrigoGonzalez/check-mkdocs.git
cd check-mkdocs
poetry install
Features
- Validates the MkDocs configuration file (default is
mkdocs.yml
). - Builds the MkDocs project documentation via
mkdocs build
. - Checks the built documentation via
mkdocs serve
. - Can be used as a pre-commit hook.
- Optionally, it can generate a build of the MkDocs documentation.
Documentation: https://rodrigogonzalez.github.io/check-mkdocs/
Pre-Commit Usage
Add this to your .pre-commit-config.yaml
, where mkdocs.yml
is the name of your MkDocs YAML configuration file:
repos:
- repo: https://github.com/RodrigoGonzalez/check-mkdocs
rev: v1.2.0
hooks:
- id: check-mkdocs
name: check-mkdocs
args: ["--config", "mkdocs.yml"] # Optional, mkdocs.yml is the default
# If you have additional plugins or libraries that are not included in check-mkdocs, add them here
additional_dependencies: ['mkdocs-material']
Command-Line Usage
To run this hook, you can use the following command:
check-mkdocs --config=mkdocs.yml
This works as well:
check-mkdocs mkdocs.yml
And if mkdocs.yml
is the name of your MkDocs YAML
configuration file, this works too:
check-mkdocs
These commands will validate the MkDocs configuration file, build the project documentation, and start the server. If there's an error in any of these steps, the tool will print an error message and return an error code.
The --generate-build
Argument
The --generate-build
argument is a command-line flag that
you can use to instruct the check_mkdocs tool to generate a
build of the MkDocs documentation. This argument is
optional, and its default value is False, which means that
by default, the tool will not generate a build.
When you provide this argument, the tool will call the
build function from mkdocs.commands.build with the loaded
configuration. This function will build the project
documentation and place the built documentation in the
site_dir
directory specified in the configuration. If the
site_dir
directory is not specified in the configuration,
the tool will use the MkDocs default location as the
site_dir
(i.e., site/
).
Here's how you can use this argument:
check-mkdocs --config=mkdocs.yml --generate-build
This command will validate the MkDocs configuration file, build the project documentation, and start the server. If there's an error in any of these steps, the tool will print an error message and return an error code.
Known Issues
Missing MkDocs Plugins
Given the enormous number of plugins available for MkDocs, it's possible that some plugins are not included in this tool. In this case you will see an error message similar to this:
check-mkdocs.............................................................Failed
- hook id: check-mkdocs
- exit code: 1
Config value 'theme': Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs
Config value 'markdown_extensions': Failed to load extension 'pymdownx.snippets'.
ModuleNotFoundError: No module named 'pymdownx'
Config value 'plugins': The "mkdocstrings" plugin is not installed
make: *** [pre-commit] Error 1
If you have additional plugins or libraries that are not included in check-mkdocs, add them here:
repos:
- repo: https://github.com/RodrigoGonzalez/check-mkdocs
hooks:
- id: check-mkdocs
# If you have additional plugins or libraries that are not included in check-mkdocs, add them here
additional_dependencies: ['mkdocs-material', 'mkdocstrings']
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for check_mkdocs-1.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6abde740e4357a97a75aea0fcf12f654d2777538f9a9d2be5262664439eeb3ae |
|
MD5 | e76b05c1e8c8ad77994518cd2443c09c |
|
BLAKE2b-256 | a81230b7823228f156e85ec786845f2decaae2d256e5024bea56a923d4d0d73b |