oprypin / mkdocs-same-dir

MkDocs plugin to allow placing mkdocs.yml in the same directory as documentation

mkdocs-same-dir

Plugin for MkDocs to allow placing mkdocs.yml in the same directory as documentation

pip install mkdocs-same-dir

Usage

Activate the plugin in mkdocs.yml, along with actually changing docs_dir
(normally, MkDocs absolutely wouldn't let you set it to .):

site_name: foo
docs_dir: .
site_dir: ../site

plugins:
  - search
  - same-dir

and now you can move this mkdocs.yml into your docs directory, or move your docs alongside mkdocs.yml.

See example layout

Important notes

Another necessary effect of this plugin is that files directly at the root of the docs dir will no longer be picked up, unless they are Markdown files.

And note that the implementation of this plugin is a huge hack that monkeypatches MkDocs' internals. But I pledge to keep up with MkDocs updates and keep it working as long as that's still possible.

mkdocs-same-dir's Issues

Release new version

Hi,
I added a change in #2. Could you please create a new release on pypi?

Not working for latest mkdocs 1.4.0

Title says it all! Thanks for the great package.

Ensure that CNAME file is copied into build

Hello,

Thanks for your work on this

I see from the readme that any files in the root won't be picked up except for markdown files. This prevents deploying to GitHub pages under a custom domain. Is there a way to ensure that the CNAME file is also picked up?

Feature request: Correct "edit this page" button when `repo_url` is set

The "Edit this page" button currently displayed on the generated docs page when repo_url is set in mkdocs.yml is not linking to the correct page when mkdocs-same-dir is in use.

For instance, if the URL is https://github.com/org/repo/edit/master/docs/README.md, the button currently links to https://github.com/org/repo/edit/master/README.md. This feature request is for the plugin to patch the button to link to the actual URL, instead of the one containing docs/.

If this is a desired feature, I can probably pull some time to work on it in the next few weeks.

Regression with mkdocstrings>=23.0.0 dependency

Hello, thanks for this wonderful plugin!

I noticed my doc builds started failing whenever mkdocstrings was upgraded to 0.24.0. If I upgrade this package in my environment, the same-dir plugin fails with the following message:

  File ".../mkdocs_same_dir/plugin.py", line 40, in _replace_validation
    config["docs_dir"] = os.path.join(config["docs_dir"], ".")
                                      ~~~~~~^^^^^^^^^^^^
KeyError: 'docs_dir'

Thought I'd report this here for now since I'm not sure how another plugin would interfere with this one. For now I simply pin mkdocstrings to 0.23.0

Plugin interfering with relative paths relative to --config-file

It appears that this plugin might be breaking the standard mkdocs behavior of evaluating paths in the config file relative to the file. If I do something like mkdocs build --config-file=docs/mkdocs.yaml, I get errors that my various configs don't exist:

ERROR   -  Config value 'theme': The path set in custom_dir ('docs/theme') does not exist.
ERROR   -  Config value 'watch': The path 'docs/theme/' isn't an existing file or directory.

The config file uses the relative path theme in both places, and the printed paths do exist relative to cwd.