Add Documentation Guide

How to add new markdown files with correct frontmatter, structure, and admin tools

Add Documentation Guide

📚 Complete Step-by-Step Guide

This guide explains how to add new documentation to the docs-angular application. The system now uses automatic discovery and hybrid navigation for optimal developer experience.

📖 For comprehensive system documentation, see Docs Angular System for detailed implementation guides.

🎯 Quick Overview

Adding documentation involves 2 main steps (navigation and routes are automatic):

  1. Create markdown files in the correct language AND project scope with proper frontmatter
  2. (Optional) Add folder metadata with _folder.md to control section icon/order/collapsed

⚙️ Documentation Root Configuration

The docs-angular system now supports configurable documentation root paths via apps/docs-angular/docs-config.ts.

Current Configuration

Check apps/docs-angular/docs-config.ts to see where documentation files should be placed:

export const DOCS_CONFIG = {
  docsPath: 'docs',                           // Root documentation folder (ACTIVE)
  autoDiscovery: false,                       // Manual discovery mode
  docsDirectoryName: 'docs',                  // Directory name to search for
  recursiveSearch: true,                      // Search recursively
  maxSearchDepth: 3,                          // Maximum depth to search
  fallbackPaths: [
    "apps/docs-angular/src/assets/docs"       // Fallback location
  ]
}

✅ CURRENT STATUS: The system is actively using docs/ as the primary documentation root (as of January 2025).

Supported Documentation Locations

Based on the configuration above, documentation can be placed in:

  1. Primary Location: docs/ (workspace root)

    • Current configured path via docsPath: 'docs'
    • Recommended for centralized documentation

  2. Fallback Location: apps/docs-angular/src/assets/docs/

    • Legacy location for backward compatibility
    • Used when files are not found in primary location

💡 TIP: Always check docs-config.ts to confirm the active documentation root before adding files.

📁 Step 1: File Organization

Directory Structure (Language-first, Multi-project aware)

Documentation follows the same structure regardless of root location:

<DOCS_ROOT>/                         # Either docs/ or apps/docs-angular/src/assets/docs/
├── english/
│   └── public/                      # Global public docs
│       ├── documentation/
│       │   └── add-documentation.md       # Your new guide (this file)
│       │   └── docs-angular-system/
│       │       ├── index.md                   # Section landing page (optional)
│       │       └── _folder.md                 # Folder-level frontmatter (optional)
│       │       └── <your-section>/
│       │           ├── overview.md
│       │           ├── getting-started.md
│       │           └── advanced-topics.md
│       └── <your-section>/
│           ├── overview.md
│           ├── getting-started.md
│           └── advanced-topics.md
│   └── GoGrab-Space/                # Example root project (private or public scope)
│       ├── index.md                 # Project landing
│       └── apps/                      # Example app (gograb-space)
│           └── gograb-space/         # Example app (gograb-space)
│               └── index.md          # App landing
│               └── platform/         # Example platform (gograb-space-platform)
│       ├── features/
│       ├── generative-ai/
│       ├── graphs/
│       │   ├── index.md
│       │   ├── D3/
│       │   └── mermaid/
│       ├── miscellaneous/
│       │   ├── index.md
│       │   ├── miscellaneous.index.md
│       │   └── ai-generated/
│       └── troubleshooting/
│           └── index.md
└── spanish/
    ├── GoGrab-Space/
    │   ├── index.mdc
    │   ├── apps/
    │   ├── core-libs/
    │   └── libs/
    └── public/
        ├── index.es.md
        ├── api/
        │   └── mock-api/
        │       └── index.md
        ├── backend-api/
        ├── components/
        ├── desarrollo/
        ├── documentacion/
        ├── GoGrab-Space/
        │   └── sistema-almacenamiento/
        ├── la-plataforma/
        ├── libs/
        ├── miscellaneous/
        │   └── miscellaneous.index.es.md
        ├── next-steps/
        │   └── index.es.md
        ├── plan/
        │   └── index.md
        ├── platform/
        ├── sistema-almacenamiento/
        │   └── firebase/
        │       └── index.md
        ├── solucion-problemas/
        ├── widgets/
        └── yam/
            └── ai/

Current Active Root: docs/

With the current configuration (docsPath: 'docs'), the actual structure is:

