Skip to main content
Version: Next

Navigation and Cross-Reference Features

This guide explains the enhanced navigation and cross-reference features available throughout the ageSchemaClient documentation.

Overview​

The documentation includes several navigation enhancements designed to improve your learning experience:

  • Breadcrumb Navigation - Shows your current location in the documentation hierarchy
  • Tag-Based Organization - Content is organized by topics and difficulty levels
  • Cross-References - Automatic linking between related concepts
  • Related Articles - Suggestions for further reading
  • Comprehensive Glossary - Searchable definitions of all terms
  • Difficulty Indicators - Content is marked by complexity level

Breadcrumbs appear at the top of each documentation page, showing your current location in the site hierarchy.

Features​

  • Hierarchical Navigation - Click any breadcrumb to navigate up the hierarchy
  • Current Page Indicator - The current page is highlighted and not clickable
  • Mobile Responsive - Adapts to smaller screens with appropriate spacing
  • Accessibility - Proper ARIA labels and keyboard navigation support

Example​

Home / Documentation / Getting Started / Basic Usage

Tag System​

Content is organized using a comprehensive tag system that helps you find related information.

Tag Types​

Difficulty Levels​

  • 🟢 Beginner - Suitable for newcomers to the topic
  • 🟡 Intermediate - Requires basic understanding of the concepts
  • 🔴 Advanced - For experienced users with deep knowledge

Content Types​

  • 📚 Tutorial - Step-by-step learning content
  • 🗺️ Guide - Practical how-to instructions
  • 📖 Reference - Detailed API and technical documentation
  • 💡 Example - Code examples and demonstrations
  • 🧠 Concept - Theoretical explanations and concepts

Topic Tags​

Content is also tagged by topic areas such as:

  • getting-started
  • query-builder
  • schema-validation
  • batch-operations
  • performance
  • troubleshooting

Using Tags​

  • Tags appear at the top of each article
  • Click on tags to find related content
  • Use the tag filter on listing pages
  • Browse by difficulty level to find appropriate content

Cross-Reference System​

The documentation includes automatic cross-referencing that links related concepts throughout the content.

Automatic Linking​

Key terms are automatically linked to their definitions or detailed explanations:

  • Apache AGE - Links to glossary definition
  • Cypher - Links to query language documentation
  • Query Builder - Links to API reference
  • Schema Validation - Links to validation guide
  • Batch Loader - Links to batch operations documentation

Hover Previews​

When you hover over a cross-referenced term, you'll see a preview tooltip with:

  • Brief definition of the term
  • Category information
  • Link to full documentation

Example Usage​

When reading about "Apache AGE queries", the term "Apache AGE" will be automatically linked to provide context and additional information.

At the end of each documentation page, you'll find suggestions for related articles.

  1. Manual Relationships - Explicitly defined in the page frontmatter
  2. Tag Similarity - Articles with similar tags
  3. Category Relationships - Articles in related categories
  4. Reading Progression - Logical next steps in learning

Article Information​

Each related article shows:

  • Title and Description - Clear overview of the content
  • Difficulty Level - Helps you choose appropriate next steps
  • Category - Shows the content area
  • Direct Links - Quick navigation to related content

Comprehensive Glossary​

The glossary provides searchable definitions for all terms used in the documentation.

Features​

  • Search Functionality - Find terms quickly by name or description
  • Category Filtering - Browse terms by category (Database, API, etc.)
  • Cross-References - Links between related terms
  • Examples - Code examples and usage patterns
  • External Resources - Links to additional documentation

Categories​

  • Database - PostgreSQL, Apache AGE, transactions
  • Query Language - Cypher, query building, patterns
  • API - Client methods, interfaces, types
  • Graph Concepts - Vertices, edges, properties, labels
  • Performance - Optimization, batch operations, pooling
  • Validation - Schema validation, error handling

Using the Glossary​

  1. Browse by Category - Use the category filter to explore specific areas
  2. Search Terms - Type in the search box to find specific definitions
  3. Follow Cross-References - Click on related terms to explore connections
  4. View Examples - See practical usage examples for each term

Last Updated Information​

Each page shows when it was last updated, helping you understand the currency of the information.

Features​

  • Timestamp Display - Shows the last modification date
  • Author Information - When available, shows who made the update
  • Version Tracking - Helps identify the most current information

Edit This Page​

Every documentation page includes an "Edit this page" link that takes you directly to the source file on GitHub.

Benefits​

  • Community Contributions - Easy way to suggest improvements
  • Error Reporting - Quick access to report issues
  • Transparency - See the source markdown for any page
  • Version History - Access to the full change history

Best Practices​

For Readers​

  1. Use Breadcrumbs - Navigate efficiently through the documentation hierarchy
  2. Check Difficulty Levels - Start with beginner content and progress gradually
  3. Follow Cross-References - Explore linked terms to deepen understanding
  4. Read Related Articles - Expand your knowledge with suggested content
  5. Use the Glossary - Look up unfamiliar terms for quick clarification

For Contributors​

  1. Add Appropriate Tags - Help readers find your content
  2. Set Difficulty Levels - Guide readers to appropriate content
  3. Include Related Articles - Help readers find next steps
  4. Use Cross-Reference Terms - Link to existing definitions and explanations
  5. Update Timestamps - Keep the last_updated field current

Technical Implementation​

The navigation features are built using:

  • React Components - Modular, reusable UI components
  • TypeScript - Type-safe implementation with full IntelliSense
  • CSS Modules - Scoped styling with theme support
  • Docusaurus Integration - Seamless integration with the documentation platform
  • Accessibility Standards - WCAG 2.1 compliant navigation
  • Mobile Responsive - Optimized for all device sizes

Component Architecture​

Navigation System
├── Breadcrumbs Component
├── Tag System
│   ├── Difficulty Tags
│   ├── Content Type Tags
│   └── Topic Tags
├── Cross-Reference System
│   ├── Automatic Linking
│   ├── Hover Previews
│   └── Term Detection
├── Related Articles
│   ├── Manual Relationships
│   ├── Tag-Based Suggestions
│   └── Category Relationships
└── Glossary
    ├── Search Interface
    ├── Category Filtering
    └── Cross-Reference Links

Troubleshooting​

Common Issues​

  • Ensure you're on a documentation page (not a blog post or custom page)
  • Check that the page is properly configured in the sidebar

Cross-References Not Working​

  • Verify that terms match exactly (case-insensitive)
  • Check that the target pages exist
  • Ensure proper markdown formatting
  • Add related_articles to the page frontmatter
  • Verify that linked pages exist
  • Check tag configuration for automatic suggestions

Glossary Search Issues​

  • Try different search terms or partial matches
  • Use category filters to narrow results
  • Check spelling and try synonyms

Getting Help​

If you encounter issues with the navigation features:

  1. Check the Documentation - Review this guide for usage instructions
  2. Search the Glossary - Look up unfamiliar terms
  3. Use Cross-References - Follow links to related information
  4. Report Issues - Use the "Edit this page" link to report problems
  5. Community Support - Ask questions in the GitHub discussions

Next Steps​

Now that you understand the navigation features:

The enhanced navigation system is designed to make your learning journey more efficient and enjoyable. Take advantage of these features to quickly find the information you need and discover related content that expands your understanding.