mkdocs.yml location

[dfee]

my repo has multiple components, including:

• docs
• api
• client
• {quite a few others}

I'd prefer to put my mkdocs.yml in my /docs dir. But I get this complaint:

ERROR   -  Config value: 'docs_dir'. Error: The 'docs_dir' should not be the parent directory of the config file. Use a child directory instead so that the config file is a sibling of the config file.

I'm not sure I agree with this. What's the reasoning behind this?

[waylan]

I thought this was discussed clearly elsewhere but I can't find it. However, there are some relevant (and lengthy) discussions in #543 and #610. Also, see #972, which was a bug encountered by a user because this policy was not always enforced as strictly as it is today.

To answer the question directly, I'll point out that the root if a project often contains all sorts of config files (makefile, .gitignore, .gitattributes, .travis.yml, .coveragerc etc...). Seems like mkdocs.yml would just be another one of these config files in the root dir.

However, there is much more to it than that, Its important to note the a MkDocs project can contain multiple items (including, but not limited to):

- docs/
- custom_theme/
- site/
- mkdocs.yml

Within that narrow view, having the config file at the root makes sense. If you are really bothered by having the mkdcos.yml file in your project root, then you probably won't like the theme_dir or the site_dir (which is generated on mkdocs build) being in your root directly either. In that case, I would suggest nesting everything within a parent directory. Perhaps like this:

- docs/
  - docs/
  - custom_theme/
  - site/
  - mkdocs.yml
- api/
- client/
- ...

In light of #543 (which may be subject to change), you do need to cd into your parent dir, but that's a small price to pay for a clean root. And if you don't like docs/docs/..., you can always rename the docs_dir to something else (perhaps src which gives you the sensible location docs/src). In fact, the default value of docs_dir being "docs" really only makes sense with the current defaults.

Finally, many of our competitors follow the same pattern. I realize that's not really a reason, but it shows a common pattern that many (most?) users will find natural.

Given the above and the various other links issues, it should be clear that MkDocs has been created from its inception with the current behavior as the (in this regard) as the only way to configure the project. A change now would have far reaching consequences which would be a disruption to many many users. Therefore, even if reasonable counter-arguments could be made for each of the points above, there would have to be a pretty strong argument before we would consider such a change.

[dfee]

Thanks for the reply. I think I'll go with the docs/docs approach.

[waylan]

For future reference, there is one more consideration that I failed to mention earlier, which may actually be the most important one of all: Some of our competitors use various strict naming conventions for different things or require separate directories for documents verses assets, etc. In MkDocs, anything in the docs_dir, regardless of name/location/file type will be included in the built site. That offers a lower barrier to entry, is simpler to remember, and is easy to understand. Once we start adding exceptions for this file or that, we loose that simplicity. Therefore, any file in the docs_dir will end up in the built site. As we don't want the mkdocs.yml file in the built site, it can't go in the docs_dir.

[oprypin]

While these are valid considerations from a perfectionist standpoint (I can easily imagine myself being in that mindset), I think this is user-hostile, and is still a major factor in me doubting the choice of the tool.

Seems like mkdocs.yml would just be another one of these config files in the root dir

Well no, that's what I really don't want. The files there describe my project, while mkdocs.yml describes a book I wrote for my project, and it should be with the book.
(This could also be seen as overstating the importance of the tool; "yes, the mkdocs.yml in the root".)

Now, if I have multiple (kinds of) books, like the original poster, that structure just breaks down, and that's not coincidental but rather a natural consequence of mixing up these relations.

Do I really want to see this unnecessary directory nesting just to isolate that one special snowflake of a file?

• docs/
  • mkdocs.yml
  • docs/
    • index.md
    • section1/
      • foo.md
    • section2/
      • bar.md
• api/
  • mkdocs.yml
  • docs/
    • index.md
    • section1/

I'll still have to have that structure with 1 book anyway, because having the file at the top level just can't make sense considering the above. Or if I happened to use a different generator tool for that other doc, would I use this structure?

• book1
  • other_generator.yml (→book1)
  • foo.md
• book2
  • foo.md
• mkdocs.yml (→book2)

---

you probably won't like the theme_dir or the site_dir (which is generated on mkdocs build) being in your root directly either.

OK so I'll reconfigure that? Thankfully that option is not locked down.

In MkDocs, anything in the docs_dir, regardless of name/location/file type will be included in the built site.

I'm sure mkdocs.yml, which is already special in many regards, could easily be understood to also be special in that regard. This argument is still mainly perfectionism.

---

Now what bothered me even more is just how adamant the tool is about enforcing this, even though it would've worked perfectly fine if not for the intentional error. There's no way to alter this validation step, no way to run something before it, or tell the tool "shh I know what I'm doing". No way for a plugin to achieve this, certainly, save for "hacking into" the implementation outside of the plugin API, e.g.

