Unexpected error behaviour on name clash

[dmoisset]

I recently had an issue with my docs, and although it's something I can and should fix in my docs, I think mkdocs error handling could be improved in this case. When having both a README.md and index.html in my source, and adding the README.md as one of the nav items, mkdocs correctly warns me that it won't clobber the index.html(yay!), but then proceeds to generate broken output in the TOC for that item(boo!), where the link label is None, and the link URL points to a README.md file in the output (which doesn't exist). The behaviour of generating broken output and succeeding is quite surprising.

I would expect any of the following:

• mkdocs complaining that it can not generate correct output (error rather than warning, like if I had use the --strict option but defaulting to this in this case)
• Not generating any output at all, to at least get a "clean" output
• Ideally, creating a renamed "README.html" or similar file with the rendered output, rather than failing.

To reproduce

Use the following config:

site_name: Demo for buggy index.html behaviour

site_dir: output
docs_dir: source
markdown_extensions:
  - toc:
      permalink: true
nav:
  - index.md
  - demo/README.md

Create the following tree of files. Put any valid content in the markdown/html files (or leave them empty):

├── bug.yaml
└── source
    ├── demo
    │   ├── README.md
    │   └── index.html
    └── index.md

Once you build this (I've used mkdocs 1.5.2) you'll get a navigation on the top with a link labeled "None", which points to an invalid URL (404).

[oprypin]

Yep, this looks like bug. I will look into it very soon. Thank you for the detailed report.

[oprypin]

By the way, if we delete the whole demo subdirectory, it still produces a None nav entry. That's really the worse part of this for me. Other than this, it's actually hard to find what exactly is not intended behavior, it all started to seem like it is actually intended behavior.

[oprypin]

Regarding your particular situation, it seems like you wanted to rely on the behavior of assuming that .html is the rendered file but still linking to the .md file and it kinda working and even picking up the page title from .md even though it's not the actual page used.

In such case, the correct way to configure it is as follows:

site_name: Demo for buggy index.html behaviour

markdown_extensions:
  - toc:
      permalink: true

exclude_docs: |
  /demo/README.md

nav:
  - index.md
  - Title: demo/index.html