Docs LATEST

Markdown & Frontmatter

Writing content with YAML frontmatter and Markdown.

Content & Data

VelvetCMS uses Markdown files with YAML frontmatter for content storage. This format is human-readable, version-control friendly, and easy to migrate.

File Format #

Content files combine YAML frontmatter with Markdown body:

---
title: Welcome to VelvetCMS
description: A modern content management framework.
status: published
layout: default
author: Admin
created_at: 2026-01-15
---

Welcome to **VelvetCMS**, a modular content framework built for PHP 8.4+.

## Features

- Fast and lightweight
- Flexible content drivers
- Modern PHP architecture

Frontmatter Fields #

Reserved Fields #

These fields have special meaning:

Field Type Description
title string Page title (used in <title> and headings)
description string Meta description for SEO
status string draft or published
layout string Template layout name
slug string URL slug (derived from filename if not set)
created_at date Creation date (YYYY-MM-DD)
updated_at date Last modification date
order integer Sort order for listings

Custom Fields #

Add any custom fields you need:

---
title: Product Page
category: electronics
price: 299.99
featured: true
tags:
  - gadgets
  - technology
seo:
  keywords: "tech, gadgets, electronics"
  canonical: /products/widget
---

Custom fields are passed to templates as-is.

Markdown Engines #

Configure your preferred Markdown parser in config/content.php:

'parser' => [
    'driver' => 'commonmark',  // or 'parsedown', 'html'
],
Engine Description
commonmark Full CommonMark spec, extensible (default)
parsedown Fast, minimal dependencies
html No parsing-content is raw HTML

Template Tags #

Template syntax is preserved through Markdown parsing:

---
title: Dynamic Page
---

Hello, {{ $user->name }}!

Your dashboard:

{!! $dashboardWidget !!}

Tags are protected during parsing and evaluated when the template renders.

Supported Syntax #

  • {{ $variable }} - escaped output
  • {!! $variable !!} - raw output
  • @include('partial') - include directive
  • @if/@foreach - control structures

Markdown Features #

Standard Markdown syntax is supported:

Text Formatting #

**bold** or __bold__
*italic* or _italic_
~~strikethrough~~
`inline code`

[Link text](https://example.com)
[Link with title](https://example.com "Title")
![Alt text](/images/photo.jpg)

Code Blocks #

```php
$greeting = "Hello, World!";
echo $greeting;
```

Tables #

| Name | Role |
|------|------|
| Alice | Admin |
| Bob | Editor |

Task Lists #

- [x] Completed task
- [ ] Pending task

Caching #

Parsed Markdown is cached by default. Configure the TTL:

// config/content.php
'parser' => [
    'driver' => 'commonmark',
    'cache_ttl' => 600,  // seconds, 0 to disable
],

Cache is invalidated automatically when content is saved through PageService.

File Organization #

Organize content in directories:

content/
├── pages/
│   ├── index.md
│   ├── about.md
│   └── contact.md
├── blog/
│   ├── 2026-01-15-welcome.md
│   └── 2026-01-20-update.md
└── docs/
    ├── getting-started.md
    └── api-reference.md

The directory structure maps to URL slugs: blog/2026-01-15-welcome becomes /blog/2026-01-15-welcome.

← Previous Content Drivers Next → Velvet Blocks (.vlt)