Skip to main content

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

check_mkdocs-1.2.0.tar.gz (6.5 kB view details)

Uploaded Source

Built Distribution

check_mkdocs-1.2.0-py3-none-any.whl (9.5 kB view details)

Uploaded Python 3

File details

Details for the file check_mkdocs-1.2.0.tar.gz.

File metadata

  • Download URL: check_mkdocs-1.2.0.tar.gz
  • Upload date:
  • Size: 6.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.6.1 CPython/3.11.4 Darwin/22.6.0

File hashes

Hashes for check_mkdocs-1.2.0.tar.gz
Algorithm Hash digest
SHA256 a139d0a0a81feed2bbf1de7bb33a3cedb64b5c6be5d21ce7ff452526fdb729a3
MD5 7a78e3db1eab4feec9d7522837b9371b
BLAKE2b-256 ee4efb199827ceda2affab3a2080014ba7b0e941875b457edccc38d946fa01ac

See more details on using hashes here.

File details

Details for the file check_mkdocs-1.2.0-py3-none-any.whl.

File metadata

  • Download URL: check_mkdocs-1.2.0-py3-none-any.whl
  • Upload date:
  • Size: 9.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.6.1 CPython/3.11.4 Darwin/22.6.0

File hashes

Hashes for check_mkdocs-1.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6abde740e4357a97a75aea0fcf12f654d2777538f9a9d2be5262664439eeb3ae
MD5 e76b05c1e8c8ad77994518cd2443c09c
BLAKE2b-256 a81230b7823228f156e85ec786845f2decaae2d256e5024bea56a923d4d0d73b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page