Skip to main content

Content Relationship Management

This guide explains how to use the content relationship management system to create, validate, and visualize connections between documentation pages.

Understanding Content Relationships

Content relationships in our documentation system are defined in frontmatter metadata using these key fields:

  • relatedPages: Pages that are directly related to the current content (bidirectional relationship)
  • associatedResources: External resources or tools associated with the content
  • prerequisites: Content that should be read before the current page
  • nextSteps: Suggested content to read after the current page
  • seeAlso: Additional relevant content that doesn't fit the other categories

For example, in a page about "API Authentication," you might include:

---
title: API Authentication
relatedPages: 
  - security/authorization
  - getting-started/credentials
prerequisites:
  - api/overview
nextSteps:
  - api/making-requests
associatedResources:
  - tools/api-tester
---

Managing Relationships

Adding Relationships

To add relationships to a document, edit the frontmatter section at the top of the markdown file:

  1. Identify the content ID of the page you want to link to (usually the path without file extension)
  2. Add the ID to the appropriate relationship field in the frontmatter
  3. For relatedPages, remember that these are bidirectional relationships, so the target page should ideally also link back

Validating Relationships

Use the relationship validation tool to verify that all content relationships are valid:

# Validate all content relationships
node scripts/js/manage-relationships.js --validate

# Validate and automatically fix issues
node scripts/js/manage-relationships.js --validate --fix

This will check for:

  • Broken references to non-existent pages
  • One-way relationships (where relatedPages don't link back)

Suggesting Relationships

The system can analyze content similarity to suggest potential relationships:

node scripts/js/manage-relationships.js --suggest

This generates suggestions based on:

  • Content similarity between documents
  • Keyword analysis of titles and descriptions
  • Existing relationship patterns

Visualizing Content Relationships

You can generate a visual graph of content relationships:

# Generate relationship JSON data
node scripts/js/manage-relationships.js --graph

# Create and open a visualization in your browser
node scripts/js/visualization/relationship-graph.js

The visualization provides:

  • Interactive force-directed graph of all content
  • Color coding based on business area/category
  • Different line styles for relationship types
  • Filtering by relationship type
  • Search functionality
  • Node highlighting on hover

Reading the Graph

In the relationship graph:

  • Nodes: Represent individual content pages
  • Edges: Represent relationships between pages
  • Node size: Larger nodes have more connections
  • Node color: Represents business area or category
  • Edge style: Represents relationship type (solid for related pages, dashed for prerequisites, etc.)

Relationship Best Practices

For effective content relationships:

  1. Be selective: Only link to truly relevant content; don't overwhelm with too many links
  2. Maintain reciprocity: For relatedPages, establish two-way relationships when appropriate
  3. Consider the user journey: Use prerequisites and nextSteps to create logical reading paths
  4. Check validation: Run the validation tool regularly or use the GitHub Action
  5. Review suggestions: Periodically check for suggested relationships to improve connections

Automated Workflow

The content relationship system includes automated validation through GitHub Actions:

  • Relationship validation runs on all PRs affecting documentation
  • A relationship graph is automatically generated and published
  • Broken links are reported in the workflow log

Troubleshooting

Missing Documentation ID

If your document doesn't have an explicit id in the frontmatter, the system will generate one based on the file path. To avoid issues, you can add an explicit ID:

---
id: unique-content-id
title: Document Title
---

Broken References

If the validation reports broken references, check:

  • The spelling of the referenced ID
  • Whether the target document exists
  • If the target has a custom ID specified in its frontmatter

Large Graphs

For documentation with many files and relationships, the visualization may become cluttered. Use the filtering options to focus on specific relationship types or search for specific content.