Docs Angular Guide

Complete guide for using, configuring, and extending the docs-angular application

Docs Angular Guide

Welcome to the comprehensive guide for the docs-angular application! This modern Angular 20-based documentation system provides a beautiful, performant, and feature-rich alternative to VitePress with advanced search capabilities, interactive navigation, and intelligent content presentation.

📖 For detailed system implementation documentation, see Docs Angular System for complete development guides and technical details.

🚀 What is Docs Angular?

The docs-angular app is a standalone Angular application designed to serve as a modern documentation platform, replacing the previous VitePress system with the following key features:

📁 Project Structure

apps/docs-angular/
├── src/
│   ├── app/
│   │   ├── pages/                    # Page components for different sections
│   │   │   ├── getting-started/
│   │   │   ├── guide/
│   │   │   ├── apps/
│   │   │   ├── libs/
│   │   │   ├── examples/
│   │   │   ├── ai-instructions/
│   │   │   └── dynamic-page/         # Flexible page component
│   │   ├── services/                 # Core services
│   │   │   ├── markdown.service.ts   # Content loading and parsing
│   │   │   ├── navigation.service.ts # Navigation state management
│   │   │   └── search.service.ts     # Global search functionality
│   │   ├── shared/                   # Reusable components
│   │   │   ├── docs-page/           # Main documentation layout
│   │   │   ├── enhanced-markdown-renderer/ # Advanced markdown display
│   │   │   ├── code-block/          # Interactive code blocks
│   │   │   ├── global-search/       # Search modal interface
│   │   │   └── on-this-page/        # Table of contents sidebar
│   │   ├── app.component.ts         # Main app with navigation
│   │   └── app.routes.ts            # Routing configuration
│   └── assets/
│       └── docs/                    # Markdown documentation files
│           ├── getting-started.md
│           ├── guide/
│           ├── apps/
│           ├── libs/
│           ├── examples/
│           ├── ai-instructions/
│           └── unified-system/
└── project.json                     # Nx project configuration

📝 Adding New Documentation

Step 1: Create Markdown Files

Add your markdown files to the appropriate directory in apps/docs-angular/src/assets/docs/:

# Example: Adding a new guide
touch apps/docs-angular/src/assets/docs/guide/new-feature-guide.md

Markdown File Format:

---
title: Your Page Title
description: Brief description of the page content
layout: guide
---

# Your Page Title

Your content here with proper markdown formatting.

## Sections

Use proper heading hierarchy for automatic "On this page" navigation.

### Code Examples

```typescript
// Code blocks are automatically enhanced with copy functionality
export class ExampleComponent {
  title = 'Hello World';
}

🔗 Links

Use absolute paths for internal links: Other Guide


### Step 2: Update Navigation Structure

Edit the navigation structure in `apps/docs-angular/src/app/services/markdown.service.ts`:

```typescript
readonly navigationStructure = signal<NavigationItem[]>([
  {
    text: '🎯 Development Guides',
    items: [
      { text: 'How to Add a New App', link: '/guide/add-new-app' },
      { text: 'New Feature Guide', link: '/guide/new-feature-guide' }, // Add your new item
      // ... other items
    ]
  },
  // ... other sections
]);

Step 3: Add Routes (Optional)

For specific routes, add them to apps/docs-angular/src/app/app.routes.ts:

{
  path: 'guide/new-feature-guide',
  loadComponent: () => import('./pages/dynamic-page/dynamic-page.component').then(m => m.DynamicPageComponent),
  title: 'New Feature Guide - Editor Documentation'
}

Note: The catch-all routes should handle most cases automatically.

Step 4: Build and Test

# Build the documentation app
nx build docs-angular

# Serve for development
nx serve docs-angular

📊 Mermaid Diagrams Support

The docs-angular app now includes full support for Mermaid diagrams, allowing you to create beautiful, interactive visualizations directly within your markdown documentation.

Creating Mermaid Diagrams

Simply use fenced code blocks with the mermaid language identifier:

```mermaid
graph TD
    A[Editor-Web] -->|Button Actions| B[Singularity]
    C[Space-Map] -->|Logic Visualization| B
    D[UX-Test] -->|Widget Logic| B
    B -->|Shared Logic| E[Universal Registry]
```

Features

Supported Diagram Types

Advanced Configuration

Add titles and custom themes:

```mermaid System Architecture
graph TD
    A[Frontend] --> B[Backend]
    B --> C[Database]
```

For complete documentation and examples, see the 📊 Mermaid Diagrams Guide.

🔧 Configuration

Navigation Configuration

The navigation structure is defined in markdown.service.ts. You can:

{
  text: '📚 New Section',
  collapsed: false, // Start expanded
  items: [
    { text: 'Overview', link: '/new-section/' },
    {
      text: 'Subsection',
      items: [
        { text: 'Sub-item', link: '/new-section/sub-item' }
      ]
    }
  ]
}

Search Configuration

The search service automatically indexes all pages in the navigation structure. To configure search behavior:

  1. Modify search relevance in search.service.ts:

    private calculateRelevanceScore(indexed: SearchIndex, searchTerms: string[]): number {
  let score = 0;
  // Customize scoring logic here
  if (titleLower.includes(term)) {
    score += 15; // Increase title match weight
  }
  return score;
}

  2. Adjust search keyboard shortcuts in the same file:

    // Currently supports Cmd/Ctrl + K
if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
  // Add additional shortcuts here
}

Styling and Theming

The app uses CSS custom properties for theming. Override styles in apps/docs-angular/src/styles.scss:

:root {
  // Primary colors
  --primary: #3b82f6;
  --secondary: #8b5cf6;
  
  // Background colors
  --bg-primary: #ffffff;
  --bg-secondary: #f8f9fa;
  
  // Text colors
  --text-primary: #1f2937;
  --text-secondary: #6b7280;
  
  // Borders
  --border-subtle: rgba(128, 128, 128, 0.15);
}

