mkdocs-build-cache-plugin 0.1.0

MkDocs plugin to check if a build is necessary by hashing configuration and documentation files.

MkDocs Build Cache Plugin

A simple MkDocs plugin to cache build outputs and skip rebuilds when nothing has changed. This plugin computes a unique hash based on your MkDocs configuration and source files, and only triggers a rebuild when changes are detected.

Features

• Build Caching: Saves a cache file (build_cache.json) that stores a hash of the build configuration and source files.
• Skip Unnecessary Rebuilds: If the computed hash matches the cache file from a previous build, the plugin will skip the rebuild process.
• Seamless MkDocs Integration: Built as a standard MkDocs plugin that hooks into the on_config and on_post_build events.

Installation

pip install mkdocs-build-cache-plugin

Usage

1. Configure MkDocs: In your mkdocs.yml, add the plugin to your plugins list:

   plugins:
     - search
     - build-cache
   

2. Run MkDocs: When you run mkdocs build, the plugin will compute a cache ID based on your configuration and documentation files. If nothing has changed since the last build, the plugin will log a message and skip the rebuild.

How It Works

• on_config: During the configuration phase, the plugin computes a SHA-256 hash of your MkDocs configuration and the content of all files in the docs_dir.

  • If a cache file (build_cache.json) exists and its stored hash matches the computed hash, the plugin raises a BuildCacheAbort exception to skip the build.
  • Otherwise, it sets the build_cache_id in the configuration.

• on_post_build: After a successful build, the plugin writes the computed hash to build_cache.json for future comparisons.

Development and Testing

The project uses pytest for testing. To run the tests:

1. Install the development dependencies:

   pip install -r requirements/dev.txt
   

2. Run the tests:

   pytest
   

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/my-new-feature).
3. Commit your changes (git commit -am 'Add new feature').
4. Push to the branch (git push origin feature/my-new-feature).
5. Create a new Pull Request.

License

This project is licensed under the MIT License.

Acknowledgments

• MkDocs for the excellent static site generator.