mkdocs-gen-files

0.6.1 · active · verified Sat Apr 11

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.

Warnings

breaking 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.
Fix: Monitor project announcements for `ProperDocs` for future changes. Be prepared for potential migration or changes in build process if full `mkdocs` compatibility diverges.
gotcha 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.
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.
gotcha 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.
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`.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install mkdocs-gen-files Install latest version

Imports

open

import mkdocs_gen_files
with mkdocs_gen_files.open('path/to/file.md', 'w') as f:

Used within generation scripts to create new documentation files.

nav
```
from mkdocs_gen_files import nav
nav['My Section/Page Title'] = 'path/to/file.md'
```
Used within generation scripts to dynamically build the navigation structure, often in conjunction with mkdocs-literate-nav.

Quickstart

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.

### mkdocs.yml
plugins:
  - gen-files:
      scripts:
        - gen_pages.py

### gen_pages.py
import mkdocs_gen_files

# Generate a simple markdown file
with mkdocs_gen_files.open("generated/example.md", "w") as f:
    f.write("# Hello from mkdocs-gen-files!\n\n")
    f.write("This page was created dynamically at build time.\n")

# Optional: Add to navigation (requires mkdocs-literate-nav)
# from mkdocs_gen_files import nav
# nav["Generated Content/Example"] = "generated/example.md"

print("Successfully generated 'generated/example.md'")

view raw JSON →