📚 Documentation Site Expansion with Nuxt Content Module

[productdevbook]

📚 Documentation Site Expansion with Nuxt Content Module

Overview

Expand the existing documentation site in the docs folder to create a comprehensive documentation platform using Nuxt Content module. The current site has a beautiful landing page, but needs structured documentation with navigation, search, and interactive components.

Goals

• Create a comprehensive documentation structure
• Implement interactive components and navigation
• Provide excellent developer experience
• Support markdown-based content authoring
• Enable easy content updates and contributions

Implementation Plan

1. 🔧 Setup and Configuration

Install Nuxt Content Module

• Add @nuxt/content dependency to docs/package.json
• Configure content module in docs/nuxt.config.ts
• Set up content sources and markdown processing
• Configure syntax highlighting and MDC components
• Add content watcher for development

Update Dependencies

cd docs
pnpm add @nuxt/content
pnpm add @nuxtjs/mdc
pnpm add shiki # for syntax highlighting

Configuration Updates

// docs/nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/content',
    // ... existing modules
  ],
  content: {
    highlight: {
      theme: {
        default: 'github-light',
        dark: 'github-dark'
      },
      preload: ['json', 'js', 'ts', 'html', 'css', 'vue', 'diff', 'shell', 'markdown']
    },
    markdown: {
      mdc: true
    }
  }
})

2. 📁 Content Structure

Create Content Directory Structure

docs/content/
├── index.md                           # Documentation home
├── 1.introduction/
│   ├── 1.getting-started.md
│   ├── 2.why-nitroping.md
│   ├── 3.architecture.md
│   └── 4.features.md
├── 2.installation/
│   ├── 1.requirements.md
│   ├── 2.quick-start.md
│   ├── 3.docker-setup.md
│   ├── 4.manual-installation.md
│   └── 5.environment-variables.md
├── 3.api/
│   ├── index.md
│   ├── 1.graphql-overview.md
│   ├── 2.authentication.md
│   ├── 3.apps.md
│   ├── 4.devices.md
│   ├── 5.notifications.md
│   ├── 6.mutations.md
│   └── 7.queries.md
├── 4.sdks/
│   ├── index.md
│   ├── 1.ios/
│   │   ├── index.md
│   │   ├── installation.md
│   │   ├── configuration.md
│   │   └── usage.md
│   ├── 2.android/
│   │   ├── index.md
│   │   ├── installation.md
│   │   ├── configuration.md
│   │   └── usage.md
│   ├── 3.web/
│   │   ├── index.md
│   │   ├── setup.md
│   │   └── integration.md
│   └── 4.coming-soon/
│       ├── react-native.md
│       ├── flutter.md
│       └── unity.md
├── 5.deployment/
│   ├── index.md
│   ├── 1.docker-compose.md
│   ├── 2.kubernetes.md
│   ├── 3.cloud-providers.md
│   ├── 4.reverse-proxy.md
│   └── 5.monitoring.md
├── 6.configuration/
│   ├── index.md
│   ├── 1.environment-variables.md
│   ├── 2.database.md
│   ├── 3.providers.md
│   └── 4.security.md
└── 7.guides/
    ├── index.md
    ├── 1.first-notification.md
    ├── 2.batch-notifications.md
    ├── 3.analytics.md
    └── 4.troubleshooting.md

Create Frontmatter Templates

• Define consistent frontmatter structure for all content types
• Include title, description, navigation order, and SEO metadata
• Set up page categories and tags

Example frontmatter:

---
title: 'Getting Started with NitroPing'
description: 'Learn how to set up and use NitroPing for your push notifications'
navigation: 
  title: 'Getting Started'
  order: 1
category: 'introduction'
tags: ['setup', 'quickstart']
---

3. 🎨 Documentation Components

Core Documentation Components

