{"id":4115,"library":"mkdocs-gen-files","title":"mkdocs-gen-files","description":"mkdocs-gen-files is an MkDocs plugin that allows users to programmatically generate documentation pages and modify existing ones during the MkDocs build process. It's particularly useful for creating dynamic content, API documentation from code, or custom navigation structures using Python scripts. The current version is 0.6.1, and releases are often tied to MkDocs compatibility or feature enhancements, without a strict schedule.","status":"active","version":"0.6.1","language":"en","source_language":"en","source_url":"https://github.com/oprypin/mkdocs-gen-files","tags":["mkdocs","documentation generation","plugin","dynamic content"],"install":[{"cmd":"pip install mkdocs-gen-files","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency as this is a plugin for MkDocs.","package":"mkdocs","optional":false}],"imports":[{"note":"Used within generation scripts to create new documentation files.","symbol":"open","correct":"import mkdocs_gen_files\nwith mkdocs_gen_files.open('path/to/file.md', 'w') as f:"},{"note":"Used within generation scripts to dynamically build the navigation structure, often in conjunction with mkdocs-literate-nav.","symbol":"nav","correct":"from mkdocs_gen_files import nav\nnav['My Section/Page Title'] = 'path/to/file.md'"}],"quickstart":{"code":"### mkdocs.yml\nplugins:\n  - gen-files:\n      scripts:\n        - gen_pages.py\n\n### gen_pages.py\nimport mkdocs_gen_files\n\n# Generate a simple markdown file\nwith mkdocs_gen_files.open(\"generated/example.md\", \"w\") as f:\n    f.write(\"# Hello from mkdocs-gen-files!\\n\\n\")\n    f.write(\"This page was created dynamically at build time.\\n\")\n\n# Optional: Add to navigation (requires mkdocs-literate-nav)\n# from mkdocs_gen_files import nav\n# nav[\"Generated Content/Example\"] = \"generated/example.md\"\n\nprint(\"Successfully generated 'generated/example.md'\")","lang":"python","description":"To use mkdocs-gen-files, first configure it in your `mkdocs.yml` to specify the Python scripts it should run. Then, create a Python script (e.g., `gen_pages.py`) where you can use `mkdocs_gen_files.open` to write content to new documentation pages. The quickstart demonstrates creating a basic markdown file."},"warnings":[{"fix":"Monitor project announcements for `ProperDocs` for future changes. Be prepared for potential migration or changes in build process if full `mkdocs` compatibility diverges.","message":"Starting from v0.6.1, the plugin will issue a warning when used with the `mkdocs` executable. The project maintainers are starting a community continuation under 'ProperDocs', and future compatibility with the original `mkdocs` project might be impacted or require migration.","severity":"breaking","affected_versions":">=0.6.1"},{"fix":"Upgrade to `mkdocs-gen-files` v0.4.0 or newer. Scripts are now correctly resolved relative to the `mkdocs.yml` file, making builds more consistent regardless of CWD.","message":"Prior to v0.4.0, scripts specified in `mkdocs.yml` were resolved relative to the current working directory, not the `mkdocs.yml` file's location. This could lead to scripts not being found when running `mkdocs` from different directories.","severity":"gotcha","affected_versions":"<0.4.0"},{"fix":"Upgrade to `mkdocs-gen-files` v0.6.0 or newer to ensure `set_edit_path()` functions correctly even when `edit_uri_template` is used in your `mkdocs.yml`.","message":"Before v0.6.0, using MkDocs's `edit_uri_template` configuration could prevent `mkdocs_gen_files.set_edit_path()` from correctly applying custom edit URIs to generated files.","severity":"gotcha","affected_versions":"<0.6.0"},{"fix":"Upgrade to `mkdocs-gen-files` v0.5.0 or newer. Cleanup now occurs after all other plugins (on MkDocs 1.4+), ensuring better compatibility with other plugins that might access generated files.","message":"Before v0.5.0 (on MkDocs 1.4+), the temporary directory used by `mkdocs-gen-files` for generated files might have been cleaned up too early, potentially affecting other plugins that expect these files to persist during the build process.","severity":"gotcha","affected_versions":"<0.5.0"},{"fix":"Use `mkdocs_gen_files.set_edit_path(file, 'custom/path/to/edit.md')` within your generation script to explicitly define the edit URI for generated files, or `set_edit_path(file, None)` to explicitly remove it.","message":"Beginning with v0.3.0, generated files no longer have an `edit_uri` by default. If you relied on MkDocs's default `repo_url` based edit links for generated content, they will disappear.","severity":"gotcha","affected_versions":">=0.3.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}