Content Directory Structure

Overview

Full directory layout

priv/content/
├── site.yml
├── authors/
│   └── {slug}.yml
├── tags/
│   └── {slug}.yml
├── media/
│   ├── {slug}.yml
│   └── files/
│       └── {path}
├── templates/
│   └── sections/
│       └── {template_name}.yml
├── layouts/
│   └── {layout_name}.yml
├── shared_sections/
│   └── {name}.yml
├── collections/
│   └── {slug}.yml
└── pages/
    └── {slug}/
        ├── page.yml
        └── versions/
            └── {YYYYMMDDTHHMMSSz}/
                ├── version.yml
                └── sections/
                    ├── 01-{name}.yml
                    ├── 02-{name}.md
                    └── 03-{name}.{field}.md

Naming conventions

site.yml and global resources

site.yml

name: My Site
tagline: A brief tagline
meta_title: SEO title
meta_description: SEO description
domain: example.com
og_image: og-default
favicon: favicon

authors/{slug}.yml

name: Maya Johnson
bio: Author biography text
avatar: maya-avatar
url: https://example.com
# extra: (any additional fields)

tags/{slug}.yml

display_name: Coffee

media/{slug}.yml

path: files/hero.jpg
alt: Descriptive alt text
caption: Optional caption
content_type: image/jpeg
# extra: (any additional fields)

Media files live in media/files/ alongside the YAML metadata.

Layout definitions

Inline sections

# layouts/default.yml
header_sections:
  - template: nav
    fields:
      links:
        - label: Home
          url: /
        - label: Blog
          url: /blog
footer_sections:
  - template: footer
    fields:
      copyright: "2025 My Site"

Shared section references

# layouts/default.yml
header_sections:
  - shared_section: main-nav
footer_sections:
  - shared_section: site-footer

Shared section refs are resolved at load time — the final Layout struct contains full Section structs.

Reusable content blocks and page groupings

shared_sections/{name}.yml

# shared_sections/main-nav.yml
template: nav
fields:
  links:
    - label: Home
      url: /
    - label: Blog
      url: /blog

Referenced in layouts via shared_section: main-nav.

collections/{slug}.yml

# collections/blog.yml
name: Blog
filters:
  prefix: /blog/
  tag: coffee
  author: maya
sort_by: published_at    # slug | title | published_at | updated_at
sort_direction: desc     # asc (default) | desc

# SEO (optional, used by Brix.Meta.field/3)
meta_title: Blog Posts
meta_description: All blog posts
og_title: Blog
og_description: Read our blog
og_image: blog-og

Field type definitions

templates/sections/{name}.yml

# templates/sections/hero.yml
fields:
  heading:
    type: string
    required: true
  subheading:
    type: string
  body:
    type: richtext
  image:
    type: media
  link_url:
    type: url
  visible:
    type: boolean
  count:
    type: integer
  items:
    type: list
    of: map
  metadata:
    type: map

Supported field types

Page directory layout with versions

page.yml

# pages/blog/hello/page.yml
title: Hello World
layout: default
authors:
  - maya
tags:
  - coffee
  - travel
published_version: "20240315T090000Z"

# SEO (optional)
meta_title: Hello World - Blog
meta_description: A post about coffee
og_title: Hello World
og_description: A post about coffee
og_image: hello-og

# Old URLs that redirect here
slug_history:
  - /old-hello
  - /posts/hello

version.yml

# pages/blog/hello/versions/20240315T090000Z/version.yml
published_at: "2024-03-15T09:00:00Z"
updated_at: "2024-03-15T09:00:00Z"

Slug derivation

Publishing states

Three file formats for sections

YAML section

# sections/01-hero.yml
template: hero
fields:
  heading: Welcome
  subheading: To my site
  image: hero-image

Position extracted from filename prefix (01- -> position 1).

Standalone markdown

# sections/02-intro.md
---
template: richtext
---

This is the body with **bold** and *italic*.

Template from frontmatter or filename. The entire markdown body becomes the section's content field.

Mixed: YAML + markdown field

# sections/03-cta.yml
template: cta
fields:
  heading: Call to Action
  button_text: Learn More

# sections/03-cta.body.md

Rich **markdown** content for the `body` field.

The .body.md file merges into the body key of the YAML section's fields. The source_fields map preserves the raw markdown before HTML conversion.