MkDocs静态页面超链接失效求助：构建后异常，serve模式正常

Hey there! I’ve run into this exact problem a few times when deploying MkDocs sites—frustrating when everything works locally but breaks once you push the static files. Let’s walk through the most likely fixes:

1. Fix Your Link Syntax #

MkDocs is designed to handle clean URLs automatically, so avoid hardcoding .html in your links. Instead of writing:

[Folder Content](folder/index.html)

Use either of these formats:

[Folder Content](folder/)
# Or even simpler
[Folder Content](folder)

When you build the site, MkDocs will resolve these to the correct folder/index.html path, whether you’re serving locally or deploying to a server. Hardcoding .html can cause path mismatches if your site is deployed in a subdirectory.

2. Set the site_url in mkdocs.yml #

If your site is deployed to a subdirectory (e.g., https://yourdomain.com/docs/ instead of the server root), MkDocs needs to know this to generate proper relative links. Add this line to your mkdocs.yml:

site_url: https://yourdomain.com/docs/

Replace the URL with your actual deployment path. This ensures all links are generated relative to your site’s root, not the server’s root—something mkdocs serve handles automatically locally, but static builds don’t.

3. Clean and Rebuild Your Site #

Sometimes old build artifacts can cause weird path issues. Run this command to wipe the existing site folder and generate a fresh build:

mkdocs build --clean

Double-check the generated site folder to confirm folder/index.html exists and has the correct structure.

4. Check Your Server Configuration #

If the above steps don’t fix it, the problem might be with how your server handles URLs. Most servers need to be configured to serve index.html when a directory path is requested:

• GitHub Pages/GitLab Pages: This is enabled by default, so you shouldn’t need to tweak anything here.
• Nginx: Add this rule to your server block to redirect directory requests to index.html:

  try_files $uri $uri/ $uri/index.html;
  

• Apache: Make sure mod_dir is enabled (it usually is by default) and that DirectoryIndex index.html is set in your .htaccess or server config.

Give these steps a shot—9 times out of 10, it’s either a link syntax issue or missing site_url configuration.

内容的提问来源于stack exchange，提问作者Joseph Kobti