Cecil
A simple and powerful content-driven static site generator.
Cecilapp · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Cecilapp/CecilAbout this skill
name: cecil description: Build and configure Cecil static sites, with focused guidance for content, templates, and site generation. license: EUPL-1.2
Cecil Site Builder
You are an expert Cecil developer capable of creating and generating static websites with Cecil, a PHP-based static site generator powered by Symfony components and Twig.
When to Use This Skill
Use this skill when:
- Creating or scaffolding a new Cecil site
- Building and generating static websites with Cecil
- Configuring site settings, taxonomies, and content organization
- Creating or updating Twig templates and layouts
- Managing assets, including images and stylesheets
- Deploying Cecil-generated static sites
- Troubleshooting build issues or optimizing the performance of the generated site and build process
- Working with Cecil's plugin/extension system
Project Structure
Directory Layout
my-site/
├── cecil.yml # Main configuration file (or config.yml)
├── pages/ # Markdown pages
├── layouts/ # Twig templates
├── assets/ # Processed files (CSS, JS, images)
├── static/ # Static files copied as-is
└── data/ # Data collections (YAML/JSON/...)
Key Directories
- pages/ - Markdown content files organized into sections
- layouts/ - Twig templates and partials
- assets/ - Files handled by Cecil (Sass compilation, minification, image handling)
- static/ - Files copied to output without transformation
- data/ - Data files exposed in templates via
site.data
Cecil Fundamentals
Architecture
Cecil follows a build pipeline:
Builder → Steps → Generators → Renderer → Output
-
Steps (
Step/): Sequential build phases- Pages: Parse markdown content
- Data: Load data files
- Assets: Process assets
- Taxonomies: Generate taxonomy pages
- Menus: Build navigation structures
- Optimize: Optimize output
- StaticFiles: Copy static files
-
Generators (
Generator/): Page generators executed via priority queue- Generators are ordered by numeric weight; lower numbers execute first (e.g., DefaultPages at weight 10 runs before Alias at weight 80).
- DefaultPages (10) → VirtualPages (20) → ExternalBody (30) → Section (40) → Taxonomy (50) → Homepage (60) → Pagination (70) → Alias (80) → Redirect (90)
-
Renderer (
Renderer/): Twig-based rendering with custom extensions -
Output: Built static site in
_site/directory
Content Model
- Pages: Markdown files composed of front matter and body
- Front matter: Metadata surrounded by separators (
---,+++, or<!-- -->) - Section: Root folder in
pages/(e.g.pages/blog/post-1.md-> sectionblog) - File-based routing: Files under
pages/define generated paths - Collections: Pages, taxonomies, data and static files are exposed to templates
Nested Sections (Sub-sections)
A nested folder that explicitly contains an index.md file becomes a sub-section of its parent Section. A nested folder without an index.md file is not a sub-section: its pages simply belong to the parent section.
pages/
└─ blog # Section "blog"
├─ index.md
├─ post-1.md # Page in "blog"
└─ 2024 # Sub-section (contains an "index.md")
├─ index.md
└─ post-2.md # Page in "blog" AND "blog/2024"
A sub-section:
- Is a full Section (same
type, variables, and layout resolution) available at its own URL (e.g./blog/2024/) - Can be nested at any depth (e.g.
blog/2024/06/) - Lists its own pages; those pages also belong to each parent section
- Is not listed among the pages of its parent section
Sub-sections support the same front matter variables as any section (sortby, pagination, cascade, circular). Use cascade on a parent index.md to propagate variables down to sub-sections and their pages.
Configuration
Configuration is defined in cecil.yml or config.yml at project root:
- Core options are top-level keys such as
title,baseurl,description,taxonomies,menus - Dot notation in templates applies to
sitevariable access (for examplesite.title) - Defaults are defined in
config/default.phpand base pipeline inconfig/base.php
Building a Cecil Site
Step 1: Download Cecil
Download Cecil using curl:
curl -LO https://cecil.app/cecil.phar
chmod +x cecil.phar
Step 2: Create a New Site
Use the new:site command to scaffold a new website:
php cecil.phar new:site
Step 3: Configure the Site
Edit cecil.yml:
title: My Site
baseurl: https://example.com/
description: My awesome static site
taxonomies:
categories: category
tags: tag
Step 4: Create Content
Create a page with:
php cecil.phar new:page
Then edit the generated file in pages/:
---
title: My First Post
description: Welcome to my blog
date: 2024-05-14
tags: [Welcome, "First post"]
---
# My First Post
This is my first post content.
Step 5: Create Templates
Create Twig templates in layouts/ (for example layouts/page.html.twig):
<!DOCTYPE html>
<html>
<head>
<title>{{ page.title }} - {{ site.title }}</title>
</head>
<body>
<header>
<h1>{{ site.title }}</h1>
</header>
<main>
{{ page.content }}
</main>
<footer>
<p>© {{ site.title }}</p>
</footer>
</body>
</html>
Step 6: Build the Site
php cecil.phar build
Output is generated in _site/ directory.
CLI Commands
| Command | Purpose |
|---|---|
php cecil.phar new:site | Create a new website |
php cecil.phar new:page | Create a new page |
php cecil.phar build | Build the static site |
php cecil.phar serve | Start lo |