Site Configuration for Partners

Partner Documentation

This guide covers advanced configuration options for sites integrated with DCS.

Configuration Files

DCS sites use several configuration files:

File	Purpose
.dcs/config.yaml	Main DCS configuration
.dcs/pages.yaml	Page registry
.env	Environment variables
.github/copilot-instructions.md	AI development guidelines

DCS Config File

Full Schema

# .dcs/config.yaml

site:
  # Required: Unique identifier for the site
  slug: my-site
  
  # Required: Display name
  name: My Site
  
  # Optional: Site description
  description: A website managed by DCS
  
  # Optional: Default language
  language: en-US

api:
  # Required: DCS API endpoint
  endpoint: https://portal.duffcloudservices.com/api
  
  # Optional: Request timeout in milliseconds
  timeout: 5000
  
  # Optional: Enable caching
  cache: true
  cacheTTL: 300  # seconds

features:
  # Enable text override functionality
  textOverrides: true
  
  # Enable SEO metadata management
  seoMetadata: true
  
  # Enable blog CMS
  blog: true
  
  # Enable analytics tracking
  analytics: true
  
  # Enable development requests
  devRequests: true

deployment:
  # Azure Static Web App configuration
  provider: azure-swa
  
  # Build output directory
  outputDir: .vitepress/dist
  
  # Build command
  buildCommand: pnpm build

github:
  # Repository owner/name
  repo: owner/my-site
  
  # Default branch
  defaultBranch: main
  
  # Release branch pattern
  releaseBranchPattern: release/{version}

Pages Configuration

Page Properties

# .dcs/pages.yaml

pages:
  - slug: home                    # URL-safe identifier
    path: /                       # Route path
    type: static                  # Page type
    title: Home                   # Display title
    deletable: false              # Can be deleted via portal?
    textKeys:                     # Text keys (auto-discovered)
      - home.hero.title
      - home.hero.subtitle
    meta:                         # Optional metadata
      template: landing
      priority: high

Page Types Reference

Type	Auto-Generated	Deletable	Use Case
static	No	Configurable	Standard pages
index	No	No	Collection landing pages
dynamic	Yes	No	Generated from data

Example: Blog Site

pages:
  # Main pages
  - slug: home
    path: /
    type: static
    title: Home
    deletable: false

  # Blog section
  - slug: blogs
    path: /blog
    type: index
    title: Blog
    deletable: false

  # Dynamic blog posts
  - slug: blog-post
    path: /blog/:slug
    type: dynamic
    title: Blog Post
    deletable: false

  # Topic pages
  - slug: topics
    path: /topics/:topic
    type: dynamic
    title: Topics
    deletable: false

Environment Variables

Required Variables

# .env

# DCS API Configuration
VITE_DCS_API=https://portal.duffcloudservices.com/api
VITE_SITE_ID=your-site-id

# Optional: Enable debug mode
VITE_DCS_DEBUG=false

Environment-Specific Config

# .env.development
VITE_DCS_API=https://dev.portal.duffcloudservices.com/api
VITE_DCS_DEBUG=true

# .env.production
VITE_DCS_API=https://portal.duffcloudservices.com/api
VITE_DCS_DEBUG=false

Text Key Conventions

Naming Pattern

{page}.{section}.{element}

Recommended Structure

# Page-level keys
home.meta.title          # SEO title
home.meta.description    # SEO description

# Section keys
home.hero.title
home.hero.subtitle
home.hero.cta

home.features.title
home.features.item1.title
home.features.item1.description

# Shared/global keys
global.footer.copyright
global.nav.contact
global.cta.learnMore

Key Naming Best Practices

✅ Do:

• Use lowercase with dots
• Be descriptive but concise
• Group related keys
• Use consistent terminology

❌ Don't:

• Use camelCase or snake_case
• Include version numbers
• Use generic names like text1
• Duplicate keys across pages

Widget Configuration

Widget Types

DCS supports configurable widgets that site owners can modify:

# In component frontmatter or config
widgets:
  - id: hero-carousel
    type: carousel
    config:
      autoplay: true
      interval: 5000
      slides:
        - image: /images/slide1.jpg
          title: Welcome
        - image: /images/slide2.jpg
          title: About Us

  - id: testimonials
    type: testimonial-grid
    config:
      columns: 3
      showRating: true

Widget Schema

interface WidgetConfig {
  id: string           // Unique widget identifier
  type: string         // Widget type name
  config: Record<string, unknown>  // Widget-specific config
}

SEO Configuration

Per-Page SEO

# .dcs/seo/home.yaml
title: "Home | My Site"
description: "Welcome to My Site - your solution for..."
ogImage: /images/og-home.jpg
robots: index, follow
canonical: https://mysite.com/

Global SEO Defaults

# .dcs/seo/defaults.yaml
siteName: My Site
titleTemplate: "{title} | My Site"
defaultOgImage: /images/og-default.jpg
twitterHandle: "@mysite"

Analytics Configuration

Enable Analytics

# .dcs/config.yaml
features:
  analytics: true

analytics:
  provider: dcs
  trackPageViews: true
  trackEvents: true
  anonymizeIp: true

Custom Events

// In your Vue components
import { useAnalytics } from '@dcs/client'

const { trackEvent } = useAnalytics()

// Track custom events
trackEvent('button_click', {
  button: 'cta-hero',
  page: 'home'
})

Deployment Configuration

Azure Static Web Apps

# staticwebapp.config.json
{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/images/*", "/api/*"]
  },
  "routes": [
    {
      "route": "/api/*",
      "allowedRoles": ["authenticated"]
    }
  ],
  "responseOverrides": {
    "404": {
      "rewrite": "/404.html"
    }
  }
}

Build Configuration

# .dcs/config.yaml
deployment:
  buildCommand: pnpm build
  outputDir: .vitepress/dist
  nodeVersion: 22
  
  # Environment variables for build
  buildEnv:
    VITE_DCS_API: https://portal.duffcloudservices.com/api

Troubleshooting Configuration

Validate Configuration

# Run DCS config validation
pnpm dcs validate

# Output
✓ .dcs/config.yaml is valid
✓ .dcs/pages.yaml is valid
✓ Environment variables configured
⚠ Missing optional: analytics configuration

Common Issues

Issue	Cause	Solution
Text not updating	Cache enabled	Clear cache or reduce TTL
Pages not found	Missing pages.yaml entry	Add page to registry
SEO not applied	Wrong path format	Use exact route path
Build failing	Missing env vars	Check .env configuration

Next Steps

• Text Content API — API reference
• Pages.yaml Reference — Full schema documentation
• Deployment Guide — Deployment workflows