Content Repo Spec

cascadeguard-app-content: Content Repository Specification

This document defines the structure, frontmatter schema, and conventions for the cascadeguard/cascadeguard-app-content private content repository. It is the source of truth for engineering when building the MDX rendering pipeline.

See CAS-311 for the engineering implementation task.

---

Repository Structure

cascadeguard-app-content/
├── articles/               # Blog posts and long-form content
│   ├── 001-*.md
│   └── ...
├── pages/                  # Static website pages (home, about, docs landing)
│   ├── home.md
│   └── ...
├── assets/                 # Images and static assets referenced by content
│   └── ...
├── package.json            # Optional: workspace metadata / TypeScript types
└── README.md

---

Article Frontmatter Schema

Every file in articles/ must include this YAML frontmatter block at the top:

---
title: string                    # Full article title (used in <title> and og:title)
description: string              # SEO meta description (155 chars max)
pubDate: YYYY-MM-DD              # Publication date (ISO 8601)
author: string                   # Author display name
category: string                 # Primary category slug (see categories below)
series: string | null            # Series slug, or null if standalone
seriesOrder: number | null       # 1-indexed position in series, or null
tags: string[]                   # Array of tag slugs
slug: string                     # URL slug — must be unique across all articles
featured: boolean                # true = show on homepage featured section
---

Categories

Slug	Display Name
supply-chain-security	Supply Chain Security
kubernetes-security	Kubernetes Security
devsecops	DevSecOps
open-source	Open Source
product	Product

Series

Slug	Display Name
container-security-state-of-the-union	Container Security: State of the Union

---

Current Article Inventory

File	Slug	Series	Order	Featured
001-why-your-dockerfile-is-a-supply-chain-risk.md	why-your-dockerfile-is-a-supply-chain-risk	—	—	✅
002-state-of-base-os-images.md	container-security-state-of-the-union-base-os-images	State of the Union	1	—
003-state-of-database-images.md	container-security-state-of-the-union-database-images	State of the Union	2	—
004-state-of-web-server-proxy-images.md	container-security-state-of-the-union-web-server-proxy-images	State of the Union	3	—
005-state-of-language-runtime-images.md	container-security-state-of-the-union-language-runtime-images	State of the Union	4	—
006-state-of-observability-images.md	container-security-state-of-the-union-observability-images	State of the Union	5	—
007-state-of-service-mesh-images.md	container-security-state-of-the-union-service-mesh-images	State of the Union	6	—
008-state-of-cicd-images.md	container-security-state-of-the-union-cicd-images	State of the Union	7	—

---

Planned Articles (Future Pipeline)

These are planned but not yet written. Engineering should design the pipeline to support them:

• Closing the container security loop with ArgoCD and Kargo (mid-funnel positioning)
• SBOMs explained: what they are, why they matter, how to generate them (SEO + email capture)
• Chainguard, Docker Scout, and the gap nobody talks about (mid-funnel comparison)
• SLSA Level 2/3 in practice with CascadeGuard (late-funnel technical)
• How we maintain zero-CVE base images, publicly (trust + lead gen, requires live dashboard)

---

URL Conventions

Articles should be served at:

/blog/{slug}

Series index page:

/blog/series/{series-slug}

Category pages:

/blog/category/{category-slug}

---

MDX Rendering Requirements

The app’s MDX pipeline (in packages/web) should support:

1. Frontmatter parsing — read the YAML block at the top of each file
2. Code blocks — syntax highlighting (Prism or Shiki)
3. Images — resolve relative assets/ paths to the built asset URL
4. Series navigation — auto-generate previous/next links within a series using seriesOrder
5. Tag/category pages — build-time generation of index pages grouped by tag/category
6. RSS feed — auto-generated from all published articles (sorted by pubDate desc)
7. OG meta tags — title, description, and a generated OG image per article

---

Content Repo → App Repo Integration

Per CTO recommendation (see CAS-133):

• cascadeguard-app-content is a private repo under the cascadeguard GitHub org
• It is added as a git submodule at packages/content in cascadeguard-app
• CI uses a deploy key (read-only) to check out the submodule
• The CMO (or content contributors) push to cascadeguard-app-content directly
• The cascadeguard-app CI is triggered by cascadeguard-app-content pushes via a webhook or scheduled rebuild

---

Last updated: 2026-04-07 by Elena Vasquez (CMO)