Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Error when using files from root and from docs folder #615

Closed
dfl-aeb opened this issue Nov 17, 2023 · 3 comments
Closed

Error when using files from root and from docs folder #615

dfl-aeb opened this issue Nov 17, 2023 · 3 comments

Comments

@dfl-aeb
Copy link

dfl-aeb commented Nov 17, 2023

First thanks for your great plugin and all the work you put into it.

We're experiencing a problem when using files from the root dir like the README.md and files from the docs dir like docs/test.md.

Our folder structure looks like this:

├── README.md
├── CHANGELOG.md
├── docs
│   └── test.md
└── mkdocs.yml

The mkdocs.yml looks like this:

edit_uri: edit/main

nav:
  - Home: README.md 
  - Changelog: CHANGELOG.md
  - Test: docs/test.md

plugins:
  - simple:
      folders: ["docs/**", "./CHANGELOG.md", "./README.md"]
      merge_docs_dir: false

We needed to set merge_docs_dir to false to be able to specify the test docs like this docs/test.md in the nav section. This was the only way we could get the edit_uri to work properly (if there is another way please let me know).

By setting merge_docs_dir to false the docs get rendered correctly and the edit_uri works as expected. The problem is now, that mkdocs prints out this info message during the build:

INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - docs/test.md

- The plugin copies the README and the CHANGELOG additionaly into the docs dir, which is not necessary because it's already in the root dir. (My bad, I had copied the README and CHANGELOG into the docs folder)

  • I don't understand whys mkdocs thinks that the docs/test.md is not included in the nav section. It is included and it gets rendered correctly. I assume it has something to do with the docs_dir that the simple plugin is setting?!

This is a bit confusing for our users. Is there a way to fix this?

@athackst
Copy link
Owner

Hello!

Thank you for the detailed issue. Let me see if I can reproduce and I'll get back to you.

@athackst
Copy link
Owner

It looks like the main issue was that you'd copied the README and CHANGELOG into the docs folder and that's fixed now?

I don't see the error " docs/test.md is not included in the nav section " when I run this setup locally.

Also, feel free to comment on mkdocs/mkdocs#3450 if that works for you!

@dfl-aeb
Copy link
Author

dfl-aeb commented Nov 20, 2023

Thanks for your quick reply. I have managed to resolve the issue. It seems that the main issue was that I copied the files into the wrong place.
I still get the error for the docs/test.md but only in one specific repository. I could also not reproduce the error in a new repository. I will try to find out what it is and will report back here.

@dfl-aeb dfl-aeb closed this as completed Nov 20, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants