Cecil is distributed as a single executable file, cecil.phar, which runs anywhere PHP is installed.

Requirements

• PHP 8.3+
• PHP extensions: fileinfo, gd and mbstring

Check your PHP version and loaded extensions:

php -v
php -m

Optional extensions

Download the PHAR

Download cecil.phar from your terminal:

curl -LO https://cecil.app/cecil.phar

Then run it with PHP:

php cecil.phar --version

Install globally

Installing Cecil globally allows you to run the cecil command from any directory, instead of php cecil.phar.

macOS and Linux

With Homebrew:

brew install cecilapp/tap/cecil

Or manually, by moving the PHAR in a directory of your PATH:

mv cecil.phar /usr/local/bin/cecil
chmod +x /usr/local/bin/cecil

Windows

With Scoop:

scoop install https://cecil.app/scoop/cecil.json

Or manually:

1. Move cecil.phar in a dedicated directory, like C:\bin
2. Rename it from cecil.phar to cecil
3. Append ;C:\bin to your PATH environment variable
4. Create a wrapping batch script next to it

PHIVE

With PHIVE (The PHAR Installation and Verification Environment):

phive install cecil

Composer

With Composer:

composer global require cecil/cecil

Verify the installation

cecil --version

Update

Update Cecil to the latest version according to your installation method:

# PHAR
php cecil.phar self-update
# Homebrew
brew upgrade cecilapp/tap/cecil
# Scoop
scoop update cecil
# PHIVE
phive update cecil
# Composer
composer global update cecil/cecil

The self-update command (PHAR only) also accepts the following options:

• --rollback: reverts to the previous installed version
• --stable: forces an update to the last stable version
• --preview: forces an update to the last unstable version

Troubleshooting

command not found: cecil

The installation directory is not in your PATH: add it, or run Cecil with php cecil.phar from the directory containing the PHAR.

PHP version or extension error

Your PHP CLI may differ from the one you expect (several versions installed): check it with php -v and php --ini, then enable missing extensions in the loaded php.ini file.

Diagnose a website

Once a website is created, run the doctor command to diagnose its configuration.

File system tree

Project files organization.

<mywebsite>
├─ pages
|  ├─ blog            <- Section
|  |  ├─ post-1.md    <- Page in Section
|  |  └─ post-2.md
|  ├─ projects
|  |  └─ project-a.md
|  └─ about.md        <- Root page
├─ assets
|  ├─ styles.scss     <- Asset file
|  └─ logo.png
├─ static
|  └─ file.pdf        <- Static file
└─ data
   └─ authors.yml     <- Data collection

Built website tree

Result of the build.

<mywebsite>
└─ _site
   ├─ index.html               <- Generated home page
   ├─ blog/
   |  ├─ index.html            <- Generated list of posts
   |  ├─ post-1/index.html     <- A blog post
   |  └─ post-2/index.html
   ├─ projects/
   |  ├─ index.html
   |  └─ project-a/index.html
   ├─ about/index.html
   ├─ styles.css
   ├─ logo.png
   └─ file.pdf

File based routing

Markdown files in the pages directory enable file based routing. Meaning that adding a pages/my-projects/project-a.md for instance will make it available at /project-a in your browser.

File:
                   pages/my-projects/project-a.md
                        └───── filepath ──────┘
URL:
    ┌───── baseurl ─────┬─────── path ────────┐
     https://example.com/my-projects/project-a/index.html
                        └─ section ─┴─ slug ──┘

Create a website

You can create a new website from scratch in a few minutes.

Follow the steps below to create your first Cecil website.

Prerequisites

• PHP 8.3+
• Terminal (a basic understanding of terminal)
• Text editor, like VS Code and/or Typora

1. Download Cecil

Download cecil.phar from your terminal:

curl -LO https://cecil.app/cecil.phar

You can also download Cecil manually, or use:

• Homebrew: brew install cecilapp/tap/cecil
• Scoop: scoop install https://cecil.app/scoop/cecil.json

2. Create a new site

Create a directory for the website (e.g.: <mywebsite>), put cecil.phar in it, then run the new:site command:

php cecil.phar new:site

3. Add a page

Run the new:page command:

php cecil.phar new:page

Now you can edit the newly created page with your Markdown editor: <mywebsite>/pages/<new-page>.md.

4. Check the preview

Run the following command to create a preview of the website:

php cecil.phar serve

Then navigate to http://localhost:8000.

5. Build and deploy

When you are satisfied with the result, you can generate the website in order to deploy it on the Web.

Run the following command to build the website:

php cecil.phar build

You can now copy the content of the _site directory to a Web server 🎉

To get started quickly, use one of Cecil's ready-to-use starter kits:

• The Butler: a publishing-ready starter blog.
• Links: an open source Linktree alternative.
• Photo Stream: a super simple self-hosted photo stream.
• Statidocs: build a documentation website quickly.