Headers component theme

The Headers component theme for Cecil provides support of _headers file generation.

After installation and without any configuration, this component theme generates a _headers file containing default HTTP headers (security and cache) and the HTTP headers defined in the server.headers configuration.

Services that support the _headers file:

• Netlify
• statichost
• Cloudflare Pages

Note

The Netlify component theme already generates a _headers file: don't use both themes together.

Installation

composer require cecil/theme-headers

Or download the latest archive and uncompress its content in themes/headers.

Usage

Add headers in the theme section of your site configuration:

theme:
  - headers

The _headers file is generated at the root of the output directory (_site/ by default).

Add headers

server:
  headers:
    - path: <path> # Relative path, prefixed with a slash. Support "*" wildcard.
      headers:
        - key: <key>
          value: "<value>"

Documentation: https://cecil.app/documentation/configuration/#server-headers

Your headers are added after the default headers of the theme (they are also applied by the local preview server cecil serve).

Default headers

The theme provides the following default headers:

Path	Headers
/*	X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security
/favicon*, /logo*, /icon*, /assets/*, /images/*, /videos/*, /styles/*, /css/*, /*.css, /fonts/*	Cache-Control: public, max-age=31536000 (1 year)
/javascript/*, /js/*, /*.js	Cache-Control: private, max-age=31536000 (1 year)
/serviceworker.js, /manifest.webmanifest	Cache-Control: no-cache
/admin/*	Cache-Control: no-cache, no-store, must-revalidate, permissive Content-Security-Policy

Important

Files with a long cache lifetime should have a fingerprint in their name (see assets.fingerprint), otherwise visitors may not receive their updates.

To replace the default headers, copy them from the theme config.yml into the headers.default section of your site configuration, then edit them. To disable them:

headers:
  default: false

When a path matches several rules, the headers of all matching rules are applied.

Development

The demo/ website uses the theme under development and covers the supported cases (default headers, headers defined in server.headers, default headers disabled):

php demo/link.php
php cecil.phar build demo
php cecil.phar build demo --config config.no-default.yml --output _site_no-default

The generated _headers files must match demo/expected/_headers and demo/expected/_headers.no-default: this is checked by the Test workflow.

License

Headers is a free software distributed under the terms of the MIT license.

© Arnaud Ligny