• DocsNavigation.vue - Sidebar navigation with collapsible sections
• DocsToc.vue - Table of contents for current page
• DocsSearch.vue - Full-text search with fuzzy matching
• DocsPrevNext.vue - Navigation between pages
• DocsCodeBlock.vue - Enhanced code blocks with copy functionality
• DocsBreadcrumb.vue - Breadcrumb navigation
• DocsAlert.vue - Callout boxes for tips, warnings, etc.
• DocsCard.vue - Card layout for feature highlights
• DocsTabs.vue - Tabbed content for multi-platform examples

MDC Components for Content

<!-- Example: GraphQL Code Block -->
<template>
  <div class="docs-graphql-example">
    <div class="tabs">
      <button @click="activeTab = 'query'">Query</button>
      <button @click="activeTab = 'response'">Response</button>
    </div>
    <CodeBlock 
      :code="activeTab === 'query' ? query : response" 
      :language="activeTab === 'query' ? 'graphql' : 'json'"
    />
  </div>
</template>

Interactive Examples

• ApiPlayground.vue - Live GraphQL playground
• PlatformTabs.vue - Switch between iOS/Android/Web examples
• ConfigurationForm.vue - Interactive configuration builder

4. 🔧 Pages and Layout

Documentation Layout

• Create docs/app/layouts/docs.vue with three-column layout
• Implement responsive sidebar with mobile menu
• Add dark mode support with theme persistence
• Include progress indicator for reading

Dynamic Documentation Pages

• Create docs/app/pages/docs/[...slug].vue for content rendering
• Implement automatic breadcrumb generation
• Add reading time estimation
• Include page metadata and SEO optimization

Navigation Integration

• Auto-generate navigation from content structure
• Implement active page highlighting
• Add search results page
• Create 404 page for missing documentation

5. 📝 Content Creation

Core Documentation Pages

Introduction Section

• Getting Started guide with step-by-step setup
• Why NitroPing? (benefits, comparison)
• Architecture overview with diagrams
• Feature highlights and use cases

Installation Section

• System requirements and prerequisites
• Quick start with Docker Compose
• Manual installation guide
• Environment variables reference
• Database setup instructions

API Documentation

• GraphQL overview and concepts
• Authentication and API keys
• Apps management (CRUD operations)
• Device registration and management
• Notification sending and targeting
• Complete mutations reference
• Complete queries reference
• Error handling guide

SDK Documentation

• iOS SDK complete guide
  • Installation via Swift Package Manager
  • Configuration and initialization
  • Push notification registration
  • Handling notifications
  • Example integrations
• Android SDK complete guide
  • Gradle installation
  • Kotlin/Java configuration
  • FCM token handling
  • Notification reception
• Web Push guide
  • Service worker setup
  • VAPID configuration
  • Browser compatibility

Deployment Guides

• Docker Compose production setup
• Kubernetes deployment manifests
• Cloud provider guides (AWS, GCP, Digital Ocean)
• Reverse proxy configuration (nginx, Traefik)
• Monitoring and logging setup
• Backup and disaster recovery

Configuration Reference

• Complete environment variables list
• Database configuration options
• Push provider settings (APNs, FCM, Web Push)
• Security configuration best practices
• Performance tuning guide

Guides and Tutorials

• Sending your first notification
• Batch notification strategies
• Analytics and delivery tracking
• Troubleshooting common issues
• Migration from other services

6. 🔍 Search and Navigation Features

Search Implementation

• Implement full-text search using Nuxt Content's search capabilities
• Add search shortcuts (Ctrl+K / Cmd+K)
• Create search results page with highlighting
• Add autocomplete and suggestions
• Implement search analytics

Navigation Enhancements

• Keyboard navigation support (arrow keys, tab)
• Quick navigation with hotkeys
• Bookmarkable URLs for all sections
• Print-friendly CSS for documentation
• Export to PDF functionality (future enhancement)

7. 📱 Mobile and Accessibility

Mobile Optimization

• Responsive navigation with collapsible sidebar
• Touch-friendly interactive elements
• Optimized code block scrolling
• Mobile search interface