docs/
├── english/
│   ├── Ai-instructions/
│   │   └── ai-instructions-index.md
│   ├── Ai-Process/
│   ├── Architecture/
│   │   └── ecosystem/
│   ├── Backend-Api/
│   │   ├── index.md
│   │   └── progress-notes/
│   ├── docs-angular-docs/
│   │   └── add-documentation.md  # This file
│   ├── docs-to-review/
│   ├── GoGrab-Pulse/
│   │   ├── index.mdc
│   │   ├── artists/
│   │   ├── guides/
│   │   └── intro/
│   ├── GoGrab-Space/
│   ├── GoGrab-Space-Deck-md/
│   ├── private/
│   └── public/
│       ├── index.md
│       ├── development/
│       │   ├── index.md
│       │   ├── angular/
│       │   ├── building/
│       │   ├── common-errors/
│       │   │   └── index.md
│       │   ├── css-dev/
│       │   │   └── index.md
│       │   ├── debugging/
│       │   ├── directives/
│       │   │   └── index.md
│       │   ├── html/
│       │   ├── libraries/
│       │   │   ├── index.md
│       │   │   └── troubleshooting/
│       │   ├── monorepo/
│       │   ├── NX/
│       │   ├── performance/
│       │   ├── styles/
│       │   ├── tools-docs/
│       │   │   └── scripts-maybe-deprecated/
│       │   ├── typescript/
│       │   └── zsh/
│       ├── features/
│       ├── generative-ai/
│       ├── graphs/
│       │   ├── index.md
│       │   ├── D3/
│       │   └── mermaid/
│       ├── miscellaneous/
│       │   ├── index.md
│       │   ├── miscellaneous.index.md
│       │   └── ai-generated/
│       └── troubleshooting/
│           ├── index.md
│           └── quick-reference/
└── spanish/
    ├── GoGrab-Space/
    │   ├── index.mdc
    │   ├── apps/
    │   ├── core-libs/
    │   └── libs/
    └── public/
        ├── index.es.md
        ├── api/
        │   └── mock-api/
        │       └── index.md
        ├── backend-api/
        ├── components/
        ├── desarrollo/
        ├── documentacion/
        ├── GoGrab-Space/
        │   └── sistema-almacenamiento/
        ├── la-plataforma/
        ├── libs/
        │   └── sistemas/
        │       └── sistema-iconos/
        ├── miscellaneous/
        │   └── miscellaneous.index.es.md
        ├── next-steps/
        │   └── index.es.md
        ├── plan/
        │   └── index.md
        ├── platform/
        ├── sistema-almacenamiento/
        │   └── firebase/
        │       └── index.md
        ├── solucion-problemas/
        ├── widgets/
        └── yam/
            └── ai/

Creating Documentation Files

⚠️ IMPORTANT: Use the configured documentation root from docs-config.ts. Currently set to: docs/

Single Document

# Create a single markdown file (English) - Using current configured root
touch docs/english/public/my-new-guide.md

# Create a Spanish placeholder (recommended)
touch docs/spanish/public/mi-nueva-guia.es.md

# Alternative: Using fallback location
touch apps/docs-angular/src/assets/docs/english/public/my-new-guide.md

Organized Section with Multiple Files

# Create a new directory for organized documentation (English) - Using current configured root
mkdir -p docs/english/public/my-section

# Create individual files
touch docs/english/public/my-section/index.md
touch docs/english/public/my-section/overview.md
touch docs/english/public/my-section/getting-started.md
touch docs/english/public/my-section/advanced-topics.md

# Optional Spanish placeholders
mkdir -p docs/spanish/public/mi-seccion
touch docs/spanish/public/mi-seccion/index.es.md

# Alternative: Using fallback location
mkdir -p apps/docs-angular/src/assets/docs/english/public/my-section
touch apps/docs-angular/src/assets/docs/english/public/my-section/index.md

Markdown File Best Practices

File Naming Convention

Header Structure for Navigation

# Main Title

## Section One
Content for section one...

## Section Two  
Content for section two...

### Subsection
Subsection content...

🚨 IMPORTANT: Headers generate fragment IDs automatically:

🧭 Step 2: Navigation & Routes (Automatic)

🧭 Routing Details

english/public/my-section/overview.md        → /my-section/overview
english/public/my-section/index.md           → /my-section
spanish/public/mi-seccion/overview.es.md    → /es/mi-seccion/overview
english/GoGrab-Pulse/guides/setup.md        → /GoGrab-Pulse/guides/setup
english/GoGrab-Pulse/index.md               → /GoGrab-Pulse

🧾 Templates

Template 1: Minimal

---
title: Widget Builder Overview
description: Introduction to building widgets
icon: 🧩
order: 1
created: December 2, 2025 - 2:30 PM
sessionID: 1
status: 🎯 In Progress
---

