Link Path Calculator

Use this step-by-step process to determine the correct link path between any two pages in the documentation. This is the single most useful reference for avoiding broken links.

Step 1: Identify the Source File

Determine which markdown file contains the link you are writing. Note its full path from the docs/ root:

• configuration/applications.md
• appendices/validations.md
• administration/index.md

Step 2: Identify the Target File

Determine which markdown file you want to link to:

• configuration/member-properties.md
• logic-builder/index.md
• deployment/index.md

Step 3: Determine the Link Type

Are you writing a markdown link or an HTML link?

• Markdown link: [Link Text](path) — MkDocs will rewrite the path
• HTML link: <a href="path"> — the browser resolves the path as-is

Step 4: Calculate the Path

For Markdown Links

Find the relative path from the source file to the target file as they exist on disk:

1. Start at the source file's directory.
2. Use ../ to go up to the common parent directory.
3. Navigate down to the target file.
4. Include the .md extension.

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

• Source is in appendices/ → go up one level with ../ → now at docs/
• Navigate to configuration/member-properties.md
• Result: ../configuration/member-properties.md

For HTML Links

Calculate based on the built URL structure, not the source file structure. Remember that MkDocs converts each .md file into a directory:

1. Determine the built URL of the source page.
2. Determine the built URL of the target page.
3. Calculate the relative path between the two built URLs.

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

• Source built URL: /admin-docs/appendices/validations/ (file became a directory)
• Target built URL: /admin-docs/configuration/member-properties/
• From validations/, go up to appendices/ (one ../), then up to site root (another ../), then down to target
• Result: ../../configuration/member-properties/

Common Path Lookup Table

This table covers the most common link scenarios in the EPMware Admin Guide:

From configuration/ pages

From	To	Markdown Path	HTML Path
configuration/applications.md	configuration/dimensions.md	dimensions.md	../dimensions/
configuration/applications.md	deployment/index.md	../deployment/index.md	../../deployment/
configuration/applications.md	appendices/oracle-epm-cloud.md	../appendices/oracle-epm-cloud.md	../../appendices/oracle-epm-cloud/
configuration/index.md	configuration/applications.md	applications.md	applications/

From appendices/ pages

From	To	Markdown Path	HTML Path
appendices/validations.md	configuration/member-properties.md	../configuration/member-properties.md	../../configuration/member-properties/
appendices/validations.md	logic-builder/index.md	../logic-builder/index.md	../../logic-builder/
appendices/oracle-epm-cloud.md	configuration/applications.md	../configuration/applications.md	../../configuration/applications/
appendices/index.md	appendices/oracle-epm-cloud.md	oracle-epm-cloud.md	oracle-epm-cloud/

From administration/ pages

From	To	Markdown Path	HTML Path
administration/index.md	administration/services.md	services.md	services/
administration/index.md	administration/migration.md	migration.md	migration/
administration/index.md	configuration/applications.md	../configuration/applications.md	../../configuration/applications/
administration/migration.md	deployment/index.md	../deployment/index.md	../../deployment/

From root index.md

From	To	Markdown Path	HTML Path
index.md	configuration/index.md	configuration/index.md	configuration/
index.md	security/index.md	security/index.md	security/

Visual Directory Depth Reference

docs/                              depth 0
├── index.md                       depth 0 → built as /
├── configuration/                 depth 1
│   ├── index.md                   depth 1 → built as /configuration/
│   ├── applications.md            depth 1 → built as /configuration/applications/
│   └── member-properties.md       depth 1 → built as /configuration/member-properties/
├── appendices/                    depth 1
│   ├── index.md                   depth 1 → built as /appendices/
│   └── validations.md             depth 1 → built as /appendices/validations/
├── administration/                depth 1
│   ├── index.md                   depth 1 → built as /administration/
│   ├── services.md                depth 1 → built as /administration/services/
│   └── migration.md               depth 1 → built as /administration/migration/
└── deployment/                    depth 1
    └── index.md                   depth 1 → built as /deployment/

Key Insight

For markdown links, the path is calculated from the source file's location on disk. For HTML links, the path is calculated from the source file's built URL — which adds one extra level of depth because each .md file becomes a directory. This is why HTML links from non-index files need one more ../ than you might expect.

Verification Procedure

After writing any link:

1. Run mkdocs serve.
2. Navigate to the page containing the link.
3. Hover over the link and check the URL in the browser status bar.
4. Click the link and confirm it reaches the correct page.
5. If you get a 404, compare the actual URL to your expected URL and adjust the number of ../ segments.