Missing documentation on installing Mkdocs development version dependencies

I can’t find any information in the documentation about installing the necessary dependencies for Mkdocs.

With Python 3.10.6 in a fairly standard Ubuntu 22.04 WSL environment I had to install the following dependencies after running pip install --editable . to be able to run mkdocs serve:

pip install markdown pymdown-extensions markdown-callouts mdx-gh-links \
    mkdocs-{redirects,click,autorefs,literate-nav} mkdocstrings[python]

Is there a more obvious way? hatch env docs also doesn’t work in my case, at least. When I enter the environment ant run mkdocs serve, the output is:

ERROR    -  Config value 'markdown_extensions': Failed to load extension
            'pymdownx.highlight'.
            ModuleNotFoundError: No module named 'pymdownx'
ERROR    -  Config value 'plugins': The "redirects" plugin is not installed
Aborted with 2 Configuration Errors!

If there is a way that would work across different setups, I’d be happy to add it to the documentation.

Issue Analytics

State:
Created a year ago
Comments:9 (9 by maintainers)

Top GitHub Comments

1reaction

pcgaustadcommented, Oct 29, 2022

To build docs (installs deps implicitly): hatch run docs:mkdocs serve

Thanks! Another way would be hatch -e docs shell, it seems,

1reaction

oprypincommented, Oct 29, 2022

You’re right that this isn’t documented in our repo 😕

To build docs (installs deps implicitly): hatch run docs:mkdocs serve

To learn about the dependencies: hatch env show hatch env show docs

Click to expand
hatch env show --json | jq -r ".docs.dependencies | .[]"

Markdown >=3.3.3
mdx_gh_links >=0.2
markdown-callouts >=0.3.0
mkdocs-literate-nav >=0.5.0
mkdocs-redirects >=1.0.1
pymdown-extensions >=8.0.1
mkdocstrings-python >=0.7.1
mkdocs-click >=0.8.0

To roll with your own dependency installation method: hatch env show --json | jq -r ".docs.dependencies | .[]" > docs.requirements.txt pip install -r docs-requirements.txt

(cc @ofek I really wish this didn’t require jq)

Top Results From Across the Web

Release Notes - MkDocs

You can determine your currently installed version using mkdocs --version : ... versions. Please report if this release breaks something.

Support latest realise of Markdown library · Issue #2892 - GitHub

I believe there has been some update to the Markdown library and how it internally records its version that is breaking things.

Getting started - Material for MkDocs - GitHub Pages

This will install all required dependencies like Python and MkDocs. cloning from GitHub¶. Material can also be used without a system-wide installation by ......

Frequently Asked Questions - Read the Docs

For libraries that cannot be installed via apt in the builder there is another way to successfully build the documentation despite missing dependencies....

mkdocs-macros-plugin - Python Package Health Analysis - Snyk

Installation · Prerequisites · Standard installation · "Manual installation" · Development/test installation · Declaration of plugin · Check that it works.