Pages & Content - Domma CMS

Overview — URL Mapping

Pages are Markdown files stored in your project's content/pages/ directory. The file path maps directly to the public URL — no configuration required.

File path	Public URL	Notes
`content/pages/about.md`	`/about`	Top-level page
`content/pages/blog/post.md`	`/blog/post`	Nested page
`content/pages/blog/index.md`	`/blog`	Index file — maps to parent slug
`content/pages/index.md`	`/`	Site root / home page

Each page is rendered server-side using the layout configured for that page (or the site default). Pages can override their layout individually via frontmatter.

Deep nesting is supported to any depth. Directory names become URL segments automatically.

Frontmatter Fields

Each Markdown page may open with a YAML frontmatter block delimited by ---. All fields are optional unless otherwise noted.

---
title: My Page Title
description: SEO meta description
layout: default    # default | with-sidebar | minimal | landing
theme: ocean-dark  # Override site theme for this page
draft: false       # true hides page from public
published: true
author: Admin
tags: [blog, news]
image: /media/hero.jpg
---

Field	Type	Description
`title`	string	Page title used in the `<title>` tag and headings. Falls back to site title if omitted.
`description`	string	SEO meta description. Populated into `<meta name="description">` and Open Graph tags.
`layout`	string	Layout template to use for this page. Overrides the site-wide default. Options: `default`, `with-sidebar`, `minimal`, `landing`.
`theme`	string	Override the active Domma theme for this page only (e.g. `ocean-dark`, `forest-light`).
`draft`	boolean	When `true`, the page is hidden from public routes but still accessible and previewable in the admin panel.
`published`	boolean	When `false`, the page is completely excluded from navigation, sitemaps, and public access.
`author`	string	Author name. Displayed in page metadata and used in structured data output.
`tags`	array	List of tags. Used for filtering, related content, and tag archive pages.
`image`	string	Path to a hero or thumbnail image. Used as `og:image` and in layout hero sections.

Markdown Content

All page content below the frontmatter block is written in CommonMark Markdown with several extensions enabled by default.

Supported Syntax

Standard CommonMark (headings, bold, italic, blockquotes, lists)
Tables — GitHub Flavoured Markdown table syntax
Task lists — - [ ] and - [x]
Fenced code blocks with optional language identifier
Syntax highlighting via domma-syntax
Footnotes — [^1] reference style
Definition lists

Images & Links

![alt](src) renders with responsive styling and lazy loading applied automatically
Internal links use relative paths; the CMS resolves them correctly regardless of base URL
External links automatically receive target="_blank" rel="noopener"
Media uploaded via the admin is accessible at /media/filename

---
title: Example Page
---

# Welcome

This is **bold** and this is _italic_.

## A Table

| Name  | Role    |
|-------|---------|
| Alice | Editor  |
| Bob   | Author  |

## Task List

- [x] Write content
- [ ] Review and publish

```js
console.log('Hello from a fenced code block');
```

The frontmatter --- separator is stripped before rendering. Only the body below the second --- is passed to the Markdown parser.

Built-in Shortcodes

Shortcodes extend Markdown with dynamic, reusable components. They are processed server-side before the Markdown parser runs.

Shortcode	Description
`[grid cols="3"]...[/grid]`	Wraps content in a responsive Domma grid. The `cols` attribute sets the column count (1–6). Stacks automatically on mobile.
`[card title="Title"]...[/card]`	Renders a styled Domma `.card` component with an optional header title and body content.
`[hero title="Title" subtitle="Sub"]`	Inserts a full-width hero section. Supports `title`, `subtitle`, `variant`, and `bg` attributes.
`[collection slug="posts" limit="5"]`	Displays a list of Collection entries. Supports `slug`, `limit`, `sort`, and `template` attributes.
`[form slug="contact"]`	Embeds a CMS-managed Form by its slug. The form schema, validation, and submission handling are all configured in the admin.
`[view slug="my-view"]`	Pro Embeds a Pro View component by slug. Useful for interactive widgets and data-driven sections.
`[cta text="Click Here" url="/page"]`	Renders a call-to-action button. Supports `text`, `url`, `variant` (primary/secondary/outline), and `size`.
`[slideover]...[/slideover]`	Wraps content in a Domma Slideover off-canvas panel. A trigger button is automatically generated unless `trigger="false"` is set.
`[effect type="breathe"]...[/effect]`	Wraps content in a Domma Effect animation. Supports all `Domma.effects` types: `breathe`, `pulse`, `reveal`, `scramble`, `counter`, `shake`.
`[celebrate]`	Inserts a trigger that fires a Domma fireworks celebration animation when clicked or when the page loads (use `on="load"`).
`[dconfig key="site.title"]`	Outputs a config value dynamically at render time. Dot-notation keys reference values in `config/site.json` and other config files.

