Paths are relative to you, not the config file

[d0ugal]

You can do mkdocs build --config-file=path/to/mkdocs.yml but any configuration values in that file are relative to your current working directory.

This seems wrong to me, but it's only something I've ran into when trying to automate MkDocs builds (for integration testing). I'm not sure if we want to change this, or what people really expect. The common use case is that you are in the same directory as the config file anyway, so that doen't matter.

Something like this should be changed or at least decided for a 1.0 release.

Thoughts?

[waylan]

I think that is a reasonable compromise. Not sure when I would want to point to a config file in a different location anyway. If I had multiple config files for one project, they would most likley be side-by-side in the root of the project anyway:

./docs/
./default.yml
./experimental.yml

Or I suppose the various config files could be in a subdir:

./docs/
./mkdocs_cfg/default.yml
./mkdocs_cfg/experimental.yml

Either way, I would be calling the mkdocs command from the project root. Therefore, it seems logical that all paths in the config would be relative to the cwd. Besides, if I rearranged my file structure from one to the other, I would not want to have to edit each file to alter the paths.

When automating doc builds (in a tox config or from a make file) one may need to cd into the project root before building, but that is nothing unusual (and good practice anyway).

Maybe the commands could accept a --project_root option which defaults to the cwd. That might address the few edge cases where someone is not calling a command from the project root. But is seems unnecessary to me.

[d0ugal]

Okay, fair point. I mostly wanted to raise this and have some sort of record of it. I think I agree, so, closing this for now :)

[jimporter]

Not sure when I would want to point to a config file in a different location anyway.

The case I care about (from issue #676) is when performing out-of-tree builds. I treat my build system as a toolbox of commands, and being able to run make doc (from the build dir, of course) is nice. The main reason I use out-of-tree builds is to make it easy to keep the build files for multiple build configs around (e.g. a clang build vs a gcc build).

While MkDocs itself is unlikely to benefit from from out-of-tree builds, it means that for my projects, I'm either forced to run mkdocs directly[1] or handle cding into the source dir to build the docs. Neither is particularly convenient, and I think the stated benefit (being able to put your mkdocs.yml file in a subdir without changing the relative paths) is of dubious merit. In fact, not knowing about this behavior, I'd probably end up changing the relative paths and then have to change them back when I found out that that's not what MkDocs expected.

[1] Which is more typing, since I prefer to use --clean and activate my MkDocs virtualenv in-line.

[d0ugal]

Yeah, so it is interesting that you hit this when doing automation like I did. I think we should try and fix this, I can't really see how the paths being relative to the user makes sense. Personally, I found it really easy to work around, I don't think it is that hard, but the fact that the config essentially changes as you move around the file-system is weird.

I think for this to work well, we would need to join each config option with the path to the mkdocs yaml when we do all the config processing in https://github.com/mkdocs/mkdocs/blob/master/mkdocs/config/config_options.py

[lovelydinosaur]

Just agreeing that I think this is a valid issue