Accessibility

• ARIA labels for all interactive elements
• Keyboard navigation support
• Screen reader compatibility
• High contrast mode support
• Focus management for navigation

8. ⚡ Performance and SEO

Performance Optimization

• Image optimization for screenshots and diagrams
• Code splitting for documentation components
• Lazy loading for content sections
• Service worker for offline reading

SEO Optimization

• Generate sitemap for all documentation pages
• Meta tags and Open Graph data
• Structured data markup
• Canonical URLs for content
• RSS feed for updates (future)

9. 🚀 Deployment and CI/CD

Documentation Deployment

• Set up automated deployment for docs changes
• Configure preview deployments for pull requests
• Add documentation build to CI pipeline
• Set up content validation (links, formatting)

Content Management

• Create content contribution guidelines
• Set up automated content linting
• Add change detection for documentation updates
• Create templates for new documentation sections

10. 🧪 Testing and Quality

Content Testing

• Automated link checking
• Code example validation
• Markdown formatting tests
• Search functionality testing

User Testing

• Documentation navigation usability
• Mobile experience testing
• Accessibility audit
• Performance benchmarking

Example Code Implementations

Navigation Component Structure

<!-- DocsNavigation.vue -->
<template>
  <nav class="docs-nav">
    <div class="nav-header">
      <NuxtLink to="/docs" class="nav-title">
        Documentation
      </NuxtLink>
      <DocsSearch />
    </div>
    
    <div class="nav-content">
      <div v-for="section in navigation" :key="section._path" class="nav-section">
        <div class="nav-section-title">
          {{ section.title }}
        </div>
        <ul class="nav-items">
          <li v-for="item in section.children" :key="item._path">
            <NuxtLink 
              :to="item._path"
              :class="{ active: $route.path === item._path }"
              class="nav-item"
            >
              {{ item.title }}
            </NuxtLink>
          </li>
        </ul>
      </div>
    </div>
  </nav>
</template>

Content Page Template

<!-- [...slug].vue -->
<template>
  <DocsLayout>
    <template #sidebar>
      <DocsNavigation />
    </template>
    
    <template #content>
      <article class="prose prose-lg">
        <DocsBreadcrumb :page="page" />
        <ContentRenderer :value="page" />
        <DocsPrevNext :prev="prev" :next="next" />
      </article>
    </template>
    
    <template #toc>
      <DocsToc :links="page.body.toc.links" />
    </template>
  </DocsLayout>
</template>

<script setup>
const { path } = useRoute()
const { data: page } = await useAsyncData(`docs-${path}`, () => 
  queryContent(path).findOne()
)
const [prev, next] = await queryContent()
  .only(['_path', 'title'])
  .findSurround(path)
</script>

Success Criteria

Phase 1 (Foundation) ✅

• Nuxt Content module installed and configured
• Basic content structure created
• Core navigation components implemented
• Essential documentation pages written

Phase 2 (Enhancement) 🚀

• Search functionality implemented
• Interactive components added
• Mobile optimization completed
• SEO optimization implemented

Phase 3 (Polish) ✨

• Advanced features (API playground, examples)
• Accessibility audit completed
• Performance optimization
• User testing and feedback integration

Timeline

• Week 1: Setup, configuration, and basic content structure
• Week 2: Core components and navigation implementation
• Week 3: Content creation and search implementation
• Week 4: Mobile optimization and polish

Notes

• Focus on developer experience and ease of content contribution
• Ensure all examples are tested and up-to-date
• Consider internationalization for future expansion
• Plan for community contributions and content updates

Related Issues

• Documentation should link to existing SDK implementations in /ios and /android folders
• Consider integration with the main NitroPing dashboard for live examples
• Plan for API documentation auto-generation from GraphQL schema

---

Assignee: To be assigned
Labels: documentation, enhancement, nuxt-content, good first issue (for smaller tasks)
Milestone: Documentation v1.0