Custom shortcodes can be registered in config/shortcodes.js. Each shortcode receives parsed attributes and inner content as arguments.

Drafts & Visibility

Two frontmatter flags control page visibility independently of one another.

`draft: true`

Page is hidden from all public routes
Still accessible and editable in the admin panel
Admins and Managers can preview the page via the admin preview link
Does not appear in navigation menus or sitemaps
Appears with a Draft badge in the admin pages list

`published: false`

Completely removes the page from public access
Excluded from navigation, sitemaps, and collection queries
Returns a 404 if visited directly
Still visible and editable in the admin panel
Use when archiving or permanently hiding content

State	Public access	Admin preview	Navigation / Sitemap	Admin badge
`draft: false, published: true`	Yes	Yes	Included	—
`draft: true`	No	Yes	Excluded	Draft
`published: false`	No (404)	Yes	Excluded	Unpublished

Per-Page Layouts

The site-wide default layout is set in config/site.json. Individual pages can override this by specifying a layout key in their frontmatter.

Layout	Navbar	Footer	Sidebar	Breadcrumbs	Best for
`default`	Full	Full	None	Yes	General content pages
`with-sidebar`	Full	Full	Left	Yes	Documentation, long-form content
`minimal`	Slim	Minimal	None	No	Login, error, legal pages
`landing`	Transparent	Full	None	No	Marketing, campaign pages

---
title: Contact Us
layout: minimal
---

Custom layouts can be created by adding entries to config/layouts.json. Each layout definition specifies which layout components to include and their configuration.

// config/layouts.json
{
  "my-custom": {
    "navbar": "slim",
    "footer": "columns",
    "sidebar": false,
    "breadcrumbs": true
  }
}

Layout templates are stored in layouts/ at the project root. Each layout is an HTML file that receives the rendered page content as a {{content}} variable.

SEO

The CMS handles common SEO concerns automatically. Frontmatter fields feed directly into the generated <head> tags.

Meta Tags

Tag	Source
`<title>`	Frontmatter `title`, falls back to `config/site.json → title`
`meta[description]`	Frontmatter `description`
`og:title`	Frontmatter `title`
`og:description`	Frontmatter `description`
`og:image`	Frontmatter `image`
`link[canonical]`	Derived from `site.baseUrl` + page slug

Sitemaps & Crawling

Sitemap at /sitemap.xml is auto-generated at startup
Pages with draft: true or published: false are excluded
Sitemap generation can be disabled in config/site.json → seo.sitemap: false
Place a custom robots.txt in public/ — it will be served as-is
If no robots.txt is present, the CMS serves a permissive default
Structured data (JSON-LD) can be added via a schema frontmatter key

---
title: About Us
description: Learn about our team and mission.
image: /media/about-hero.jpg
schema:
  "@type": "AboutPage"
---

Server-Side Rendering

All pages are rendered server-side by the Fastify backend using the built-in Markdown service. There is no client-side routing for page loads.

Render Pipeline

Fastify receives the request
The router maps the URL to a file in content/pages/
Frontmatter is parsed and stripped
Shortcodes are expanded server-side
Template variables are substituted
Markdown is converted to HTML
The result is injected into the selected layout template
The final HTML response is sent and cached

Template Variables

Variable	Value
`{{site.title}}`	Value from `config/site.json → title`
`{{site.baseUrl}}`	Configured base URL
`{{page.title}}`	Current page frontmatter `title`
`{{page.slug}}`	Current page URL slug
`{{year}}`	Current four-digit year

Partials

Reusable content snippets stored in content/partials/ can be embedded into any page using the block shortcode:

[block slug="cta-banner"]

Partials are rendered as Markdown and support the same shortcodes and template variables as full pages.

Caching

Setting	Default	Description
`cache.enabled`	`true`	Toggle in-memory render cache on or off
`cache.ttl`	`300`	Time-to-live in seconds before a cached render is invalidated
`cache.invalidateOnSave`	`true`	Automatically clears the cache entry for a page when it is saved in the admin

Development mode disables caching and enables hot reload — pages re-render on every request so edits are visible immediately without restarting the server.

// config/site.json
{
  "env": "development",
  "cache": {
    "enabled": false
  }
}