🎯 Frontmatter Metadata System

The documentation system now supports rich frontmatter metadata in .md files, allowing you to control navigation, icons, ordering, and much more without touching any code.

🚀 Quick Start

Add YAML frontmatter to the top of any .md file:

---
title: My Amazing Guide
description: A comprehensive guide to amazing things
icon: 🌟 // Include the icon of the documentation.
order: 1
category: guides // Include the category of the documentation.
tags: [tutorial, beginner-friendly] // Include the tags of the documentation.
author: Your Name // Include the author of the documentation.
created: November 6, 2025 - 10:00 AM // Double check the date and time is correct.
updated: November 14, 2025 - 8:00 AM EST // Double check the date and time is correct.
sessionID: 125.1 // This is the session ID of the session that the documentation was created in.
status: published // Include the status of the documentation.
difficulty: beginner // Include the difficulty level of the documentation.
estimatedReadTime: 5 // Include the estimated reading time of the documentation.
toc: true // Include the table of contents of the documentation.
searchable: true // Include the searchable flag of the documentation.
breadcrumbs: true // Include the breadcrumbs flag of the documentation.  
sidebar: true // Include the sidebar flag of the documentation.
purpose: The definitive architectural document integrating all systems // Include the purpose of the documentation.
---

# Your content starts here...

📋 Complete Property Reference

✅ Basic Metadata

🎨 Visual & Navigation

🏷️ Organization

⏱️ User Experience

🎛️ UI Controls

🎨 Icon System

The new system supports both emojis and URLs:

📱 Emoji Icons

icon: 🚀  # Rocket emoji
icon: 🎵  # Musical note
icon: 🔧  # Wrench tool

🖼️ URL Icons (SVG, PNG, etc.)

icon: https://gograb.io/media/icons/svg/static/sun.svg
icon: /assets/icons/custom-icon.png
icon: https://cdn.example.com/lottie/animation.lottie

Supported formats:

• ✅ SVG (vector graphics)
• ✅ PNG/JPG (raster images)
• ✅ GIF (animated)
• ✅ WebP (modern format)
• 🔮 Lottie (future support)

🎨 Theme System Integration

The frontmatter system now fully integrates with your AI-Powered Theme System, matching the structure from theme-system.md:

Complete Theme Configuration

theme:
  name: gograb-pulse-music-ai
  type: feature  # framework | feature | core | foundation
  brandArchetype: Creator  # Hero, Sage, Innovator, Creator, etc.
  industry: entertainment  # healthcare, finance, technology, etc.
  designStyle: modern  # modern, classic, minimal, bold, playful, professional
  accessibilityLevel: AA  # AA or AAA
  primaryColors: ["#FF6B6B", "#4ECDC4", "#45B7D1"]
  visualEffects:
    neumorphism: false
    glassmorphism: true
    gradients: true
    animations: true
  componentVariations:
    buttons: music-creator-style
    cards: album-card-style
    forms: audio-input-style
    navigation: studio-nav-style

Performance & Analytics

performance:
  loadPriority: high  # high | normal | low
  cacheStrategy: aggressive  # aggressive | normal | minimal
  preload: true

Internationalization

i18n:
  translationKey: gograb-pulse-intro
  rtlSupport: false
  culturalAdaptations: [music-industry-global, ai-ethics-considerations]

📁 Folder-Scoped Ordering

The order property works within each folder, not globally:

📁 guides/
  ├── 📄 intro.md (order: 1)      ← Shows first in guides
  ├── 📄 advanced.md (order: 2)   ← Shows second in guides  
  └── 📄 tips.md (order: 3)       ← Shows third in guides

📁 tutorials/
  ├── 📄 basics.md (order: 1)     ← Shows first in tutorials
  └── 📄 expert.md (order: 2)     ← Shows second in tutorials

🔄 Backwards Compatibility

The system is fully backwards compatible:

1. Files without frontmatter → Use hardcoded getSectionConfig() fallback
2. Files with partial frontmatter → Mix frontmatter + fallback values
3. Files with complete frontmatter → Use frontmatter exclusively

🌍 Language Support & Cross-Language Linking

Basic Language Support:

---
title: Getting Started
description: Learn the basics of our platform
language: en
---

🚀 WORKING: Cross-Language Linking System

Our documentation system now supports intelligent cross-language linking that allows users to switch languages while staying on the same conceptual page. When a user switches languages, the system will navigate to the equivalent page in the target language.

📍 File Location Guide:

English Files: apps/docs-angular/src/assets/docs/english/public/[section]/[filename].md Spanish Files: apps/docs-angular/src/assets/docs/spanish/public/[section]/[filename].es.md

🔧 Implementation Example:

English File (apps/docs-angular/src/assets/docs/english/public/documentation/language-aware-discovery-and-navigation.md):

---
title: Language‑Aware Discovery & Navigation
description: Navigation labels, links, and routes now derive strictly from the selected language
layout: guide
crossLanguageId: language-aware-discovery-navigation
created: November 6, 2025 - 10:00 AM // Double check the date and time is correct.
updated: November 14, 2025 - 8:00 AM EST // Double check the date and time is correct.
languageVersions:
  en: documentation/language-aware-discovery-and-navigation
  es: documentacion/language-aware-discovery-and-navigation
---

Spanish File (apps/docs-angular/src/assets/docs/spanish/public/documentacion/language-aware-discovery-and-navigation.es.md):

