mkdocs-same-dir

What it is and what it does

mkdocs-same-dir is a plugin for ProperDocs that relaxes the normal directory layout constraint, allowing you to place your properdocs.yml configuration file in the same directory as your documentation files instead of requiring it to live in a parent directory. This simplifies project structure for documentation-heavy repositories where you want the config and content colocated.

The plugin works by monkeypatching ProperDocs' internals to permit docs_dir to be set to `.` (the current directory). A key side effect is that non-Markdown files at the root of the docs directory are no longer picked up automatically—only Markdown files are included. The maintainer has committed to keeping the plugin compatible with ProperDocs updates, though the implementation's reliance on internal patching means compatibility cannot be guaranteed indefinitely.

Use it for:

• Organizing documentation projects where config and content live together in a single directory for simpler repository structure.
• Migrating existing documentation layouts to colocate properdocs.yml with markdown files without restructuring the entire docs folder.
• Building documentation sites where the configuration file is version-controlled alongside the documentation it describes.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A ProperDocs plugin that allows placing the properdocs.yml configuration file in the same directory as your documentation files, rather than requiring it to be in a separate parent directory.

Yes, if you use ProperDocs and want to colocate properdocs.yml with your docs directory. The plugin is actively maintained, has no known vulnerabilities, and carries a permissive MIT license. The main trade-off is the monkeypatch approach—it works reliably today but depends on the maintainer tracking ProperDocs changes. Suitable for projects where this layout simplification justifies that dependency.

Install

mkdocs-same-dir on PyPI

pip install mkdocs-same-dir

uv add mkdocs-same-dir

poetry add mkdocs-same-dir

Installing mkdocs-same-dir

Before you install

Low install friction with a pure Python wheel. Actively maintained as of 2026-04-17 with recent activity. Depends only on mkdocs and properdocs, both standard documentation tools.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

pip install mkdocs-same-dir

# In properdocs.yml (placed in your docs directory):
site_name: foo
docs_dir: .
site_dir: ../site

plugins:
  - search
  - same-dir

Requires ProperDocs to be installed and configured; the plugin monkeypatches ProperDocs internals and may break with major ProperDocs updates.

Verify before relying

• Whether the monkeypatch approach remains compatible with future ProperDocs versions beyond the maintainer's stated commitment.
• Performance implications when docs_dir is set to the root directory with many non-Markdown files present.

Package facts

Evidence: mkdocs_same_dir-0.1.5-py3-none-any.whl

Keywords: mkdocs, mkdocs-plugin, properdocs

Tags

More Documentation packages