How to Fix MkDocs 404 Edit URI

In this tutorial, you'll learn about How to Fix MkDocs 404 Edit URI. We cover key concepts, practical examples, and best practices.

The "Edit on GitHub" link in your MkDocs Material site leads to a 404 page. The edit URI configuration points to the wrong repository path.

The Wrong Way

# mkdocs.yml
repo_url: https://github.com/user/repo
edit_uri: edit/main/docs/

The edit_uri must point to the raw file path, not the branch edit page.

The Right Way

Step 1: Use the correct edit_uri format

# mkdocs.yml
repo_url: https://github.com/your-org/your-repo
edit_uri: blob/main/docs/

MkDocs appends the file path to edit_uri. The final URL becomes: https://github.com/your-org/your-repo/blob/main/docs/index.md.

Step 2: For MkDocs Material theme

# Material theme specific:
theme:
  name: material
  features:
    - content.action.edit

repo_url: https://github.com/your-org/your-repo
edit_uri: blob/main/docs/

Step 3: Verify the generated URLs

# After building, check the generated HTML:
grep 'edit' site/index.html
# Expected: https://github.com/your-org/your-repo/blob/main/docs/index.md

Step 4: Handle monorepo setups

# If docs are in a subdirectory of the repo:
edit_uri: blob/main/docs/website/
# Full URL: https://github.com/.../blob/main/docs/website/index.md

Edit link points to https://github.com/your-org/your-repo/blob/main/docs/index.md — opens file for editing.

Prevention

• Test the edit URL locally by building and clicking the link.
• Use blob/main/docs/ as the standard format for edit_uri.
• The URL construction pattern is similar to Doda Browser's "View Source" feature — the path must correctly resolve to the raw resource.

Common Mistakes with 404 edit uri

1. Using foldl instead of foldl' causing stack overflow on large lists
2. Forgetting deriving (Show, Eq) on custom data types needed for debugging
3. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable

These mistakes appear frequently in real-world MKDOCS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

# GitLab:
edit_uri: -/edit/main/docs/
# Bitbucket:
edit_uri: src/main/docs/