Allow docs to be in the root directory

[oprypin]

• Closes Support docs from the root directory. #3450 by @athackst

If the config file is inside docs_dir, you get this message:

ERROR   -  Config value 'docs_dir': The 'mkdocs.yml' config file should not be inside the docs_dir.
           To allow this arrangement, please exclude the file (and other files as applicable) by adding the following configuration:

           exclude_docs: |
             /mkdocs.yml

If the site_dir is inside docs_dir, you get this message:

ERROR   -  Config value 'site_dir': The site_dir should not be inside the docs_dir as this leads to the build directory being copied into itself.
           To allow this arrangement, please exclude the directory (and other files as applicable) by adding the following configuration:

           exclude_docs: |
             /site

[oprypin]

My motivation for this is that the user will be informed about the setting and will take this opportunity to check which other files should perhaps be excluded as well.

[athackst]

I think the site_dir message is good.

I'm not sure I follow what use case you're protecting against to warn against the mkdocs.yml file inside of the docs dir.

Previously mkdocs required the docs dir to be located in a child directory named 'docs', but since you can now specify the config from the command line, I don't believe this is the case any more?

[oprypin]

Well, do people want to publish mkdocs.yml online? Probably not? So how can it be a bad warning. And I am hoping that people will take this opportunity to also exclude all other kinds of files that may be in the root directory of their repository.

[athackst]

Ah, ok. Makes sense then.

[athackst]

Would you consider making it a warning instead of an error?

[oprypin]

Error is closer to the current behavior than no error, so it was the default choice. Currently I don't see strong arguments in either direction. It can always be changed to warning, and could even be changed now, sure. Do you have any use case in mind?

[athackst]

Yeah, if you want to do something like #3526 so excluded docs aren't triggering the reload server but you want to have mkdocs.yml trigger it, you might want to not add it to exclude_docs

[athackst]

Eh, nevermind. I think I found a clean way of handling that case. An error sounds fine to me.

[oprypin]

I didn't merge this because not sure if next maintainers will want to own this code.

[athackst]

Who are the next maintainers?

[pawamoy]

Right now, they are the people in the @mkdocs/core team who have the time and will to work on MkDocs :) As you know it, we're also trying to onboard more people.

[oprypin]

• The actual context is I am stepping down from MkDocs #3621