Skip to content
CecilappPublic

About

Documentation site for the Cecil static site generator.

Topics

Resources

Stars

4 stars

Watchers

1 watching

Forks

Repository files navigation

cecil.app

Source code of cecil.app website, generated with Cecil (obviously) and hosted by Netlify.

Netlify Status

A mirror is also deployed on Cloudflare Pages, built with the Cecil standalone binary (no PHP):

  • Build command: bash ./scripts/cloudflare-build.sh
  • Build output directory: _site
  • Environment variables (optional): CECIL_VERSION (latest release by default), CECIL_BASEURL (deployment URL by default)
  • Daily build: deploy hook stored in the CLOUDFLARE_PAGES_DEPLOY_HOOK repository secret

Themes are installed from composer.lock without Composer, _redirects is adapted to Cloudflare Pages and the *.pages.dev domain is not indexed.

Another mirror can be deployed on Render with the render.yaml Blueprint, also built with the standalone binary (bash ./scripts/render-build.sh). Headers and non-HTML redirects are defined in the Blueprint, and the mirror is not indexed.

Install

Download Cecil

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

Install dependencies

composer install

Usage

Contribute to the documentation

The documentation is available in docs at github.com/Cecilapp/Cecil.

Create a news entry

php cecil.phar new:page --name=news/cecil-X.Y.0-released --prefix

Preview locally

vendor/bin/tailwind-builder assets/css/tailwind.css -o assets/styles.css --watch
XDEBUG_MODE=off php cecil.phar serve -v --config=config/dev.yml

Build for production

vendor/bin/tailwind-builder assets/css/tailwind.css -o assets/styles.css --minify
php cecil.phar build

Build CSS

composer run css:build

Build translations

French strings live in translations/messages.fr.po (edited with Poedit). The compiled .mo can be regenerated without gettext tools:

composer run i18n:build

Fetch themes, components and starters data

Data are fetched from the GitHub API (requires jq):

curl -s -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/search/repositories?q=topic:cecil-theme+org:Cecilapp+fork:true+is:public+archived:false' | jq '[.items[] | {name, full_name, description, github: .html_url, license: .license.name, homepage, date: .pushed_at, default_branch, topics}] | sort_by(.date) | reverse' > data/themes.json
curl -s -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/search/repositories?q=topic:cecil-theme-component+org:Cecilapp+fork:true+is:public+archived:false' | jq '[.items[] | {name, full_name, description, github: .html_url, license: .license.name, homepage, date: .pushed_at, default_branch, topics}] | sort_by(.date) | reverse' > data/components.json
curl -s -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/search/repositories?q=topic:cecil-starter+org:Cecilapp+fork:true+is:public+archived:false' | jq '[.items[] | {name, full_name, description, github: .html_url, license: .license.name, homepage, date: .pushed_at, default_branch, topics}] | sort_by(.date) | reverse' > data/starterkits.json

Add a website to the showcase

The showcase (/showcase/) lists the websites of data/showcase.yml, with a screenshot from assets/images/showcase/. scripts/showcase.mjs collects the data of a website built with Cecil from its URL:

npm install                      # once
npx playwright install chromium  # once (or set CHROME, falls back to the installed Chrome)
npm run showcase -- https://example.com          # prints the YAML entry
npm run showcase -- https://example.com --write  # appends it to data/showcase.yml
  • Data: title (og:site_name or <title>), descriptions in English and French (hreflang alternate pages), GitHub repository (if linked from the page); the generator meta tag is checked.
  • Screenshots: 1280×800, <name>.png, plus <name>.dark.png if the site supports dark mode (prefers-color-scheme, localStorage.theme or a dark class/attribute), displayed automatically by Cecil for visitors in dark mode.
  • Options: --title=, --github=, --name= (screenshot file name, the domain by default), --no-screenshot.

Review the descriptions (shorten them, translate those marked TODO) and the screenshots (cookie banners, popups) before committing.

Social images

The image displayed when a page is shared (Open Graph, X Card) is generated at build time by the Open Graph image component theme (cecil/theme-ogimage): the title of the page drawn on static/images/cecil-card-2.png, with the Montserrat fonts of assets/ogimage/fonts/.

  • Generated: an og.png next to each page (e.g. /documentation/quick-start/og.png), given to the metatags partial with og_image(page) in layouts/page.html.twig.
  • Not generated: pages with an image in their front matter, and the homepage (the site image is used).
  • Configuration: under the ogimage key of cecil.yml (disabled in config/dev.yml for faster local builds); see the theme documentation for all the options.

The PHP GD extension with FreeType support is required: without it, a warning is logged and the site image is used.

Search

The site is searched client side with the FlexSearch component theme (cecil/theme-flexsearch): no service, works offline, in English and French.

Search is configured in cecil.yml, under the flexsearch key; the indexed sections are listed in the order of the result groups:

flexsearch:
  enabled: true # display the search box
  sections:
    documentation:
      limit: 5 # maximum number of results in the group
    how-to:
      limit: 3
      split: false # one record per post, not one per heading
    news:
      limit: 3
      split: false
      date: true # show the date of the post in the search results

See the theme documentation for all the options.

  • Index: /flexsearch.json (and /fr/flexsearch.json), generated at build time by the theme.
  • UI: included in the header with partials/flexsearch.html.twig; the theme stylesheet is inlined before the main CSS, and customized (colors, header trigger) in assets/css/search.css.

About

Documentation site for the Cecil static site generator.

Topics

Resources

Stars

4 stars

Watchers

1 watching

Forks

Sponsor this project

Used by

Contributors

Languages