Skip to content

Managing Links & Cross-References

Links are the single most common source of problems in the EPMware documentation sites. This section covers the rules and patterns you need to follow to avoid broken links.

MkDocs handles two types of links differently, and understanding this difference is critical.

Markdown links use the standard [text](path) syntax:

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

MkDocs rewrites markdown links during the build process. It resolves .md references and converts them to the correct final URLs. This means markdown links are more forgiving — MkDocs will usually figure out the right path.

HTML links use <a href="..."> syntax, typically found inside card layouts and button elements:

<a href="services.md" class="md-button">View Services →</a>

Critical Difference

MkDocs does NOT rewrite href attributes in raw HTML <a> tags. The browser resolves these paths relative to the current page URL, not relative to the source file location. This means HTML links often require different path formats than markdown links to reach the same destination.

How MkDocs Resolves Paths

When MkDocs builds the site, each .md file becomes an index.html inside a directory named after the file. For example:

Source File Built URL
docs/index.md /admin-docs/
docs/configuration/applications.md /admin-docs/configuration/applications/
docs/appendices/validations.md /admin-docs/appendices/validations/
docs/administration/index.md /admin-docs/administration/

Because each page becomes a directory (e.g., applications/index.html), relative paths in HTML links resolve from that directory — which is one level deeper than you might expect.

Same Folder

When linking between files in the same folder, use just the filename:

[Infrastructure](infrastructure.md)
[Applications](applications.md)

Different Folder — Going Up Then Down

When linking from one section to another, use ../ to navigate up:

<!-- From configuration/applications.md to deployment/index.md -->
[Deployment](../deployment/index.md)

<!-- From configuration/applications.md to appendices/oracle-epm-cloud.md -->
[Oracle EPM Cloud](../appendices/oracle-epm-cloud.md)

Linking with Anchors

To link to a specific section on another page, append #anchor-name:

[Deployment Manager](../deployment/index.md#deployment-manager)

The anchor is generated from the heading text: lowercase, spaces replaced with hyphens, and special characters removed. For example, the heading ## Application Create and Import produces the anchor #application-create-and-import.

This is where most problems occur. HTML <a href> links are resolved by the browser based on the current page URL, not by MkDocs based on the source file.

Count Your Directory Depth

The key question is: How many levels deep is the current page from the site root?

Current Page Depth from Site Root Path Prefix to Reach Root
docs/index.md 0 (none needed)
docs/configuration/index.md 1 ../
docs/configuration/applications.md 2* ../ (same folder as index)
docs/appendices/validations.md 2* ../../
docs/appendices/index.md 1 ../

*Because MkDocs converts applications.md to applications/index.html, the browser sees it as being inside an applications/ directory.

The Key Rule for HTML Links

From a file like appendices/validations.md, the built URL is /admin-docs/appendices/validations/. To reach the site root (/admin-docs/), you need to go up two levels: ../../. Then navigate down to the target section. So to link from validations.md to configuration/member-properties.md, the correct HTML href is ../../configuration/member-properties/.

Examples from the EPMware Admin Guide

From appendices/validations.md to configuration/member-properties.md:

<!-- WRONG — only goes up one level, stays inside appendices/ -->
<a href="../configuration/member-properties/">Property Config →</a>
<!-- Resolves to: /admin-docs/appendices/configuration/member-properties/ ❌ -->

<!-- CORRECT — goes up two levels to reach site root -->
<a href="../../configuration/member-properties/">Property Config →</a>
<!-- Resolves to: /admin-docs/configuration/member-properties/ ✅ -->

From appendices/validations.md to logic-builder/index.md:

<!-- WRONG -->
<a href="../logic-builder/">Logic Builder →</a>
<!-- Resolves to: /admin-docs/appendices/logic-builder/ ❌ -->

<!-- CORRECT -->
<a href="../../logic-builder/">Logic Builder →</a>
<!-- Resolves to: /admin-docs/logic-builder/ ✅ -->

From administration/index.md to administration/services.md:

<!-- CORRECT — same section, just reference the file-turned-directory -->
<a href="services/" class="md-button">View Services →</a>

<!-- Also works with the .md extension in markdown links -->
[Services](services.md)

From administration/index.md to administration/migration.md:

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

Using Absolute Paths as a Last Resort

If relative paths are proving difficult to debug, you can use absolute paths that start from the site root. These begin with the site_url base path:

<a href="/admin-docs/configuration/member-properties/">Property Config →</a>
<a href="/admin-docs/logic-builder/">Logic Builder →</a>

Absolute Path Portability

Absolute paths work reliably but are tied to the site_url value in mkdocs.yml. If the site moves to a different base path, all absolute paths will break. Use them sparingly and only when relative paths have been exhausted.

Mistake 1: Anchor Links to Content in Separate Files

<!-- WRONG — points to a section on the same page, but content is in a separate file -->
- **[Services](#services)** - Monitor and control background services

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

This happens when content that was originally on a single page gets split into multiple files. The anchor links (#section) are left behind instead of being updated to file references.

<!-- WRONG — MkDocs won't rewrite this -->
[Member Properties](../configuration/member-properties)

<!-- CORRECT — include the .md extension -->
[Member Properties](../configuration/member-properties.md)

Mistake 3: Wrong Number of ../ Levels

This is the most frequent issue. Always count the directory depth of the current file and the target file to determine how many ../ segments you need.

Remember: markdown links ([text](path.md)) and HTML links (<a href="path/">) follow different rules. Do not assume what works for one will work for the other.

After making link changes:

  1. Run mkdocs serve locally.
  2. Click every link you changed or added.
  3. Check the browser address bar to confirm the URL is correct.
  4. If you get a 404, compare the URL the browser tried to load against the URL you expected. The difference will tell you how many ../ levels you need to adjust.

Browser DevTools

Hover over a link in your browser and look at the status bar (bottom of the browser window) to see the resolved URL before clicking. This helps you verify the path without navigating away from the current page.