# Title
Content for the page...

## Section One
Content for section one...

## Section Two  
Content for section two...

### Subsection
Subsection content...

🧾 Frontmatter Templates

Minimal (recommended)

---
title: Widget Builder Overview
description: Introduction to building widgets
icon: 🧩
order: 1
created: December 2, 2025 - 2:30 PM
sessionID: 1
---

Advanced metadata

---
title: Component Factory Reference
description: Complete API reference for the ComponentFactory
icon: 🔧
order: 3
created: December 2, 2025 - 2:30 PM
updated: December 2, 2025 - 3:00 PM
sessionID: 1
tags: [angular, components, api]
author: Platform Team
status: published
difficulty: intermediate
estimatedReadTime: 8
toc: true
searchable: true
breadcrumbs: true
sidebar: true
layout: guide
version: 1.2.0
---

Session ID

Simple: Just a number that increments (1, 2, 3...)

Read docs/sessionID.json to get the current number.

Cross-language linking

---
title: Language‑Aware Discovery & Navigation
description: How navigation and routes adapt to the selected language
sessionID: 12-01-1-2
crossLanguageId: language-aware-discovery
languageVersions:
  en: documentation/language-aware-discovery-and-navigation
  es: documentacion/language-aware-discovery-and-navigation
---

Folder-level configuration (_folder.md)

---
title: Widgets
icon: 🧩
order: 10
collapsed: false
---

Optional description content for the folder landing entry.

🗂️ File Types You Can Add

🔐 Admin Capabilities (/admin)

Visit /admin inside docs-angular for administration tools.

Modifying Documentation Root via Admin

You can change the documentation root location through the Admin Configuration Editor:

  1. Navigate to /admin/config
  2. Locate the docsPath setting
  3. Update to your desired path (e.g., docs, documentation, or apps/docs-angular/src/assets/docs)
  4. Save configuration
  5. Trigger a documentation rescan to apply changes

⚠️ Note: Changes to docs-config.ts require the development server to restart to take effect.

Tips

🤖 AI Agent Authoring & Placement Guide

Follow these strict rules when generating or moving documentation:

1) Get Session ID First

cat docs/sessionID.json

Use the sessionID number. New session? Increment by 1.

2) Check the documentation root configuration

3) Choose the correct language and project

4) Create the right files

5) Add frontmatter correctly

---
title: My Title
description: Brief description
icon: 📚
created: December 2, 2025 - 2:30 PM
sessionID: 1
order: 1
---

6) Verify links and routes

7) Refresh navigation

8) Never modify Angular routes or hardcode language prefixes

🚀 Recent Performance Improvements

The documentation system has been significantly optimized for better performance and user experience:

⚡ Faster Loading Times

🔧 Enhanced File Detection

🔄 Request Deduplication

🔗 Relative Link Resolution

🔗 Writing Links in Documentation

The docs-angular system intelligently handles both internal and external links with different behaviors:

⚡ Internal Links (Fast Client-Side Navigation)

Use absolute paths starting with / for internal documentation:

[Documentation Guide](/documentation/add-documentation)
[Getting Started](/getting-started)
[Theme System](/GoGrab-Space/theme-system)
[Apps Overview](/apps)

✅ Benefits:

🆕 Internal Links in New Tab

To open internal documentation in a new tab within the docs-angular app, add "new tab" in the title:

[Documentation Guide](/documentation/add-documentation "Open in new tab")
[Theme System](/GoGrab-Space/theme-system "new tab")
[Apps Overview](/apps "Open this in new tab")

✅ Features:

🌐 External Links (Open in New Tab)

External links automatically open in new tabs with a visual indicator:

