Package: hatch-mkdocs
hatch-mkdocsHatchplugin to integrateMkDocsand infer dependencies into an envThis plugin populatesHatchenvironments withdependencieson the fly based on amkdocs.ymlfile.This is intended to effortlessly manage dependencies for a MkDocs site.You just need to add this minimal config to Hatch, along with any existing MkDocs config:hatch.tomlmkdocs.yml[env]requires=["hatch-mkdocs",][env.collectors.mkdocs.docs]path="mkdocs.yml"site_name:MkDocs exampleplugins:-autorefsmarkdown_extensions:-callouts-pymdownx.superfencesThis gets you the following implied Hatch configuration: (click to expand)hatch.toml[envs.docs]detached=truedependencies=["markdown-callouts","mkdocs","mkdocs-autorefs","pymdown-extensions",][envs.docs.scripts]build="mkdocs build -f mkdocs.yml {args}"serve="mkdocs serve -f mkdocs.yml {args}"gh-deploy="mkdocs gh-deploy -f mkdocs.yml {args}"(this is just for posterity, no such config is actually written to a file)With this:You don't need to specify the PyPI dependencies, they get inferred on the fly just frommkdocs.ymlby doing a reverse lookup of MkDocs plugins in thecatalog, usingmkdocs get-deps. (See more details there)An automatically managed virtual environment with pre-defined MkDocs commands is at your fingertips.You can check this yourself:hatch env show docsStandalone                     
┌──────┬─────────┬────────────────────┬───────────┐
│ Name │ Type    │ Dependencies       │ Scripts   │
├──────┼─────────┼────────────────────┼───────────┤
│ docs │ virtual │ markdown-callouts  │ build     │
│      │         │ mkdocs             │ gh-deploy │
│      │         │ mkdocs-autorefs    │ serve     │
│      │         │ pymdown-extensions │           │
└──────┴─────────┴────────────────────┴───────────┘The dependencies get resolved and installed into a virtual environment as part of a Hatch invocation. So, you can directly run:hatch run docs:buildCreating environment: docs
Checking dependencies
Syncing dependencies
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: site
INFO    -  Documentation built in 0.03 seconds(If you've been using virtualenvs directly, this single command replaces creating an environment, installing dependencies into it, as well as runningmkdocsin it, optionally with arguments)Furthermore, whenever the set of dependencies changes (i.e. you select new MkDocs plugins), these Hatch commands will re-install dependencies as necessary.Otherwise, the environment is just reused; the installation happens only on the first invocation.If at any point you want to make sure the dependencies are re-installed anew, you can just remove the environment:hatch env remove docsRemoving environment: docsInstallationJustinstall Hatch. Ideally in an isolated way withpipx install hatch, or justpip install hatchas a more well-known way.If you declarehatch-mkdocsas a dependency in your Hatch config (pyproject.tomlorhatch.toml) as shown above, Hatch will automatically install it on first use.Alternatively you can install it manually:pipx inject hatch hatch-mkdocsor justpip install hatch-mkdocs.And donotinstall MkDocs - it's unnecessary, only the sub-environments will have it.ConfigurationNote that although Hatch is typically associated with managing entire Python projects and applications, youcanuse it purely for environment management for a MkDocs site - through this plugin, or even without it.Hatch can be configured through one of two files -hatch.tomlorpyproject.toml. Configs in the latter are equivalent but will always need a[tool.hatch...]prefix; it can be used if you have an existing Python project and you don't want to add another config file.So, add the following into one of the files:hatch.tomlpyproject.toml[env]requires=["hatch-mkdocs",][env.collectors.mkdocs.ENV_NAME]path="path/to/mkdocs.yml"[envs.ENV_NAME]...[tool.hatch.env]requires=["hatch-mkdocs"][tool.hatch.env.collectors.mkdocs.ENV_NAME]path="path/to/mkdocs.yml"[tool.hatch.envs.ENV_NAME]...Here,[env.collectors.mkdocs.ENV_NAME]means: please populate an environment named "ENV_NAME" based on an MkDocs config. In that section,pathis the path tomkdocs.yml.At the moment that is the entire configurability of this plugin.In the first example we used "docs" as the environment name, you can use "mkdocs" as well if you like, or anything else. Further, if you use "default" as the name (which you might do if documentation building is all that you'll ever use Hatch for) then you can skip the environment prefix (docs:in the above example).Multiple separate environments with their own configs and dependencies can be populated as well.Inside[envs.ENV_NAME](which is an ordinary construct in Hatch) you can proceed to further customize the environment (though normally it shouldn't be necessary, and the section can be omitted from the text config): you can add extradependenciesorscripts, or any other environment config. You could also setdetachedback tofalseif the documentation actually relies on the project itself being installed, such as in the case ofmkdocstrings.