// Dark mode
@media (prefers-color-scheme: dark) {
  :root {
    --bg-primary: #1f2937;
    --text-primary: #f9fafb;
    // ... override dark mode colors
  }
}

🚀 Development Workflow

Running the Development Server

# Start the docs-angular development server
nx serve docs-angular

# The app will be available at http://localhost:4200

Building for Production

# Build optimized production bundle
nx build docs-angular --configuration=production

# Output will be in dist/apps/docs-angular/

Adding New Components

  1. Create component in shared directory:

    # Example: Creating a new shared component
mkdir apps/docs-angular/src/app/shared/my-component
touch apps/docs-angular/src/app/shared/my-component/my-component.component.ts
touch apps/docs-angular/src/app/shared/my-component/my-component.component.scss

  2. Use Angular 20 standalone patterns:

    import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-my-component',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div class="my-component">
      <!-- Use @if/@for control flow -->
      @if (items().length > 0) {
        @for (item of items(); track item.id) {
          <div>{{ item.name }}</div>
        }
      }
    </div>
  `,
  styleUrls: ['./my-component.component.scss']
})
export class MyComponent {
  // Use signals for reactive state
  readonly items = signal<any[]>([]);
}

🔍 Advanced Features

Custom Markdown Extensions

The enhanced markdown renderer supports custom extensions. Add new features in enhanced-markdown-renderer.component.ts:

private parseCustomElements(content: string): string {
  // Example: Custom alert boxes
  content = content.replace(
    /:::(info|warning|error|success|tip)\s*(.*?)\s*:::/gs,
    (match, type, content) => `
      <div class="alert alert-${type}">
        <div class="alert-content">${content.trim()}</div>
      </div>
    `
  );
  
  return content;
}

Search Index Customization

Customize what content gets indexed by modifying search.service.ts:

private buildSearchIndex(items: NavigationItem[], section = ''): void {
  for (const item of items) {
    if (item.link && this.shouldIndexPage(item.link)) { // Add custom filter
      // Index the page...
    }
  }
}

private shouldIndexPage(path: string): boolean {
  // Custom logic to determine if page should be indexed
  return !path.includes('/internal/'); // Example: skip internal pages
}

Analytics Integration

Add analytics tracking in app.component.ts:

ngOnInit(): void {
  this.navigationService.initializeFromRoute();
  
  // Track page views
  this.router.events
    .pipe(filter(event => event instanceof NavigationEnd))
    .subscribe((event: NavigationEnd) => {
      // Your analytics code here
      gtag('event', 'page_view', {
        page_path: event.urlAfterRedirects
      });
    });
}

📱 Responsive Design

The docs-angular app is fully responsive with three main breakpoints:

Mobile-Specific Features

🔧 Troubleshooting

Common Issues

  1. Markdown files not loading:

    • Check file paths in assets/docs/
    • Verify project.json includes markdown files in assets
    • Ensure navigation structure includes the correct links

  2. Search not working:

    • Check that pages are included in navigation structure
    • Verify search service is properly injected
    • Check browser console for errors

  3. "On this page" not showing:

    • Ensure content has proper heading structure (h1-h6)
    • Check that content selector matches the actual content area
    • Verify component is imported and included in template

  4. Routing issues:

    • Check app.routes.ts for correct path configurations
    • Ensure catch-all routes are at the end
    • Verify navigation service path handling

Debugging

Enable debug mode by adding this to your component:

constructor() {
  if (environment.production === false) {
    console.log('Navigation structure:', this.navigationService.navigationItems());
    console.log('Current path:', this.navigationService.currentPath());
  }
}

🚀 Deployment

Building for Production

# Build with production optimizations
nx build docs-angular --configuration=production

# The output will be in dist/apps/docs-angular/

Deployment Options

  1. Static Hosting (Netlify, Vercel, GitHub Pages):

    • Upload the dist/apps/docs-angular/ folder
    • Configure rewrites for Angular routing

  2. Server Hosting:

    • Use the built files with any web server
    • Ensure proper fallback to index.html for SPA routing

  3. Integration with Existing Systems:

    • The app can be integrated as a subdirectory
    • Configure base href in angular.json for subdirectory deployment

🔮 Future Enhancements

Some ideas for extending the docs-angular app:

📚 Best Practices

Content Organization

  1. Use clear hierarchies - Structure content with proper heading levels
  2. Keep file names consistent - Use kebab-case for file names
  3. Add meaningful descriptions - Include frontmatter descriptions
  4. Link related content - Use internal links to connect topics

Performance

  1. Optimize images - Use appropriate formats and sizes
  2. Lazy load components - Use Angular's lazy loading for routes
  3. Monitor bundle size - Keep dependencies minimal
  4. Use OnPush strategy - Already implemented for better performance

Accessibility

  1. Use semantic HTML - Proper heading structure, ARIA labels
  2. Keyboard navigation - Test all features with keyboard only
  3. Screen reader friendly - Descriptive text and labels
  4. High contrast support - Test in high contrast mode

🤝 Contributing

To contribute to the docs-angular app:

  1. Follow Angular conventions - Use Angular style guide
  2. Write tests - Add unit tests for new features
  3. Update documentation - Document new features and APIs
  4. Performance first - Consider impact on bundle size and runtime

🎯 Conclusion

The docs-angular app provides a powerful, modern foundation for documentation needs. Its Angular 20-based architecture ensures excellent performance, while the rich feature set offers a superior user experience compared to traditional documentation tools.

For questions, issues, or feature requests, please refer to the project's main documentation or create an issue in the repository.

Happy documenting! 📖✨