Link Guidelines for Docs-Angular

Complete guide for creating proper links in the docs-angular system

🔗 Link Guidelines for Docs-Angular

This guide provides comprehensive rules for creating proper links in the docs-angular system to ensure all navigation works correctly.

🎯 Core Principles

✅ Prefer Absolute Paths (Recommended)

<!-- ✅ CORRECT: Absolute path from root -->
[Documentation Guide](/documentation/add-documentation)

<!-- ✅ ALSO CORRECT: Relative paths now supported -->
[Documentation Guide](../documentation/add-documentation)
[Documentation Guide](./add-documentation)

<!-- ❌ WRONG: File extensions -->
[Documentation Guide](./add-documentation.md)
[Documentation Guide](/documentation/add-documentation.md)

🆕 Relative Link Support (NEW)

The system now automatically converts relative links to absolute monorepo paths:

<!-- These relative links now work automatically -->
[GoGrab Space](../GoGrab-Space)                    → /GoGrab-Space
[Theme System](../GoGrab-Space/theme-system)      → /GoGrab-Space/theme-system
[Apps Overview](./apps)                            → /apps (if in root context)

✅ No File Extensions

<!-- ✅ CORRECT: No .md extension -->
[Theme System](/GoGrab-Space/theme-system)

<!-- ❌ WRONG: With .md extension -->
[Theme System](/GoGrab-Space/theme-system.md)

✅ Follow Directory Structure

<!-- ✅ CORRECT: Matches actual file structure -->
[Enhanced Docs System](/documentation/docs-angular-system/enhanced-docs-system)

<!-- ❌ WRONG: Doesn't match structure -->
[Enhanced Docs System](/docs-angular-system/enhanced-docs-system)

📁 Path Structure Rules

Public Documentation

Files under english/public/ → Root path without /public/

File: english/public/documentation/add-documentation.md
Link: /documentation/add-documentation

Project Documentation

Files under english/ProjectName/ → Include project name

File: english/GoGrab-Pulse/intro/artist-roster.md
Link: /GoGrab-Pulse/intro/artist-roster

Subsections

Files in nested directories → Include full path

File: english/public/documentation/docs-angular-system/enhanced-docs-system.md
Link: /documentation/docs-angular-system/enhanced-docs-system

🌍 Language Support

English Links (Default)

[Getting Started](/getting-started)
[Documentation](/documentation)

Spanish Links

[Comenzar](/es/comenzar)
[Documentación](/es/documentacion)

Cross-Language Linking

Use frontmatter for intelligent language switching:

---
crossLanguageId: example-page
languageVersions:
  en: documentation/example-page
  es: documentacion/pagina-ejemplo
---

🔧 Common Link Patterns

Documentation System Links

<!-- Main documentation index -->
[Documentation](/documentation)

<!-- Specific guides -->
[Add Documentation](/documentation/add-documentation)
[Configuration Guide](/documentation/docs-configuration)
[Frontmatter System](/documentation/frontmatter-metadata-system)

<!-- System internals -->
[Enhanced Docs System](/documentation/docs-angular-system/enhanced-docs-system)
[Navigation System](/documentation/docs-angular-system/NAVIGATION-IMPROVEMENTS-COMPLETE)

Project Links

<!-- Project root -->
[GoGrab Pulse](/GoGrab-Pulse)

<!-- Project sections -->
[Artist Roster](/GoGrab-Pulse/intro/artist-roster)
[Theme System](/GoGrab-Space/theme-system)

App Links

<!-- App overview -->
[Applications](/apps)

<!-- Specific apps -->
[Singularity App](/apps/singularity)
[Editor Web](/apps/editor-web)
[Space Map](/apps/space-map)
[UX Test](/apps/ux-test)

🎯 Anchor Links (Fragments)

Section Headers

