Overview

Comprehensive documentation system guides

Documentation System Guide

📖 Comprehensive guide for AI agents on how to find, write, organize, and maintain documentation in our docs-angular system.

🎯 Quick Reference

Essential Commands

# Check active documentation root
cat apps/docs-angular/docs-config.ts

# Scan for new documentation files
yarn docs:scan

# Watch for file changes (auto-scan)
yarn docs:dev  # Starts dev server with watch mode

# Serve documentation locally
npx nx serve docs-angular  # Runs on port 5010

Key Files to Know

📚 What is docs-angular?

docs-angular is our modern Angular 20-based documentation system that:

Current Active Documentation Root: docs/ (workspace root) Fallback Location: apps/docs-angular/src/assets/docs/

🔍 How to FIND Documentation

Step 1: Determine Documentation Root

ALWAYS check the active root first:

// Read: apps/docs-angular/docs-config.ts
export const DOCS_CONFIG = {
  docsPath: 'docs',  // ← This is the active root
  fallbackPaths: ["apps/docs-angular/src/assets/docs"]
}

Current Status (as of 2025): docsPath: 'docs' is active

Step 2: Understand File Structure

Documentation follows this structure:

<DOCS_ROOT>/                          # Currently: docs/
├── english/                          # English documentation
│   ├── public/                       # Global public docs (routes start with /)
│   │   ├── documentation/            # System documentation
│   │   ├── development/              # Development guides
│   │   ├── features/                 # Feature documentation
│   │   ├── troubleshooting/         # Troubleshooting guides
│   │   └── miscellaneous/            # Miscellaneous docs
│   └── <ProjectName>/                # Project-scoped docs (routes: /ProjectName/...)
│       ├── index.md                  # Project landing page
│       └── <section>/                # Project sections
├── spanish/                           # Spanish documentation
│   ├── public/                       # Spanish public docs (routes: /es/...)
│   └── <ProjectName>/                # Spanish project docs
└── (manifests and configs)          # Auto-generated files

Step 3: Locate Specific Documentation

For Public Documentation:

For Project Documentation:

Examples:

File: docs/english/public/development/angular/index.md
URL:  /development/angular

File: docs/english/GoGrab-Space/platform/index.md
URL:  /GoGrab-Space/platform

File: docs/spanish/public/documentacion/guia.md
URL:  /es/documentacion/guia

Step 4: Use the Manifest

The manifest (docs-manifest.json) contains the complete file structure:

{
  "structure": [
    {
      "name": "documentation",
      "type": "directory",
      "path": "english/public/documentation",
      "items": [...]
    }
  ]
}

Step 5: Search Functionality

In docs-angular app:

Configuration:

✍️ How to WRITE Documentation

Step 1: Choose the Right Location

Decision Tree:

  1. Is this project-specific?

    • ✅ Yes → docs/english/<ProjectName>/<section>/file.md
    • ❌ No → Continue to step 2

  2. Is this for general development/documentation?

    • ✅ Yes → docs/english/public/documentation/ or development/
    • ❌ No → Continue to step 3

  3. Is this a feature guide?

    • ✅ Yes → docs/english/public/features/
    • ❌ No → Continue to step 4

  4. Is this troubleshooting?

    • ✅ Yes → docs/english/public/troubleshooting/
    • ❌ No → Use docs/english/public/miscellaneous/

Default Locations:

Step 2: Create the File

File Naming:

File Structure:

# Single file
docs/english/public/my-section/my-guide.md

# Organized section
docs/english/public/my-section/
├── index.md           # Landing page for section
├── overview.md        # Overview
├── getting-started.md # Getting started
└── advanced.md        # Advanced topics

For Spanish:

# Same structure, different language folder
docs/spanish/public/mi-seccion/mi-guia.md

Step 3: Add Frontmatter

Minimal Frontmatter (Recommended):

---
title: Widget Builder Overview
description: Introduction to building widgets
icon: 🧩
order: 1
---

Advanced Frontmatter:

---
title: Component Factory Reference
description: Complete API reference for the ComponentFactory
icon: 🔧
order: 3
tags: [angular, components, api]
author: Platform Team
lastUpdated: 2025-01-15
status: published
difficulty: intermediate
estimatedReadTime: 8
toc: true
searchable: true
layout: guide
crossLanguageId: component-factory-reference
languageVersions:
  en: documentation/component-factory-reference
  es: documentacion/referencia-factory-componente
---

Required Fields:

Common Fields:

Cross-Language Linking:

crossLanguageId: unique-page-id
languageVersions:
  en: section/page-name      # WITHOUT /es prefix
  es: seccion/nombre-pagina

Step 4: Write Content

Markdown Structure:

# Main Title

## Section One
Content for section one...

## Section Two
Content for section two...

### Subsection
Subsection content...

Important:

Code Blocks:

