Quick Start: Build a Page

This walkthrough uses the default file driver and theme. You can copy/paste commands from any Unix shell; Windows users can replace ./velvet with php velvet.

1. Create a page #

./velvet page:make docs --title="Documentation Home"

PageService creates content/pages/docs.md with starter Markdown. Edit the file:

---
title: Documentation Home
status: published
layout: default
excerpt: "What you can build with VelvetCMS"
---

# Welcome to the docs

VelvetCMS ships with modular routing, theming, and CLI tooling.

Frontmatter keys map directly to VelvetCMS\Models\Page fields. Anything extra is stored in meta and exposed in templates via $page->meta.

2. Route + render #

The default route in routes/web.php matches /{slug}. Visit http://localhost:8000/docs. PageService loads the Markdown, MarkdownService parses it (with CommonMark + task list extension), and ThemeService renders it with themes/default/layouts/default.velvet.php.

3. Customize the theme #

1. Open themes/default/layouts/default.velvet.php.
2. Inject page metadata:

<title>{{ $page->title }} · {{ $site['name'] }}</title>
<meta name="description" content="{{ $page->getExcerpt() }}">

3. Use helper closures injected by ThemeService:

<link rel="stylesheet" href="{{ $asset('css/app.css') }}">
<nav>
  <a href="{{ $url('/') }}">Home</a>
</nav>

Assets under themes/default/assets are served via the /themes/{theme}/assets/{asset*} route. The router sanitizes paths and sets Cache-Control, ETag, and Last-Modified headers automatically.

4. Publish #

./velvet page:publish docs

The command flips the page status, stamps published_at, flushes caches via CacheTagManager, and you’re live. Draft pages remain inaccessible unless APP_DEBUG=true.

5. Add a module #

Drop the Docs module next to the core repo (../VelvetCMS-Docs) and then follow Module Basics for module:enable, module:compile, and boot guidance so we don’t repeat those steps twice.

6. Cache routes & config (optional) #

./velvet route:cache
./velvet config:cache

route:cache stores compiled regex definitions in storage/cache/routes.php. config:cache exports every config file into storage/cache/config.php and makes bootstrap even faster.

You now understand the full page lifecycle: Markdown → PageService → ThemeService → Router → Response. The rest of this documentation dives deeper into each subsystem.