V.1.2: Markdown links earlier processed as html files, are now processed as directories

[fralau]

The new version brings a curious issue. With versions < 1.2, I used internal links in this way, to make a call to page bar.md, from page foo.md:

[linking to content in bar](../bar#content)

Which was transformed correctly into:

<a href="../bar/#content">linking to content in bar</a>

Since version 1.2, the bar is intepreted differently by mkdocs serve, which breaks all such links. I realize this is highly irregular and correct call should have been:

[linking to content in bar](bar.md#content)

So please dont throw rotten tomatoes at me 🍅 .

But just to help me fix this: why this change of behavior? Has some part been reimplemented? Or has this been intentional, to prevent that kind of error in the future?

[oprypin]

Your finding is correct. Let me expand on this.
(In addition to documentation, where I can't find references to this exact situation)

Regarding links that look like:
[linking to content in bar](../bar#content)
MkDocs completely ignores links to paths without an extension: doesn't validate or alter them.

So your link stays as pointing to a "file" named bar.

There is no strict definition or consensus among HTTP servers whether bar should be understood as bar/ (hence bar/index.html) if it happens to be a directory. So, your links would be broken on at least some servers. It's just that the new server for mkdocs serve happens to not support this. I had no intention of breaking this behavior or preventing anything, but I did intentionally rely on the trailing slash as that's much simpler. The fact is that MkDocs-endorsed links never rely on this behavior, so this wasn't seen as a problem.

As such, I would not consider this a bug. But I will not go as far as to say that the new behavior is better.

[fralau]

@oprypin Thanks a lot for this useful clarification! Also the pointer to the documentation started to put some clarity in my mind, about how mkdocs modifies internal links when it generates the html pages.

Perhaps, it would be a good idea to give additional details (or examples) on the rules that mkdocs uses, so that we can think with border cases, etc.?

[avently]

@oprypin, hello. Found this topic when tried to fix my problem with trailing slash.
Right now if I have a site https://example.com with directory structure docs/somepath/index.md I can't call example.com/somepath (note missing slash at the end). This call shows 404 error. If I add a slash at the end like example.com/somepath/ I will see a page index.md without problems.
On main mkdocs site when I enter a link without trailing slash https://www.mkdocs.org/user-guide/configuration the site redirects me to the page with trailing slash (so no 404 error).

The question is why the behaviour differs and how to get a redirect to a page with a trailing slash (if it wasn't specified)? For me it's a problem because my current site is viewed without slashes at the end and my app has links to that pages without slashes. And if I move to mkdocs this behavior will break previous versions of the app.

[oprypin]

@avently

(Note that generally, when linking from within MkDocs, you must write the links as somepath/index.md, only then they are properly supported by MkDocs.)

When hosting the site on a server and linking from elsewhere, these redirects rely on particular behaviors of particular servers. The fact that mkdocs serve supports or doesn't support such redirects has no effect on the final deployment server, which you will pick yourself, so there will be no problem.

To put it differently, a deployed MkDocs site is just a collection of HTML files. Of course HTML files themselves cannot define how redirects work on any particular server. The server used by mkdocs serve happens to not support these redirects, and actually I think it's a good thing, because then it represents the "lowest common denominator" of webservers.

[avently]

You were so fast. I didn't even fast enough to write a comment related to my testing with python -m http.server --directory site. In this case the behavior is expected and works correctly. So yeah, I can switch to mkdocs, thanks!

[oprypin]

Thanks for your perspectives. I changed the behavior to be as expected here.

[avently]

@oprypin cool, thank you too