[Angular Documentation](https://angular.dev)
[GitHub Repository](https://github.com/your-repo)
[Email Contact](mailto:[email protected])
[Phone Number](tel:+1234567890)

✅ Features:

📎 Anchor Links (Same Page Sections)

Link to sections within the same page:

[Jump to Section](#section-name)
[Configuration Details](#configuration-details)
[Common Issues](#common-issues--solutions)

✅ Auto-generated anchors:

🎯 Link Best Practices

✅ DO:

<!-- Internal links with absolute paths -->
[Documentation](/documentation)
[Apps Guide](/apps/singularity)

<!-- External links with full URLs -->
[Angular Docs](https://angular.dev)
[GitHub](https://github.com/user/repo)

<!-- Anchor links with proper format -->
[See Configuration](#configuration-section)

❌ DON'T:

<!-- Relative paths (cause routing issues) -->
[Guide](./guide.md)
[Parent](../parent.md)

<!-- File extensions (not needed) -->
[Guide](/documentation/guide.md)

<!-- Hardcoded language prefixes -->
[Spanish Guide](/es/documentation/guide)

🔍 How Link Detection Works

The system automatically determines link types:

  1. External Links - Detected by:

    • URLs starting with http:// or https://
    • URLs with mailto: or tel: protocols
    • URLs containing domains (dots without leading slash)

  2. Internal Links - Everything else:

    • Paths starting with / (absolute paths)
    • Anchor links starting with #
    • Relative paths (though not recommended)

🚀 Performance Benefits

Internal Links:

External Links:

🔧 Common Issues & Solutions

Issue 1: Fragment Links Not Working

Problem: Links like #section-name don't scroll to the correct section

Solution: Ensure headers are simple and clean

<!-- ✅ GOOD - Simple headers -->
## Widget Economy
## Development Roadmap  
## Immediate Action Plan

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

Issue 2: File Not Loading (Shows Fallback Content)

Problem: Navigation link goes to page but shows generic fallback content

Solution: Check path consistency and verify the configured documentation root

// Navigation link
{ text: 'My Guide', link: '/my-guide' }

// Route path  
{ path: 'my-guide', ... }

// File location (check docs-config.ts for active root)
docs/english/public/my-guide.md                           // Current configured root
// OR
apps/docs-angular/src/assets/docs/english/public/my-guide.md  // Fallback location

Issue 3: URL Encoding in Fragments

Problem: URLs show %23section-name instead of #section-name

Solution: This is automatically handled by the dynamic-page.component.ts - fragments are stripped for content loading but preserved for navigation.

📝 Complete Example: Adding a New Feature Guide

Let's walk through adding a complete "Widget Builder Guide" using the configured documentation root:

Step 1: Create Files

# Using current configured root (docs/)
# Create directory structure
mkdir -p docs/english/public/guides/widget-builder

# Create documentation files
touch docs/english/public/guides/widget-builder/overview.md
touch docs/english/public/guides/widget-builder/creating-widgets.md
touch docs/english/public/guides/widget-builder/advanced-features.md

# Alternative: Using fallback location
mkdir -p apps/docs-angular/src/assets/docs/english/public/guides/widget-builder
touch apps/docs-angular/src/assets/docs/english/public/guides/widget-builder/overview.md

Step 2: Write Content

<!-- docs/english/public/guides/widget-builder/overview.md -->
---
title: Widget Builder Guide
description: Complete guide to building widgets
icon: 🧩
order: 1
---

# Widget Builder Guide

## Introduction
Welcome to the comprehensive Widget Builder guide...

## Getting Started
Here's how to start building widgets...

## Core Concepts
Understanding the widget architecture...

Step 3: Refresh Navigation (optional)

Use the Admin Dashboard → Documentation Management → Run Scan to refresh immediately, or rely on the watch process.

✅ Verification Checklist

After adding new documentation, verify everything works:

File Structure Check

Navigation Check

Route Check

Content Check

🚀 Advanced Tips

Organizing Large Documentation Sets

<DOCS_ROOT>/                         # Currently: docs/
├── english/
│   └── public/
│       └── feature-name/
│           ├── overview.md (main entry point)
│           ├── getting-started.md
│           ├── configuration.md
│           ├── api-reference.md
│           └── troubleshooting.md

Configuration Management

// apps/docs-angular/docs-config.ts
export const DOCS_CONFIG = {
  docsPath: 'docs',                    // Change this to modify root location
  autoDiscovery: false,                // Enable for automatic discovery
  recursiveSearch: true,               // Search nested directories
  maxSearchDepth: 3,                   // Limit search depth
  fallbackPaths: [                     // Backup locations
    "apps/docs-angular/src/assets/docs"
  ]
}

Using Consistent Naming Patterns

Markdown Enhancement Features

The docs system supports:

Performance Considerations

🎯 Summary

Adding documentation is a streamlined 2-step process with automatic routing:

  1. ⚙️ Check Configuration: Verify the active documentation root in apps/docs-angular/docs-config.ts (currently: docs/)
  2. 📁 Create Files: Add markdown files with proper frontmatter in the configured location
  3. 🚀 Automatic Processing: Navigation and routes are generated automatically via discovery services

Key Points to Remember:

Configuration Flexibility: The system supports flexible documentation root configuration, allowing you to:

Follow this guide and your documentation will integrate seamlessly with the docs-angular application!

Guide created based on GoGrab Space documentation implementation experience
Last updated: December 2025
Session ID: 1