Content Pipeline Documentation

Overview

The content pipeline processes markdown files from content/ into pre-compiled JSON assets that the Angular app consumes.

Architecture

Pipeline Stages

  1. Discover (discover.ts) - Find all .md files, skip _ prefixed files
  2. Parse (parse.ts) - Extract YAML frontmatter and markdown body
  3. Validate (validate.ts) - Enforce frontmatter schema, fail on errors
  4. Filter (filter.ts) - Environment-aware content filtering
  5. Enrich (enrich.ts) - Add computed metadata (reading time, slugs, series)
  6. Transform (transform.ts) - Convert markdown to HTML with syntax highlighting
  7. Generate (generate.ts) - Write JSON files, RSS, sitemap

Key Features

  • Syntax Highlighting: Shiki with dual themes (light/dark mode)
  • Custom Callouts: :::callout{type="info"} → <div class="jjk-callout" data-type="info">
  • Include Directives: :::include{src="_disclaimer.md"} inlines fragments
  • Series Auto-Detection: Folders with _series.yaml auto-tag posts
  • TOC Generation: Automatic table of contents from headings
  • Environment Filtering:
    • Development: Include all content, tag drafts/scheduled
    • Production: Exclude draft: true and future-dated posts

Usage

Build Commands

# Production build (excludes drafts and future posts)
npm run build:content

# Development build (includes everything)
npm run build:content:dev

# Full build (content + Angular)
npm run build

# Development with watch
npm run dev

Content Structure

content/
├── posts/
│   ├── 2025/
│   │   ├── 01-hello-world.md
│   │   └── 02-draft-post.md
│   └── series-name/
│       ├── _series.yaml              # Series metadata
│       └── 01-first-entry.md
├── pages/
│   └── about.md
└── fragments/
    └── _disclaimer.md                # Reusable snippets

Frontmatter Schema

Required fields:

  • title (string)
  • date (YYYY-MM-DD)
  • tags (string[], posts only)

Optional fields:

  • subtitle, updated, draft, cover, excerpt, toc, layout, readingTime, corporateBsLevel

Computed fields:

  • slug, url, series, seriesOrder, isDraft, isScheduled

Output

Generated files in frontend/src/assets/generated/:

  • posts/<year>/<slug>.json - Individual post content
  • pages/<slug>.json - Individual page content
  • route-manifest.json - All routes with metadata
  • tag-index.json - Posts grouped by tag
  • series-manifest.json - Series configurations and posts
  • rss.xml - RSS 2.0 feed
  • sitemap.xml - XML sitemap

Example Post

---
title: "Hello World"
date: 2025-01-15
tags: ["meta", "getting-started"]
excerpt: "A short description"
---

## Heading

Regular markdown content.

:::callout{type="info"}
This is an info callout.
:::

```typescript
function example() {
  return "syntax highlighted";
}
```

:::include{src="_disclaimer.md"}
:::