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.

Site Identity (.dcs/site.yaml)

Site identity, repository linkage, and deployment configuration live in .dcs/site.yaml. See the site.yaml Reference for the full schema. The complete managed file set is exactly the four files in the table above — site.yaml, pages.yaml, content.yaml, and seo.yaml.

Pages Configuration

Page Properties

# .dcs/pages.yaml
version: 3                        # Current schema version
siteSlug: my-site

pages:
  - slug: home                    # URL-safe identifier
    path: /                       # Route path
    type: static                  # Page type (see table below)
    title: Home                   # Display title
    deletable: false              # Can be deleted via portal?

In version 3, textKeys is deprecated: text keys are auto-discovered during snapshot capture, and editable text values come from content.yaml. Repeatable content uses arrayKeys (a base key plus an item schema, e.g. FAQs), and form pages reference their managed form with formId.

Page Types Reference

Type	Use Case
static	User-created pages like /about or /services
index	Collection landing pages like /blog
dynamic	Pages generated from data like /topics/:topic
blog	Blog posts with a WYSIWYG content editor
event	Event detail pages with WYSIWYG content and event metadata
form	Pages rendering a managed form definition (via formId)

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

Environment Variables

The @duffcloudservices/cms package reads these; your generated deployment workflow injects them at build time from the site configuration, so hand-set them only for local development.

# .env — all optional
VITE_API_BASE_URL=https://portal.duffcloudservices.com   # DCS API base URL (this is the default)
VITE_TEXT_OVERRIDE_MODE=commit                           # Text-content override mode (editing/preview)
# VITE_SITE_SLUG is deprecated: the site is resolved server-side from the request host

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

All SEO metadata lives in a single .dcs/seo.yaml: a site block for defaults and a pages map for per-page overrides. It is portal-managed — edits normally flow through the portal SEO tools rather than by hand.

# .dcs/seo.yaml
version: 1
site:
  name: My Site
  defaultTitle: My Site — What we do
  titleTemplate: "%s — My Site"
  description: A short site-wide description used as the default.
  hostname: https://mysite.com
  twitterCard: summary_large_image
  ogImage: /images/og-default.png
pages:
  home:
    title: My Site — What we do
    description: Per-page description for the home page.

See the seo.yaml Reference for the full schema.

Analytics

Site analytics are collected by the platform — there is no site-side analytics configuration or tracking API to add. Visits, trends, and SEO metrics appear in the portal's Analytics views for your site automatically.

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"
    }
  }
}

Troubleshooting Configuration

Validate Configuration

The CLI validates the real .dcs file set (site.yaml, pages.yaml, content.yaml, seo.yaml):

dcs validate            # validate .dcs configuration files in the current directory
dcs validate --fix      # attempt to fix common issues
dcs validate --verbose  # show detailed output

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