Cross-Referencing for Connected Content — Complete Guide

In this tutorial, you will learn about Cross. We cover key concepts, practical examples, and best practices to help you master this topic.

Cross-referencing links related documentation pages together, helping users discover connected topics and navigate between them without returning to navigation menus.

What You'll Learn

You will learn cross-referencing strategies, how to implement automatic and manual cross-references, and how to maintain them as content grows.

Why It Matters

Documentation is rarely linear. Users jump between topics based on their needs. Cross-references make those jumps smooth and predictable.

Real-World Use

DodaTech uses {{< ilink >}} shortcodes for manual cross-references within content and automated related-links sections at the bottom of every page.

flowchart LR
  A[Cross-Referencing] --> B[Manual]
  A --> C[Automatic]
  A --> D[Maintenance]
  B --> E[Inline Links]
  B --> F[Related Sections]
  C --> G[Tag-Based]
  C --> H[Content-Based]
  D --> I[Link Checking]
  D --> J[Update on Move]
  E:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Cross-Reference Types

1. Inline Links

Links within the content body that connect related concepts.

## Inline Cross-Reference Example

Before learning about Python Functions, you should
understand how variables work.

2. Related Content Sections

Lists of links at the bottom of pages.

## Related Tutorials

- Python Data Types
- Python Loops
- Python File Handling

3. Prerequisite Links

Links to content the user should read first.

prerequisites:
  - Python Variables
  - Python Data Types

Implementing Cross-References

Manual Cross-References

def find_cross_reference_opportunities(content, glossary):
    opportunities = []
    for term, url in glossary.items():
        if term.lower() in content.lower():
            opportunities.append(term)
    return opportunities

content = "Python variables are used to store data values in memory."
glossary = {
    'Python Variables': '/python/variables/',
    'Python Functions': '/python/functions/',
}

opportunities = find_cross_reference_opportunities(content, glossary)
for term in opportunities:
    print(f"Link: {term}")

Expected output:

Link: Python Variables

Automatic Cross-References

# config/related-content.yaml
method: tag-based
max_links: 4
criteria:
  - shared_tags: 2
  - same_category: true
  - different_page: true

Cross-Reference Maintenance

Link Checking

Regularly verify that all cross-references resolve.

import re

def check_links(content, existing_pages):
    links = re.findall(r'\((/[^)]+)\)', content)
    broken = []
    for link in links:
        if link not in existing_pages:
            broken.append(link)
    return broken

content = "See [Variables](/python/variables/) and [Functions](/python/functions/)"
existing = {'/python/variables/', '/python/loops/'}
broken = check_links(content, existing)
print(f"Broken links: {broken}")

Expected output:

Broken links: ['/python/functions/']

Handling Page Moves

When pages move, update all cross-references.

def update_cross_references(content, old_path, new_path):
    return content.replace(old_path, new_path)

content = "See [Variables](/python/variables/)"
print(update_cross_references(content, '/python/variables/', '/python/basics/variables/'))

Expected output:

See [Variables](/python/basics/variables/)

Cross-Reference Best Practices

Common Mistakes

1. Too Many Links

A page with 20 inline links overwhelms readers. Limit inline links to essential connections.

2. Generic Anchor Text

"Click here" and "read more" do not describe the linked content. Use descriptive text.

3. Broken Links

Links that lead to 404 pages destroy user trust. Check links regularly.

4. Circular References

Page A links to Page B, and Page B links back to Page A with no additional content. Ensure cross-references add value.

5. No Cross-References

Pages in isolation do not help users discover related content. Every page should have at least 2-3 cross-references.

Practice Questions

1. What are three types of cross-references?

Inline links, related content sections, and prerequisite links.

2. Why is descriptive anchor text important?

It helps users know what they will find before clicking, reducing click-through on irrelevant links.

3. How do you maintain cross-references when pages move?

Use redirects for immediate fix, then update all links to the new URL. Automate this if possible.

4. How many related links are recommended per page?

3-5 maximum. Too many choices overwhelm users.

5. Challenge: Audit a documentation section for cross-references. Find pages with no links, pages with broken links, and pages with too many links. Propose improvements.

FAQ

Mini Project

Implement a cross-referencing system for a documentation section. Add inline links to 5 pages, create a related content section with tag-based suggestions, and set up automated link checking.

What's Next

Now that you understand cross-referencing, learn User Flows to design task-based journeys. Then study IA Patterns.