Broken Links & 404 Errors

Broken links are the most frequent issue in MkDocs documentation. This page documents the specific problems encountered in the EPMware guides and how to resolve them.

Diagnosing a Broken Link

When you click a link and get a 404 error:

Look at the URL in the browser address bar — this is where the browser tried to go.
Determine where it should have gone.
Compare the two to understand what went wrong.

For example, if you clicked a link on the validations page expecting to reach /admin-docs/configuration/member-properties/ but the browser went to /admin-docs/appendices/configuration/member-properties/, the problem is that the link only went up one directory level instead of two — it stayed inside appendices/ instead of reaching the site root.

Problem: HTML Link Stays Inside the Current Section

Symptom: Clicking a link in an HTML card or button on a page inside appendices/ takes you to /admin-docs/appendices/configuration/member-properties/ instead of /admin-docs/configuration/member-properties/.

Cause: The <a href> path uses ../ (one level up) when it needs ../../ (two levels up). Because MkDocs converts validations.md to validations/index.html, the browser sees the page as being inside a validations/ directory within appendices/. Going up one level (../) lands in appendices/, not at the site root.

Solution: Count the directory depth and use the correct number of ../ segments:

<!-- WRONG — goes up one level (stays in appendices/) -->
<a href="../configuration/member-properties/">Property Config →</a>

<!-- CORRECT — goes up two levels (reaches site root) -->
<a href="../../configuration/member-properties/">Property Config →</a>

How to count: From appendices/validations.md, the built URL is appendices/validations/index.html. That is two directories deep from the site root: appendices/ → validations/. So you need two ../ to reach the root.

Problem: Anchor Links Point to Missing Sections on Same Page

Symptom: Clicking a link like [Services](#services) on the Administration index page scrolls to the top of the page or does nothing. No section with that heading exists on the page.

Cause: The content for "Services" was moved to a separate file (services.md) but the link was left as an anchor reference (#services) pointing to a section on the same page.

Solution: Change the anchor link to a file reference:

<!-- WRONG — anchor to a section that doesn't exist on this page -->
- **[Services](#services)** - Monitor and control EPMware background services

<!-- CORRECT — link to the separate file -->
- **[Services](services.md)** - Monitor and control EPMware background services

For HTML links in cards:

<!-- WRONG -->
<a href="#application-migration" class="md-button">Migrate Apps →</a>

<!-- CORRECT -->
<a href="application-migration.md" class="md-button">Migrate Apps →</a>

Problem: Links with .md Extension in HTML Tags

Symptom: A link works in markdown format ([text](file.md)) but the same path in an HTML <a href> tag produces a 404 or unexpected behavior.

Cause: MkDocs rewrites .md extensions in markdown links but does not rewrite them in HTML href attributes. However, this behavior can vary depending on the MkDocs version and configuration.

Solution: For HTML links, use the directory-style URL that MkDocs generates (without .md), typically with a trailing slash:

<!-- Markdown link — .md is fine, MkDocs rewrites it -->
[Member Properties](../configuration/member-properties.md)

<!-- HTML link — use the built URL format -->
<a href="../configuration/member-properties/">Member Properties</a>

Consistency Tip

For markdown links ([text](path)), include the .md extension. For HTML links (<a href>), use the directory-style URL without .md and with a trailing slash. This follows the conventions established in the EPMware guides.

Problem: Relative Path Resolves Incorrectly Across Sections

Symptom: A link from appendices/oracle-epm-cloud.md to configuration/applications.md produces a URL like /admin-docs/appendices/configuration/applications/ instead of /admin-docs/configuration/applications/.

Cause: Relative paths in HTML links are resolved by the browser from the current page's URL, not from the source file's location. Since oracle-epm-cloud.md becomes appendices/oracle-epm-cloud/index.html, a relative path like ../configuration/applications/ only goes up to appendices/ — not to the site root.

Solution: Use ../../ to go up two levels:

<!-- From appendices/oracle-epm-cloud.md -->
<a href="../../configuration/applications/">Application Config →</a>

Or use markdown links instead, which MkDocs resolves correctly:

[Application Configuration](../configuration/applications.md)

Problem: Links Between Files in the Same Section

Symptom: A link from administration/index.md to administration/services.md doesn't work as expected.

Cause: Since index.md becomes the administration/ directory page, linking to sibling files requires just the filename (for markdown) or a relative path (for HTML).

Solution:

<!-- Markdown — just use the filename -->
[Services](services.md)
[Application Migration](application-migration.md)

<!-- HTML — reference the built directory -->
<a href="services/" class="md-button">View Services →</a>

Problem: Absolute Path Works Locally But Not on GitHub Pages

Symptom: A link like <a href="/configuration/applications/"> works on localhost:8000 but returns 404 on the GitHub Pages site.

Cause: The GitHub Pages site is served from a subdirectory (e.g., /admin-docs/), but the absolute path starts from the domain root (/). Locally, the site root is /, so it works; on GitHub Pages, the site root is /admin-docs/.

Solution: If using absolute paths, include the full base path:

<!-- WRONG — missing the base path -->
<a href="/configuration/applications/">Applications →</a>

<!-- CORRECT — includes the site base path -->
<a href="/admin-docs/configuration/applications/">Applications →</a>

Better yet, use relative paths to avoid this dependency entirely.

Link Path Quick Reference

This table shows the correct path format for common cross-section links:

From File	To File	Markdown Link	HTML href
`configuration/index.md`	`configuration/applications.md`	`[Apps](applications.md)`	`applications/`
`configuration/applications.md`	`deployment/index.md`	`[Deploy](../deployment/index.md)`	`../../deployment/`
`appendices/validations.md`	`configuration/member-properties.md`	`[Props](../configuration/member-properties.md)`	`../../configuration/member-properties/`
`appendices/validations.md`	`logic-builder/index.md`	`[LB](../logic-builder/index.md)`	`../../logic-builder/`
`administration/index.md`	`administration/services.md`	`[Services](services.md)`	`services/`
`administration/index.md`	`administration/migration.md#monitor`	`[Monitor](migration.md#monitor)`	`migration/#monitor`

When in Doubt, Use Markdown Links

Markdown links ([text](path.md)) are handled by MkDocs and are more reliable across different configurations. Use HTML <a href> links only when you need them for card layouts, buttons, or other HTML structures. When you must use HTML links, always verify them locally before pushing.