mkdocs-same-dir
ProperDocs plugin to allow placing properdocs.yml in the same directory as documentation
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires ProperDocs to be installed and configured; the plugin monkeypatches ProperDocs internals and may break with major ProperDocs updates.
- Low install friction with a pure Python wheel.
- Actively maintained as of 2026-04-17 with recent activity.
License · maintenance · safety
MIT (permissive) — MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.
last release 2026-04-17 (119 days) · last repo commit 2026-04-17 · 47 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 133,271 downloads/mo, #11,523 on PyPI
Alternatives
Verify before relying
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- 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.
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 on it.
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
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.
Requires ProperDocs to be installed and configured; the plugin monkeypatches ProperDocs internals and may break with major ProperDocs updates.
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-dirVerify 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
| License | MIT permissive |
| Python support | Supports the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 2 packagesmkdocsproperdocs |
| Maintenance | Actively maintained 119 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 133,271 / month, #11,523 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 4 - BetaEnvironment :: ConsoleIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseOperating System :: OS IndependentProgramming Language :: PythonProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Topic :: DocumentationTopic :: Software Development :: DocumentationTyping :: Typed |
Evidence: mkdocs_same_dir-0.1.5-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “mkdocs config same directory”
- mkdocs-same-dirA ProperDocs plugin that allows placing the properdocs.yml…
- mkdocs-multirepo-pluginMerges documentation from multiple Git repositories into a single…
- mkdocs-include-dir-to-navA MkDocs plugin that automatically expands directory references in…
Give your agent the search over MCP, or paste the wish link into any chat.
More Documentation packages
Docutils converts plaintext documentation in reStructuredText format into multiple output formats including HTML, XML, and LaTeX using a modular processing system.
Sphinx generates professional documentation from reStructuredText source files, producing HTML, PDF, EPUB, and other formats with automatic cross-references, code highlighting, and hierarchical navigation.
Griffe extracts the complete structure and signatures of Python programs to generate API documentation or detect breaking changes in your project's public API.
Install it if you need to programmatically inspect Python code structure, generate API docs, or enforce API stability in CI.
A Sphinx extension that outputs documentation in serialized HTML formats (JSON and pickle) alongside standard HTML.
Alabaster is a clean, responsive Sphinx theme for documentation that requires Python 3.10 or newer and Sphinx 6.2 or newer.
A Sphinx extension that generates HTML help files from reStructuredText documentation source.
See also mkdocs-include-markdown-plugin · mkdocs-redirects · mkdocs-multirepo-plugin · mkdocs-monorepo-plugin · properdocs · mkdocs-section-index · mkdocs-literate-nav · mkdocs-include-dir-to-nav · mkdocs-gen-files · mkdocs