DCS Configuration Reference

Complete reference for the .dcs/config.yaml configuration file.

Overview

The .dcs/config.yaml file is the main configuration file for DCS-integrated sites. It defines site identity, features, and integration settings.

Schema

# .dcs/config.yaml
version: 1

site:
  name: string           # Required: Site display name
  slug: string           # Required: Unique URL-safe identifier
  description: string    # Optional: Site description
  url: string            # Optional: Production URL
  
framework:
  type: string          # Required: vitepress | vue | nuxt | react | nextjs
  version: string       # Optional: Framework version
  
content:
  textOverrides: boolean    # Enable text content API
  seoManagement: boolean    # Enable SEO management
  blogEnabled: boolean      # Enable blog features
  
development:
  copilotEnabled: boolean   # Enable GitHub Copilot automation
  autoMerge: boolean        # Auto-merge approved dev requests
  
deployment:
  provider: string          # azure-swa | vercel | netlify
  environments:
    development: object
    production: object
    
integrations:
  analytics: object
  forms: object
  search: object

Properties

site

Site identification and metadata.

Property	Type	Required	Default	Description
name	string	Yes	—	Display name shown in portal
slug	string	Yes	—	Unique identifier (lowercase, hyphens)
description	string	No	—	Brief site description
url	string	No	—	Production URL
logo	string	No	—	Path to logo image

Example:

site:
  name: Acme Corporation
  slug: acme-corp
  description: Corporate website for Acme Corp
  url: https://www.acmecorp.com
  logo: /images/logo.svg

framework

Framework detection and configuration.

Property	Type	Required	Default	Description
type	string	Yes	—	Framework type
version	string	No	—	Framework version
buildCommand	string	No	pnpm build	Build command
outputDir	string	No	dist	Build output directory

Supported Framework Types:

Type	Build Output	Notes
vitepress	.vitepress/dist	Markdown-based docs/blogs
vue	dist	Vue SPA applications
nuxt	.output	Nuxt 3 applications
react	build	React applications
nextjs	.next	Next.js applications

Example:

framework:
  type: vitepress
  version: "1.4.0"
  buildCommand: pnpm run docs:build
  outputDir: docs/.vitepress/dist

content

Content management features.

Property	Type	Required	Default	Description
textOverrides	boolean	No	true	Enable text content API
seoManagement	boolean	No	true	Enable SEO management
blogEnabled	boolean	No	false	Enable blog features
blogPath	string	No	/blogs	Blog URL path
pagesPath	string	No	.dcs/pages.yaml	Pages config location

Example:

content:
  textOverrides: true
  seoManagement: true
  blogEnabled: true
  blogPath: /blog
  pagesPath: .dcs/pages.yaml

development

Development workflow configuration.

Property	Type	Required	Default	Description
copilotEnabled	boolean	No	true	Enable Copilot automation
autoMerge	boolean	No	false	Auto-merge approved requests
reviewRequired	boolean	No	true	Require PR review
branchPrefix	string	No	copilot/	Branch prefix for dev requests
releasePrefix	string	No	release/	Branch prefix for releases

Example:

development:
  copilotEnabled: true
  autoMerge: false
  reviewRequired: true
  branchPrefix: copilot/
  releasePrefix: release/

deployment

Deployment configuration.

Property	Type	Required	Default	Description
provider	string	No	azure-swa	Deployment provider
environments	object	No	—	Environment configurations

Provider Options:

Provider	Value	Notes
Azure Static Web Apps	azure-swa	Default, recommended
Vercel	vercel	Vercel deployments
Netlify	netlify	Netlify deployments
Custom	custom	Self-managed

Example:

deployment:
  provider: azure-swa
  environments:
    development:
      url: https://dev.acmecorp.com
      autoDeployBranch: release/*
    production:
      url: https://www.acmecorp.com
      autoDeployBranch: main
      requireApproval: true

integrations

Third-party integrations.

analytics

integrations:
  analytics:
    provider: google    # google | plausible | fathom
    trackingId: G-XXXXXXXXXX
    respectDNT: true

forms

integrations:
  forms:
    provider: formspree    # formspree | netlify | custom
    endpoint: https://formspree.io/f/xxxxx

search

integrations:
  search:
    provider: algolia      # algolia | meilisearch | pagefind
    appId: XXXXXXXXXX
    indexName: acme-docs

Complete Example

# .dcs/config.yaml
version: 1

site:
  name: Acme Corporation
  slug: acme-corp
  description: Corporate website and documentation
  url: https://www.acmecorp.com
  logo: /images/logo.svg

framework:
  type: vitepress
  version: "1.4.0"
  buildCommand: pnpm build
  outputDir: .vitepress/dist

content:
  textOverrides: true
  seoManagement: true
  blogEnabled: true
  blogPath: /blog
  pagesPath: .dcs/pages.yaml

development:
  copilotEnabled: true
  autoMerge: false
  reviewRequired: true
  branchPrefix: copilot/
  releasePrefix: release/

deployment:
  provider: azure-swa
  environments:
    development:
      url: https://dev.acmecorp.com
      autoDeployBranch: release/*
    production:
      url: https://www.acmecorp.com
      autoDeployBranch: main
      requireApproval: true

integrations:
  analytics:
    provider: google
    trackingId: G-XXXXXXXXXX
    respectDNT: true
    
  forms:
    provider: formspree
    endpoint: https://formspree.io/f/xxxxx
    
  search:
    provider: pagefind

Minimal Example

version: 1

site:
  name: My Site
  slug: my-site

framework:
  type: vitepress

Environment Variables

Some values can be overridden via environment:

Config Path	Environment Variable
site.url	SITE_URL
integrations.analytics.trackingId	ANALYTICS_ID
deployment.environments.*.url	DEPLOY_URL

Validation

CLI Validation

dcs config validate

Validation Rules

Rule	Description
version required	Must be present and valid
site.name required	Non-empty string
site.slug format	Lowercase, alphanumeric, hyphens only
framework.type valid	Must be supported type

Error Messages

Error: Invalid config
  - site.slug: Must be lowercase with hyphens only
  - framework.type: 'gatsby' is not a supported framework

Migration

From v0 to v1

# Old format (v0)
name: My Site
type: vitepress

# New format (v1)
version: 1
site:
  name: My Site
  slug: my-site
framework:
  type: vitepress

Best Practices

1. Use Descriptive Names

site:
  name: Acme Corp Marketing Site  # Clear purpose
  slug: acme-marketing            # Short, unique

2. Environment-Specific URLs

deployment:
  environments:
    development:
      url: https://dev.example.com
    staging:
      url: https://staging.example.com
    production:
      url: https://example.com

3. Explicit Feature Flags

content:
  textOverrides: true    # Be explicit
  seoManagement: true
  blogEnabled: false     # Clearly disabled

Troubleshooting

Config Not Found

Error: .dcs/config.yaml not found

Solution: Create the file in your repository root.

Invalid YAML

Error: Invalid YAML syntax at line 15

Solution: Check for proper indentation and syntax.

Unknown Framework

Error: framework.type 'hugo' is not supported

Solution: Use a supported framework type or custom.

Next Steps

• Pages Configuration — Page definitions
• Site Setup — Full integration guide
• VitePress Integration — VitePress specifics