Windows: Generator.py: subprocess.run(cmd, check=True) problem

[jccrEquinor]

Bug: npx/likec4 command not found on Windows within python, local, virtual environment

Summary

The plugin fails on Windows with the following error during mkdocs serve or mkdocs build:

ERROR - mkdocs-likec4: 'npx' or 'likec4' command not found. Ensure Node.js and likec4 are installed.

This occurs even when Node.js and npx are correctly installed and available on the system PATH.

Root Cause

In generator.py, the subprocess call uses a list-form command:

subprocess.run(cmd, check=True)

Fix

Add shell=True to the subprocess.run call in generator.py (line 68):

# Before fix
subprocess.run(cmd, check=True)

# After fix
subprocess.run(cmd, check=True, shell=True)

This allows Windows to resolve .cmd files correctly, and has no adverse effect on Linux or macOS.

Environment

• OS: Windows
• Node.js: v25.9.0
• npx: v11.12.1
• Python virtual environment (venv)
• mkdocs-likec4: latest

Steps to Reproduce

1. Install mkdocs-likec4 on Windows
2. Configure a LikeC4 project with a valid likec4.config.json
3. Run mkdocs serve
4. Observe the error even with Node.js correctly installed

Current Workaround

Manually edit generator.py in the installed package to add shell=True as described above.

[jonas-haeusler]

hi @jccrEquinor, thanks for the report!

afaik, shell=True parses the arg list inconsistent across platforms.
a cleaner fix could be to detect the npx binary via shutil.which("npx") or the likes.

happy to review an MR if you want to take a shot at it!