```typescript
// Use language tags for syntax highlighting
const example = "code";
\```

Step 5: Add Links Correctly

✅ DO - Absolute Paths (Recommended):

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

✅ DO - Relative Paths (Now Supported):

[Parent Section](../parent-section)
[Sibling Page](./sibling-page)

❌ DON'T:

[Guide](./guide.md)                    # No file extensions
[Guide](/documentation/guide.md)      # No .md extension
[Guide](/public/documentation/guide)   # Don't include /public/
[Guide](/english/documentation/guide)  # Don't include /english/

Anchor Links:

[Jump to Section](#section-name)
[Configuration](#configuration-details)

External Links:

[Angular Docs](https://angular.dev)  # Automatically opens in new tab

Internal Links in New Tab:

[Guide](/documentation/guide "new tab")  # Add "new tab" to title

Step 6: Folder Metadata (Optional)

Create _folder.md to control section appearance:

---
title: Widgets
icon: 🧩
order: 10
collapsed: false
---
Optional description for the folder landing.

Step 7: Refresh Navigation

After adding files:

  1. Auto-watch mode: If yarn docs:dev is running, files are auto-discovered
  2. Manual scan: Run yarn docs:scan to update manifest
  3. Admin panel: Use /admin → "Run Scan" to trigger immediately

🏗️ Project-Scoped Architecture

Understanding Project Context

The docs-angular system uses project-scoped architecture:

Features:

Project Types:

  1. Root Projects (isRoot: true) - Standalone documentation sites
  2. Public Documentation - Global shared documentation

Project Configuration:

{
  "name": "GoGrab-Pulse",
  "path": "docs/english/GoGrab-Pulse",
  "language": "english",
  "isRoot": true,
  "password": "123456",  // Optional password protection
  "config": {
    "search": { ... },
    "navigation": { ... },
    "ui": { ... }
  }
}

URL Structure

Public Docs:

Project Docs:

No Language Prefix in Frontmatter:

languageVersions:
  en: section/page-name    # System adds /es automatically
  es: seccion/nombre-pagina

🔧 Configuration System

Documentation Root Configuration

File: apps/docs-angular/docs-config.ts

export const DOCS_CONFIG = {
  docsPath: 'docs',              // Active documentation root
  autoDiscovery: false,          // Manual discovery mode
  docsDirectoryName: 'docs',
  recursiveSearch: true,
  maxSearchDepth: 3,
  fallbackPaths: [
    "apps/docs-angular/src/assets/docs"
  ]
}

⚠️ ALWAYS CHECK THIS FIRST before creating documentation files!

Project Configuration

File: apps/docs-angular/src/assets/docs-folders-config.json

Global Settings:

{
  "globalConfig": {
    "search": {
      "scopeToCurrentProject": true,
      "crossProjectSearch": false,
      "includePrivateInGlobalSearch": false,
      "maxResultsPerProject": 10
    },
    "navigation": { ... },
    "ui": { ... }
  },
  "folders": [
    {
      "name": "GoGrab-Pulse",
      "isRoot": true,
      "config": { ... }  // Project-specific overrides
    }
  ]
}

Configuration Hierarchy:

  1. Project Config (highest priority)
  2. Global Config (fallback)
  3. Built-in Defaults (last resort)

🔍 Search System

How Search Works

  1. Indexing - Builds search database from manifest
  2. Filtering - Filters results based on project scope
  3. Display - Shows results with project badges

Search Configuration

Behavior Matrix:

scopeToCurrentProject crossProjectSearch Result
true true Index all, show all
true false Index current, show current
false true Index all, show all
false false Index all, filter to current

Project-Scoped Search:

📋 Best Practices for AI Agents

Before Writing Documentation

  1. ✅ Check active docs root - Read apps/docs-angular/docs-config.ts
  2. ✅ Find existing docs - Search for similar content first
  3. ✅ Choose correct location - Use decision tree above
  4. ✅ Check project context - Is this project-specific or public?

While Writing Documentation

  1. ✅ Use proper frontmatter - Include title, description, icon, order
  2. ✅ Keep headers simple - No complex formatting for anchors
  3. ✅ Use absolute paths - /section/page format
  4. ✅ No file extensions - Don't include .md in links
  5. ✅ Test navigation - Verify links work before finishing

After Writing Documentation

  1. ✅ Trigger scan - Run yarn docs:scan or use admin panel
  2. ✅ Verify in sidebar - Check navigation appears correctly
  3. ✅ Test routes - Visit the page URL to verify rendering
  4. ✅ Check search - Verify page appears in search results
  5. ✅ Add Spanish placeholder - Create .es.md version if needed

File Organization Rules

Miscellaneous Docs:

Development Guides:

Troubleshooting:

Common Mistakes to Avoid

❌ Using wrong documentation root

❌ Including /public/ in URLs

❌ File extensions in links

❌ Complex header formatting

❌ Hardcoding language prefixes

🛠️ Admin Panel Features

Access: /admin in docs-angular

Features:

Default Password: admin123 (change in production!)

📚 Additional Resources

Key Documentation Files

System Documentation Location

All docs-angular system documentation is stored in:

docs/english/docs-angular-docs/
├── index.md                    # System overview
├── add-docs/                   # Adding documentation guides
├── config/                     # Configuration guides
├── features/                   # Feature documentation
├── technical-info/             # Technical architecture
├── progress-notes/             # Implementation history
└── troubleshooting/             # Troubleshooting guides

✅ Verification Checklist

After creating documentation, verify:

🚀 Quick Start Template

Creating a new documentation page:

  1. Choose location (e.g., docs/english/public/my-section/)
  2. Create file (e.g., my-guide.md)
  3. Add frontmatter:
---
title: My Guide Title
description: Short description for search
icon: 📚
order: 1
---
  1. Write content with simple headers
  2. Add links using absolute paths
  3. Trigger scan via admin panel or yarn docs:scan
  4. Verify in docs-angular app

📞 Need Help?

Last Updated: January 2025 Active Docs Root: docs/ (configured in `apps/docs-angular/docs-config.ts) System Version: Enhanced Documentation System with Project-Scoped Architecture