---
title: Sistema de navegación basado en idioma
description: Placeholder en español para documentar el comportamiento basado en idioma
layout: guide
crossLanguageId: language-aware-discovery-navigation
created: Noviembre 6, 2025 - 10:00 AM EST // Double check the date and time is correct.
updated: Noviembre 14, 2025 - 8:00 AM EST // Double check the date and time is correct.
sessionID: 125.1 // This is the session ID of the session that the documentation was created in.
languageVersions:
  en: documentation/language-aware-discovery-and-navigation
  es: documentacion/language-aware-discovery-and-navigation
---

🎯 Key Points:

1. Same crossLanguageId: Both files must have identical crossLanguageId values
2. Path Mapping: The languageVersions object maps language codes to their respective paths
3. No Language Prefix: Paths in languageVersions should NOT include /es/ prefix - the system handles this automatically
4. Directory Structure: Spanish sections may have different names (e.g., documentation → documentacion)

🌐 URL Behavior:

• Spanish URL: /es/documentacion/language-aware-discovery-and-navigation
• English URL: /documentation/language-aware-discovery-and-navigation
• Language Switch: Automatically navigates between these URLs when user changes language

Cross-Language Properties:

🚨 Important Notes:

• File Extensions: Spanish files use .es.md extension
• Directory Names: Spanish directories often use translated names (documentation → documentacion)
• Path Resolution: The system automatically handles language prefixes and file extensions
• Fallback: If cross-language linking fails, the system falls back to directory translation

🎯 Real-World Examples

Tutorial Page

---
title: Creating Your First AI Song
description: Step-by-step guide to generating music with Suno AI
icon: 🎵
order: 1
category: tutorials
tags: [ai, music, suno, beginner]
author: Music Team
difficulty: beginner
estimatedReadTime: 10
prerequisites: [basic-music-theory]
relatedPages: [voice-generation, advanced-techniques]
created: November 6, 2025 - 10:00 AM // Double check the date and time is correct.
updated: November 14, 2025 - 8:00 AM EST // Double check the date and time is correct.
sessionID: 125.1 // This is the session ID of the session that the documentation was created in.
status: published // Include the status of the documentation.
purpose: The definitive architectural document integrating all systems // Include the purpose of the documentation.
featured: true
toc: true
searchable: true
breadcrumbs: true
sidebar: true
---

API Reference

---
title: Authentication API
description: Complete reference for authentication endpoints
icon: https://api-docs.example.com/icons/auth.svg
order: 1
category: api-reference
tags: [api, authentication, security]
difficulty: intermediate
estimatedReadTime: 15
created: November 6, 2025 - 10:00 AM // Double check the date and time is correct.
updated: November 14, 2025 - 8:00 AM EST // Double check the date and time is correct.
sessionID: 125.1 // This is the session ID of the session that the documentation was created in.
status: published
toc: true
searchable: true
---

Troubleshooting Guide

---
title: Common Issues & Solutions
description: Resolve the most frequent problems quickly
icon: 🛠️
order: 999
category: troubleshooting
tags: [troubleshooting, faq, solutions]
difficulty: beginner
estimatedReadTime: 8
created: November 6, 2025 - 10:00 AM // Double check the date and time is correct.
updated: November 14, 2025 - 8:00 AM EST // Double check the date and time is correct.
status: published
featured: false
---

🚀 Migration Guide

Step 1: Identify High-Priority Pages

Start with your most important documentation:

• Index pages (index.md)
• Getting started guides
• Popular tutorials

Step 2: Add Basic Frontmatter

Begin with essential properties:

---
title: Page Title
description: Brief description
icon: 🚀
order: 1
created: November 6, 2025 - 10:00 AM // Double check the date and time is correct.
updated: November 14, 2025 - 8:00 AM EST // Double check the date and time is correct.
---

Step 3: Enhance Gradually

Add more metadata over time:

---
title: Page Title
description: Brief description  
icon: 🚀
order: 1
category: guides
tags: [tutorial, beginner]
difficulty: beginner
estimatedReadTime: 5
created: November 6, 2025 - 10:00 AM // Double check the date and time is correct.
updated: November 14, 2025 - 8:00 AM EST // Double check the date and time is correct.
---

Step 4: Custom Icons

Replace emojis with branded SVG icons:

---
icon: https://your-domain.com/icons/custom.svg
---

💡 Best Practices

✅ Do:

• Use descriptive titles and descriptions
• Choose appropriate difficulty levels
• Estimate reading times accurately
• Use consistent tagging conventions
• Provide meaningful prerequisites
• Use folder-scoped ordering (1, 2, 3...)

❌ Don't:

• Use extremely long titles (>60 chars)
• Skip descriptions for important pages
• Use random order numbers (use sequential: 1, 2, 3)
• Mix emoji and URL icons inconsistently
• Forget to update lastUpdated dates

🔮 Future Enhancements

Coming soon:

• 🎬 Lottie animation support
• 🎨 Custom CSS per page
• 📊 Analytics integration
• 🔗 Auto-generated related pages
• 🌐 Multi-language linking
• 📱 Mobile-specific layouts

🎉 Get Started Today!

The frontmatter metadata system is live and ready to use. Start enhancing your documentation with rich metadata and watch your navigation come alive with custom icons, perfect ordering, and enhanced user experience!

Questions? Check out our Configuration Guide or reach out to the GoGrab Team.