Skeleton YAML Quickstart

Define your entire site structure in one YAML file

4 min read 858 words
Edit this page

Was this page helpful?

Define your entire site structure in one YAML file, then scaffold a site from it withbengal new site.

Note

Do I need this? Yes when you need a repeatable site blueprint or custom scaffold beyond built-in templates. For a standard blog or docs site, use Scaffold Your First Site or bengal new site --template docsinstead.

The 30-Second Start

Choose the approach that fits your needs:

  • Built-in templates: Fastest for common site types (blog, docs, portfolio, etc.)
  • Custom skeletons: Full control over structure when templates don't fit your needs

Option 1: Built-in Template

Use a built-in template for common site types:

BASH
bengal new site mydocs --template docs
cd mydocs
bengal serve

Available templates: default, blog, docs, landing, portfolio, product, resume, changelog.

Option 2: Custom Skeleton YAML

Define your own structure when templates don't fit or you need a specific layout. Create a YAML file describing your site structure:

Save it asskeleton.yamlinside a template directory (for example bengal/scaffolds/my-site/skeleton.yaml, or register a custom template at runtime with bengal.scaffolds.register_template):

YAML
name: My Site
description: A simple site with two pages

structure:
  - path: index.md
    props:
      title: Welcome
      description: Home page
    content: |
      # Hello World

      Welcome to my site built with Bengal.

  - path: about.md
    props:
      title: About
      description: About this site
    content: |
      # About

      This site was scaffolded from a skeleton YAML file.

Scaffold a site from it:

BASH
bengal new site mysite --template my-site
cd mysite
bengal serve

Your site is live at http://localhost:5173. The dev server automatically rebuilds when you save changes (hot reload).

Skeleton YAML Structure

Every skeleton has two parts: metadata and structure.

YAML
# Metadata
name: My Documentation Site
description: Technical docs with navigation
version: "1.0"

# Optional: cascade settings applied to all pages
cascade:
  type: doc

# Structure: list of pages and sections
structure:
  - path: _index.md
    props:
      title: Documentation
      weight: 100
    content: |
      # Documentation
      Welcome!

Page Definition

Each page instructurecan have:

Field Required Description
path Yes File path relative tocontent/directory
type No Content type (doc, blog, landing, etc.)
props No Frontmatter fields (title, date, tags, etc.)
content No Markdown content for the page body
cascade No Settings inherited by child pages
pages No Nested pages (makes this a section)

Real-World Examples

Blog Skeleton

YAML
name: Blog
description: Personal blog with posts

structure:
  - path: index.md
    type: blog
    props:
      title: My Blog
      description: Thoughts and ideas
    content: |
      # Welcome to My Blog

      Check out my latest posts below.

  - path: about.md
    props:
      title: About Me
    content: |
      # About Me

      I write about technology and life.

  - path: posts/first-post.md
    type: blog
    props:
      title: My First Post
      date: "2026-01-15"
      tags: [welcome, intro]
    content: |
      # My First Post

      Hello world! This is my first blog post.

Documentation Skeleton

YAML
name: Project Docs
description: Technical documentation
cascade:
  type: doc

structure:
  - path: _index.md
    props:
      title: Documentation
      weight: 100
    content: |
      # Documentation

      Welcome! Start with [Getting Started](getting-started/).

  - path: getting-started/_index.md
    props:
      title: Getting Started
      weight: 10
    pages:
      - path: installation.md
        props:
          title: Installation
          weight: 10
        content: |
          # Installation

          ```bash
          pip install your-package
          ```

      - path: quickstart.md
        props:
          title: Quick Start
          weight: 20
        content: |
          # Quick Start

          Get running in 5 minutes.

  - path: api/_index.md
    props:
      title: API Reference
      weight: 30
    content: |
      # API Reference

      Complete API documentation.

Portfolio Skeleton

YAML
name: Portfolio
description: Developer portfolio

structure:
  - path: index.md
    props:
      title: Portfolio
      layout: home
    content: |
      # Hi, I'm [Your Name]

      I build things for the web.

      [View Projects](/projects) | [About Me](/about)

  - path: projects/_index.md
    props:
      title: Projects
    content: |
      # Projects

      My recent work.

  - path: projects/project-1.md
    props:
      title: E-Commerce Platform
      tags: [react, node]
      featured: true
    content: |
      # E-Commerce Platform

      A full-stack e-commerce solution.

  - path: about.md
    props:
      title: About
    content: |
      # About Me

      Software engineer passionate about great UX.

CLI Commands

Skeletons are materialized bybengal new site, not by a standalone apply command:

Command Description
bengal new site NAME --template TEMPLATE Create a site from a built-in or registered template
bengal new site NAME Launch the interactive wizard and pick a template

Tips

Try It in a Throwaway Directory

Scaffold into a temporary directory first to confirm the structure renders as expected:

BASH
bengal new site /tmp/skeleton-check --template my-site

Start From a Built-in Template

Begin with a built-in template, then edit the scaffolded structure by hand:

BASH
bengal new site mysite --template docs
cd mysite
# Add or edit sections directly under content/

Share Skeletons

Skeleton YAML files are portable. Share them with your team or publish them for others to use.

Next Steps