Updating your site CSS

Don’t mind the quickly thrown together guide :sweat_smile: Let me know if you’re missing something!

Intro

Your site-root directory contains a css directory and a sass directory. Take a quick peek inside the css directory and notice the following files and directories:

bootstrap/bootstrap.css
plugins/*
laddr/*
branding/*

These are the stylesheets that Laddr pulls into the main site out-of-the-box and are not generated from SASS. You can edit them directly but note that unless you’re adding new files you won’t be able to receive updates from upstream anymore.

Editing with SCSS

You can edit main.css by editing files under the sass directory. Remember that main.css isn’t loaded in by default and, at the time of this writing, loading it in throws your template off, so unless someone corrects me, you might want to start with a fresh main.scss.

To compile, navigate to yourdomain.com/sass/compile and wait for that to run. site-root/css/main.css will be updated with your changes.

Adding additional css files to your site

Now you need to include main.css and any other new css files you made on your site! Open html-templates/includes/site.css.tpl. You’ll find a call to cssmin with an array containing the default paths I reviewed at the start of this post. Add your files (relative to the /css directory), save, then go and check out your freshly styled Laddr instance!

1 Like

This is awesome @AndrewNatoli, thanks for putting it together!

To add some background that might be helpful:

The site-root/sass tree

Nothing in the sass directory is used by Laddr, the files in there are defaults from the template site Laddr is built on. If you like to use sass, you can make use of the sass compilation infrastructure exactly as @AndrewNatoli described. Most of the files that will compile out of the sass tree’s default contents won’t be useful in the bootstrap-based Laddr. There’s no harm or risk to creating your own files here or repurposing the names of upstream files like main.scss for your own sheet to then include

The {cssmin} template tag

The {cssmin} template plugin provides a convenient syntax and efficient implementation for including one or more .css files into your markup. It works with any files under the site-root/css/ tree, including ones written directly and ones compiled from the site-root/sass directory via /sass/compile.

Each {cssmin} tag can include one or more files from site-root/css, supporting * as a wildcard character and + as a delimiter for listing multiple filenames or patterns. An array can also be provided and is equivalent to using +. The matched files will be concatenated together into one big file, minified, and cached in memory. Edits to any files under site-root/css will immediately update the cache.

Debugging CSS

While you’re working on CSS, you will likely find it helpful to add ?cssdebug=1 to the URL of the page you are working on. This will cause the {cssmin} plugin to output direct links to every source file rather than a single minified request.

Because of this, it is helpful to upload only original CSS and not pre-minified files. The CSS files output by SASS compilation are unminified and include comments citing the source of each rule. For libraries, the unminified version of the file is usually uploaded as mylibrary.css.

The <link> tags written in debug mode include a hash of the file’s current content in the URL that triggers very aggressive caching headers. After you change a file, the next load of the page will include a new URL for that file with the new hash. Because of this, you can leave your developer tools’ “disable caching” option off; pages will refresh far faster while changes still always take effect immediately.