Why are my local html links going to parent folder instead of the .html?

Question

EDIT: Waylan's answer did the trick! Thanks!

I'm trying to zip .html files of docs to send to a customer. The goal is to have the same experience as navigating an actual website.

When opening the .html files, any link that is clicked goes to the parent folder, rather than the specific .html. For example, if I click on the link for the configuration page, it takes me to this parent folder (shown in the picture) with an index.html to the actual page. This is only happening in my local instance when I'm going through the .html files -- not when I'm navigating the built .md (using MkDocs).

• macOS Catalina, 10.15.3
• MkDocs
• Markdown

Answer 1

You probably want to set use_directory_urls: false in your mkdocs.yml config file.

The behavior you are seeing is based on a feature of web servers. If you request a directory (for example /foo/) then the server will return the index page within that directory (/foo/index.html). MkDocs makes use of this feature to provide "pretty URLs" (URLs which do not have file extensions).

Therefore, when building the site, MkDocs will convert every page to an index file within a directory and will also rewrite all of the internal links to point to those locations. So long as the pages are hosted on a server which is configured to serve index pages (most are by default), this is not an issue.

However, if you are browsing the files locally without a web server or happen to be using a server which is not configured to handle index files, then you will see the behavior you are getting. You have two options:

1. Use a properly configured server.
2. Turn off the feature with MkDoc' use_directory_urls configuration setting.

To do the latter, add the following to your mkdocs.yml config file:

use_directory_urls: false

Then rebuild the site with mkdocs build. Now your pages will not all be index files.

Note that while this allows you to browse the files without a server (using file:///), due to browser security policies, search will no longer work within a MkDocs site. Therefore, it is recommended that you always use a server. That also explains why the default configuration expects a server.