mkdocs.config.config_options.Dir.post_validation = lambda *args, **kwargs: None

Now, my main plan is to use a plugin that does just that, without publicizing it. I'll let my perfectionism run wild, except, of course, it won't be fully satisfied with that kind of solution.

I would be thankful if you considered the possibility to let a plugin officially access this validation somehow, or access the config before the validation happens (this feature would make sense in general), or selectively suppress validation errors.

[ktomk]

@oprypin: I don't think this needs a plugin necessarily, this is how I got it to work:

directory layout:

 +- /
   +- project-clone/
   +- mkdocs.yml (hard-link to project-clone/mkdocs.yml)

in mkdocs.yml:

docs_dir: "project-clone"
edit_uri: ./edit/master

as mkdocs is not aware of git anyway, for a publishing pipeline think of git-archive as a tar-pipe or similar.

[chephei]

Add a line with name the dir in mkdocs.yml
docs_dir: 'material'

and create volume for material in docker using this command
-v ${PWD}:/docs/material
here full command
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs -v ${PWD}:/docs/material squidfunk/mkdocs-material

[nmatare]

Using a symbolic works to resolve this issue.

ln -s ..root/docs/mkdocs.yml ..root/mkdocs.yml

[ktomk]

@nmatare Yes, can confirm that. I'm currently using multiple symbolic links to generate a mkdocs based website (as a github page) just from within the main source repository. It works and processes are straight forward but it has some downsides that can be minimized by having this configuration on a specific branch. Example github page: https://ktomk.github.io/pipelines/ (the repo is linked in the header).

[dzmitry-kankalovich]

While there might be some valid reasoning, I've hit a very simple problem with Docker.

Just because mkdocs.yml is on the root level, I am forced to put Dockerfile on the same level. Now, it does not look pretty anymore, considering that there is a ton of other stuff in the repo, and in fact, it is a monorepo. The problem is beyond aesthetic - docker build treats the entire repo as a context for the build, which dramatically slows it down:

Regardless of where the Dockerfile actually lives, all recursive contents of files and directories in the current directory are sent to the Docker daemon as the build context.
Source

The suggested approach - docs/src or docs/docs - is ugly to me either. The benefit of .md is that it is automatically rendered in Github / GitLab. So you kinda get the entire set of docs there for free, without forcing people to some other website with deployed mkdocs. From that perspective, I guess, you'd want to place docs nicely, in docs folder.

In conclusion, my humble opinion is that there are no strong enough reasons to prohibit such a simple solution (also not sure how is this a breaking change, but I have not delved into details of implementation).

[ktomk]

@dzmitry-kankalovich Yes, and if you follow the link, for that scenario there is .dockerignore. That is just OOTB, there are options with more control like streaming in a tar-file from standard input with the Dockerfile as the first file - this is all outlined on that page.

I do see the benefit you describe as well having the md files in the repository. In my case it's Github and before I started to integrate mkdocs it was README.md etc. and a doc folder with more Markdown files, so in my example this might be similar to yours:

• Repo on Github
• Mkdocs Github Page

I'm working with symbolic links (and one rename to have COPYING as HTML and some extra files for tuning all in it's own mkdocs based build.

[oprypin]

I had mentioned a plugin that I made that forces MkDocs to allow putting mkdocs.yml alongside the docs.
It has been working well for me, now I finally share it here.
https://github.com/oprypin/mkdocs-same-dir

[dd-ssc]

@oprypin: Thank you very much for creating that plugin, it solves a long standing problem here! 👍

I dont't even mind having .mkdocs.yaml at the root (and having two READMEs plus various other issues), but there is all kinds of .md files in various sections of my project and I need to be able to access them all from one central webpage.

I tried hard to work around this issue using symlinks and all kinds of other approaches, but it seems mkdocs actually makes an effort to actively prevent them. I really like mkdocs for many reasons and I do appreciate the hard work put into it, but concerning that aspect, I get the impression the attitude here is structure your project the way we tell you to - or use a different tool. Sorry, but from my perspective, this isn't even opinionated anymore, that's just a massive design defect.

[ktomk]

@dd-ssc I have no problems using symbolic links, even including the preview etc. with mkdocs, so I'm not aware of mkdocs actively preventing them, but your comment made me curious: can you elaborate more on the symbolic link prevention?

[ecdani]

A workaround in case you are using docker compose:

mkdocs:
    image: squidfunk/mkdocs-material:latest
    ports:
      - 8000:8000
    volumes:
      - type: bind
        source: ./docs
        target: /docs/docs
      - type: bind
        source: ./docs/mkdocs.yml
        target: /docs/mkdocs.yml