Cecil Static Site Generator

Cecil is a content-driven static site generator with the following core characteristics:

• Architecture: No database or server required, improving performance and security.
• Content: Pages are stored as Markdown flat files using YAML front matter.
• Templating: Powered by the Twig template engine with support for themes.
• Automation: Automatically generates pagination, sitemaps, redirections, robots.txt, taxonomies, and RSS feeds.
• Asset Management: Handles and optimizes assets automatically.
• Deployment: Designed for easy deployment to platforms like Netlify or Vercel.

Cecil projects rely on a specific directory structure to manage templates, server configuration, project skeletons, and translations.

• layouts/: Contains Twig template files.
  • _default/: Core templates for pages, lists, and feeds.
  • extended/: Macros and theme-specific templates.
  • partials/: Reusable UI components like navigation or metatags.
• server/: Contains files for the local development environment, including router.php (the PHP router) and livereload.js (for automatic browser refreshes).
• skeleton/: Provides a starting point for new projects, including a default cecil.yml configuration, sample pages/, layouts/, and assets/.
• translations/: Stores multilingual data using .po (source) and .mo (compiled) files.

Cecil's local PHP server uses specific helper files to manage site serving and development features. The server relies on a custom router and a live-reload mechanism to provide a seamless local development experience.

Core Components

• router.php: Acts as the router for the PHP built-in server (php -S). It is responsible for resolving requested paths, serving static files, and managing custom 404 behavior for the generated site.
• livereload.js: A script injected into HTML responses. It enables automatic browser reloading by listening to /watcher via Server-Sent Events (SSE), triggering a reload whenever changes are detected.

The Cecil Skeleton provides a standard directory structure for organizing a Cecil site. When starting a new project, use this layout to manage configuration, assets, templates, and content:

• cecil.yml: The central site configuration file.
• assets/: Directory for source assets such as styles (CSS), scripts (JS), and other media.
• layouts/: Contains Twig templates used to define the structure of your pages.
• pages/: Contains Markdown files which serve as the content for your site pages.
• static/: Contains static files that are copied directly to the output directory without processing.

Taxonomies allow you to connect and classify content using vocabularies (e.g., tags, categories) and terms (e.g., PHP, Development). Vocabularies must be declared in the Configuration.

---
tags: ["Développement", "PHP"]
---

Cecil implements file-based routing based on the location of Markdown files within the pages directory. The URL is constructed from the baseurl, the section (folder), and the slug (filename).

Example Mapping:

• File Path: pages/my-projects/project-a.md
• Resulting URL: https://example.com/my-projects/project-a/ (or .../project-a/index.html depending on server configuration).

Note: Certain prefixes can alter the URL behavior.

Cecil categorizes content into four main types:

• Pages: The primary content of your site, written in Markdown. Pages are organized into Sections (root folders) and their structure reflects the rendered website hierarchy.
• Assets: Files that undergo processing (e.g., resizing images, compiling Sass, minifying scripts). These are accessed in templates using the asset() function.
• Static files: Files that are copied directly to the built site without modification (e.g., a PDF in static/file.pdf becomes file.pdf in the output).
• Data files: Collections of custom variables stored in files (like .yml) and exposed in templates via the site.data object.

Cecil uses Gettext-style translation files to support multiple languages. The system relies on two specific file types for each language:

1. Source Catalog (.po): The editable text files containing the actual translations (e.g., messages.fr.po). This is where you add or modify translation strings.
2. Compiled Catalog (.mo): The binary files used by the application at runtime (e.g., messages.fr.mo). These are generated from the .po files.

Currently, the repository includes translations for French (fr), but the architecture allows for additional languages to be added by providing corresponding .po and .mo files.

Cecil uses a specific directory structure within resources/layouts/ to manage Twig templates. Understanding this structure is essential for customizing how your site renders:

• _default/: Contains the primary fallback templates. These provide core structures (like single pages or lists) when no specific template is assigned to a page.
• partials/: Contains reusable template fragments. Use these for shared UI components like headers, footers, or navigation to avoid code duplication.
• extended/: An optional directory for advanced or custom rendering scenarios, allowing you to host alternative template variants without modifying the default baseline.