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

Install the YAML extension by Red Hat
Add to your workspace .vscode/settings.json:

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

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

yaml

# .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

yaml

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

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.

bash

# .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

yaml

# 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:

vue

<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.

yaml

# .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

yaml

# 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):

bash

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

Site Configuration for Partners ​

Configuration Files ​

Editor Schema Support ​

VS Code Setup ​

JetBrains IDEs ​

Other Editors ​

Site Identity (.dcs/site.yaml) ​

Pages Configuration ​

Page Properties ​

Page Types Reference ​

Example: Blog Site ​

Environment Variables ​

Environment Variables ​

Text Key Conventions ​

Naming Pattern ​

Recommended Structure ​

Key Naming Best Practices ​

Component Development ​

Creating Custom Components ​

Component Organization ​

SEO Configuration ​

Analytics ​

Deployment Configuration ​

Azure Static Web Apps ​

Troubleshooting Configuration ​

Validate Configuration ​

Common Issues ​

Next Steps ​

Site Configuration for Partners

Configuration Files

Editor Schema Support

VS Code Setup

JetBrains IDEs

Other Editors

Site Identity (`.dcs/site.yaml`)

Pages Configuration

Page Properties

Page Types Reference

Example: Blog Site

Environment Variables

Environment Variables

Text Key Conventions

Naming Pattern

Recommended Structure

Key Naming Best Practices

Component Development

Creating Custom Components

Component Organization

SEO Configuration

Analytics

Deployment Configuration

Azure Static Web Apps

Troubleshooting Configuration

Validate Configuration

Common Issues

Next Steps