<!-- Link to specific section -->
[Multi-Language Support](/documentation/docs-angular-system/enhanced-docs-system#multi-language-support)

<!-- Headers are automatically converted to anchors -->
## Multi-Language Support  → #multi-language-support
### Getting Started Guide   → #getting-started-guide

Best Practices for Headers

<!-- ✅ GOOD: Simple, clean headers -->
## Widget Economy
## Development Roadmap
## Quick Start Guide

<!-- ❌ BAD: Complex headers with formatting -->
## 🧩 **WIDGET ECONOMY ARCHITECTURE**
## 🗺️ **THE DEVELOPMENT ROADMAP**

🆕 Relative Link Resolution (NEW FEATURE)

How It Works

The system automatically converts relative links to absolute monorepo paths:

<!-- From within /GoGrab-Space/libs-structural/ux-test-lib/ -->
[Directory:](../libs-structural)                    → /GoGrab-Space/libs-structural
[Parent Project:](../../GoGrab-Space)              → /GoGrab-Space
[Theme System:](../../GoGrab-Space/theme-system)   → /GoGrab-Space/theme-system

Supported Patterns

../ patterns: Navigate up directory levels
./ patterns: Navigate within current directory
Context-aware: Automatically detects project boundaries
Monorepo-aware: Converts to proper absolute paths

Examples

<!-- In /GoGrab-Space/libs-structural/ux-test-lib/ux-test -->
[Back to Structural](../libs-structural)           → /GoGrab-Space/libs-structural
[GoGrab Space Home](../../GoGrab-Space)            → /GoGrab-Space
[Theme System](../../GoGrab-Space/theme-system)    → /GoGrab-Space/theme-system

<!-- In /apps/singularity/ -->
[Apps Overview](../apps)                           → /apps
[Editor Web](../editor-web)                        → /apps/editor-web

🚨 Common Mistakes to Avoid

❌ File Extension Mistakes

<!-- DON'T USE THESE -->
[Guide](./guide.md)           <!-- Relative with extension -->
[Guide](../guide.md)          <!-- Parent directory with extension -->
[Guide](guide/index.md)       <!-- Subdirectory with extension -->
[Guide](/documentation/guide.md)
[Guide](/documentation/guide.html)

❌ Path Structure Mistakes

<!-- DON'T USE THESE -->
[Guide](/public/documentation/guide)     <!-- Including /public/ -->
[Guide](/english/documentation/guide)    <!-- Including /english/ -->
[Guide](/docs/guide)                     <!-- Wrong base path -->

🔍 Testing Your Links

Manual Testing

Start the docs-angular development server: nx serve docs-angular
Navigate to your page
Click each link to verify it works
Check browser console for 404 errors

Link Validation Checklist

Link uses absolute path from root (/section/page)
No file extensions (.md, .html)
Matches actual file structure in manifest
Works in both English and Spanish (if applicable)
Anchor links point to actual headers

🛠️ Debugging Broken Links

404 Errors

If you get a 404 error:

Check the file actually exists in the correct location
Verify the path matches the manifest structure
Ensure no typos in the path
Run yarn docs:scan to update the manifest

Wrong Page Loading

If the wrong page loads:

Check for duplicate file names
Verify the full path is unique
Check for conflicting routes

Console Debugging

Look for these console messages:

🧭 Navigating to: /documentation/guide
✅ Navigation successful: /documentation/guide
❌ Nav failed: /documentation/wrong-path

📋 Quick Reference

Template for New Links

<!-- Internal documentation -->
[Page Title](/section/page-name)

<!-- Project documentation -->
[Page Title](/ProjectName/section/page-name)

<!-- With anchor -->
[Section Title](/section/page-name#section-anchor)

<!-- Cross-language (use frontmatter) -->
crossLanguageId: unique-page-id
languageVersions:
  en: section/page-name
  es: seccion/nombre-pagina

Common Paths

<!-- Documentation -->
/documentation                           <!-- Main docs index -->
/documentation/add-documentation         <!-- How to add docs -->
/documentation/docs-configuration        <!-- Configuration guide -->
/documentation/docs-angular-system/      <!-- System internals -->

<!-- Apps -->
/apps                                    <!-- Apps overview -->
/apps/singularity                        <!-- Singularity app -->
/apps/editor-web                         <!-- Editor Web app -->

<!-- Projects -->
/GoGrab-Pulse                           <!-- GoGrab Pulse project -->
/GoGrab-Space                           <!-- GoGrab Space project -->

<!-- Core pages -->
/getting-started                         <!-- Getting started -->
/troubleshooting                         <!-- Troubleshooting -->

🎉 Best Practices Summary

Always use absolute paths starting with /
Never include file extensions (.md, .html)
Follow the actual directory structure from the manifest
Test all links before committing
Use frontmatter for cross-language linking
Keep headers simple for reliable anchor links
Update links when moving or renaming files

Following these guidelines ensures all links work correctly and provides a seamless navigation experience for users of the docs-angular system.

Need help? Check the Documentation Configuration guide or review the Enhanced Documentation System for more details.