Search code examples
mkdocs

Mkdocs hyperlink not working in static pages

I'm trying to build a documentation with mkdocs. The problem is that the links in the static created pages are not working. Instead of going to [folder]/index.html I'm presented with the following page like in the following image

The problem however doesn't exist when i try mkdocs serve

Solution

  • Set the use_directory_urls setting to false in your mkdocs.yml config file:

    use_directory_urls: false

    The documentation explains:

    This setting controls the style used for linking to pages within the documentation.

    The following table demonstrates how the URLs used on the site differ when setting use_directory_urls to true or false.

    Source file  | Generated HTML       | use_directory_urls: true | use_directory_urls: false
------------ | -------------------- | ------------------------ | ------------------------
index.md     | index.html           | /                        | /index.html
api-guide.md | api-guide/index.html | /api-guide/              | /api-guide/index.html
about.md     | about/index.html     | /about/                  | /about/index.html

    The default style of use_directory_urls: true creates more user friendly URLs, and is usually what you'll want to use.

    The alternate style can occasionally be useful if you want your documentation to remain properly linked when opening pages directly from the file system, because it create links that point directly to the target file rather than the target directory.

    The last paragraph is the key to why this makes a difference.