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/site.yaml	Site identity and Azure config
.dcs/pages.yaml	Page registry
.dcs/content.yaml	Text content (portal-managed)
.dcs/seo.yaml	SEO metadata (portal-managed)
.env	Environment variables
.github/copilot-instructions.md	AI development guidelines

Editor Schema Support

DCS provides JSON schemas for all configuration files, enabling autocompletion and validation in your editor.

VS Code Setup

1. Install the YAML extension by Red Hat

2. Add to your workspace .vscode/settings.json:

{
  "yaml.schemas": {
    "https://schema.duffcloudservices.com/1.0.0/site.json": "/.dcs/site.yaml",
    "https://schema.duffcloudservices.com/1.0.0/pages.json": "/.dcs/pages.yaml",
    "https://schema.duffcloudservices.com/1.0.0/content.json": "/.dcs/content.yaml",
    "https://schema.duffcloudservices.com/1.0.0/seo.json": "/.dcs/seo.yaml"
  }
}

3. Restart VS Code or reload the window

Once configured, you'll get:

• Autocompletion for all properties
• Validation against the schema
• Hover documentation for each field
• Error highlighting for invalid values

JetBrains IDEs

Add to your project's .idea/yamlSchemas.xml or configure via Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings.

Other Editors

Any editor supporting JSON Schema for YAML can use these URLs directly. The schemas follow JSON Schema Draft-07.

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

Component Development

Creating Custom Components

Components are Vue single-file components with text content integration:

<script setup lang="ts">
import { useTextContent } from '@/lib/use-text-content'

const { t } = useTextContent({
  pageSlug: 'home',
  defaults: {
    'hero.title': 'Welcome',
    'hero.subtitle': 'Your solution for...'
  }
})
</script>

<template>
  <section class="hero">
    <h1>{{ t('hero.title') }}</h1>
    <p>{{ t('hero.subtitle') }}</p>
  </section>
</template>

Component Organization

Place components in src/components/ with clear naming:

src/components/
├── HeroSection.vue
├── TestimonialGrid.vue
├── ContactForm.vue
└── layouts/
    └── DefaultLayout.vue

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
• site.yaml Reference — Site identity configuration
• pages.yaml Reference — Page definitions
• content.yaml Reference — Text content schema
• seo.yaml Reference — SEO configuration schema
• Deployment Guide — Deployment workflows