When config file is stdin mkdocs serve reload appears unrecoverably to crash #3972
Description
Description of bug
When config file is stdin (mkdocs serve -f -), mkdocs cannot refresh edited files. This is because each reload it attempts to re-read stdin but stdin is finished. I would like it to reuse the previous config provided by stdin. I think it's acceptable that if you're using stdin for config you don't get to automatically reflect changes to mkdocs.yaml.
When editing docs with vim mkdocs appears to crash because it encounters unexpected binary files created by vim during the editing process.
I have to cancel mkdocs and restart it for it to generate documentation again. Or shutdown mkdocs, edit with vim, exit vim, and then run mkdocs. I was hoping to #1500 exclude vim files. Ideally, this would be a mkdocs CLI option (see my usage at the bottom) to ignore file patterns.
Example "dirty" files that show up in docs directory because of vim. If I edit vim docs/index.md, then a binary file named .index.md.swp gets created.
Example stacktrace
Traceback (most recent call last):
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/livereload/__init__.py", line 211, in _build_loop
self.builder()
~~~~~~~~~~~~^^
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/commands/serve.py", line 64, in builder
config = get_config()
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/commands/serve.py", line 43, in get_config
config = load_config(
config_file=config_file,
site_dir=site_dir,
**kwargs,
)
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/config/base.py", line 360, in load_config
with _open_config_file(config_file) as fd:
~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
File "/opt/homebrew/Cellar/python@3.13/3.13.1/Frameworks/Python.framework/Versions/3.13/lib/python3.13/contextlib.py", line 141, in __enter__
return next(self.gen)
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/config/base.py", line 324, in _open_config_file
raise exceptions.ConfigurationError(f"Config file '{paths_to_try[0]}' does not exist.")
mkdocs.exceptions.ConfigurationError: Config file '<stdin>' does not exist.
ERROR - [22:47:44] An error happened during the rebuild. The server will appear stuck until build errors are resolved.
INFO - [22:47:51] Detected file changes
INFO - Building documentation...
Traceback (most recent call last):
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/livereload/__init__.py", line 211, in _build_loop
self.builder()
~~~~~~~~~~~~^^
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/commands/serve.py", line 64, in builder
config = get_config()
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/commands/serve.py", line 43, in get_config
config = load_config(
config_file=config_file,
site_dir=site_dir,
**kwargs,
)
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/config/base.py", line 360, in load_config
with _open_config_file(config_file) as fd:
~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
File "/opt/homebrew/Cellar/python@3.13/3.13.1/Frameworks/Python.framework/Versions/3.13/lib/python3.13/contextlib.py", line 141, in __enter__
return next(self.gen)
File "/Users/sgleske/.techdocs/python3/lib/python3.13/site-packages/mkdocs/config/base.py", line 324, in _open_config_file
raise exceptions.ConfigurationError(f"Config file '{paths_to_try[0]}' does not exist.")
mkdocs.exceptions.ConfigurationError: Config file '<stdin>' does not exist.
ERROR - [22:47:51] An error happened during the rebuild. The server will appear stuck until build errors are resolved.
^CINFO - Shutting down...
Environment
# macOS 14.1 23B2073
# Darwin 23.1.0 arm64
# GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
$ python --version
Python 3.13.1
pip freeze output from python3 virtualenv.
babel==2.17.0
certifi==2025.1.31
charset-normalizer==3.4.1
click==8.1.8
colorama==0.4.6
ghp-import==2.1.0
griffe==1.6.0
idna==3.10
Jinja2==3.1.6
Markdown==3.7
markdown_graphviz_inline==1.1.3
MarkupSafe==3.0.2
mdx-truly-sane-lists==1.3
mergedeep==1.3.4
mkdocs==1.6.1
mkdocs-autorefs==1.4.1
mkdocs-gen-files==0.5.0
mkdocs-get-deps==0.2.0
mkdocs-material==9.6.5
mkdocs-material-extensions==1.3.1
mkdocs-monorepo-plugin==1.1.0
mkdocs-redirects==1.2.2
mkdocs-same-dir==0.1.3
mkdocs-techdocs-core==1.5.3
mkdocstrings==0.28.2
mkdocstrings-python==1.16.2
packaging==25.0
paginate==0.5.7
pathspec==0.12.1
plantuml-markdown==3.11.1
platformdirs==4.3.7
Pygments==2.19.1
pymdown-extensions==10.14.3
python-dateutil==2.9.0.post0
python-slugify==8.0.4
PyYAML==6.0.2
pyyaml_env_tag==0.1
regex==2024.11.6
requests==2.32.3
six==1.17.0
text-unidecode==1.3
urllib3==2.4.0
watchdog==6.0.0
How I'm calling mkdocs
mkdocs_config() {
cat <<EOF
$(cat mkdocs.yml)
# https://github.com/backstage/mkdocs-techdocs-core/blob/58da52411a8f55e9afdc11dd9694897534058310/README.md#mkdocs-plugins-and-extensions
# https://github.com/backstage/mkdocs-techdocs-core/blob/58da52411a8f55e9afdc11dd9694897534058310/techdocs_core/core.py#L101-L201
plugins:
- search:
pipeline:
- stemmer
- stopWordFilter
- trimmer
- techdocs-core:
use_material_search: true
use_pymdownx_blocks: true
EOF
}
mkdocs_config | \
mkdocs serve -f - -a "${TECHDOCS_HOST}:${TECHDOCS_PORT}" -t material "$@"