Static resources - limburgie/c3s GitHub Wiki

It is typical for templates in a website to reference static resources such as images, stylesheets and Javascripts. In this page, we explain where these resource should reside and how to reference them from pages and templates.

The assets folder

In C3S, all static resources must reside under an assets root folder, which should be on the same level as c3s.json. Inside that folder you can include subfolders for CSS, Javascripts or whatever static resources your site's theme exists of.

Let's take a look at the folder structure for the C3S Quickstart site:

site/
├─ assets/
├─── css/
├───── style.css
├─ pages/
├─── home.ftl
├─── news.ftl
├─ templates/
├─── main.ftl
├─ c3s.json

As you can see, style.css resides in assets/css relatively to the c3s.json file.

Referencing assets

If you need to reference static resources from a page or template, it is recommended to use absolute URLs:

<!doctype html>
<html>
<head>
    <title>${site.name}</title>
    <link href="/assets/css/style.css" rel="stylesheet">
</head>
<body>
    ...
</body>
</html>

When referencing assets from other assets, it is of course better to use relative URLs. E.g. when referencing images from a CSS file:

header {
    background: url("../img/bg-primary-green.jpg") no-repeat;
    background-size: cover;
    padding: 2rem 0;
    position: relative;
}

Caching

Static resources are by default cached for 1 hour. During development, it is recommended to disable the cache inside the browser so you can immediately verify your changes. It is currently not possible to configure or disable the asset cache in C3S using configuration.

Automatic SASS compilation

SASS files (CSS with .scss extension) are automatically parsed by C3S and the result of the SASS parser is also cached. If C3S receives a request for a CSS file and it cannot find that file, it will look for a SCSS file with the same name on the same location. If such file can be found and successfully parsed, C3S will return the parsed CSS as if it was residing on the server.

This way, you can keep your HTML file clean like the example above, while using SASS instead of CSS to simplify development.

Your file structure would look like this:

site/
├─ assets/
├─── css/
├───── style.scss
├─ pages/
├─── ...
├─ c3s.json

In your page or template you would still reference the stylesheet as if it was normal CSS:

<!doctype html>
<html>
<head>
    <title>...</title>
    <link href="/assets/css/style.css" rel="stylesheet">
</head>
<body>
    ...
</body>
</html>

But in reality, your CSS file is actually a SASS file:

body {
  h1 {
    margin-top: 20px;
  }
}