Skip to main content

Using Pelican with Sass and Bootstrap v5

code
A guide to integrating Dart Sass with Pelican for Bootstrap v5 projects using Docker.

Introduction

Bootstrap v5 uses Dart Sass for compiling Sass source files into CSS files. When building Pelican-based websites with Bootstrap v5, it's recommended to follow the same approach for your asset pipeline. This article explains how to set up a Docker-based Dart Sass workflow that integrates with Pelican.

Prerequisites

  • Docker installed on your system
  • Basic familiarity with Pelican static site generator
  • Understanding of Sass/SCSS for CSS preprocessing

Setting up Dart Sass with Docker

We can use the michalklempa/dart-sass Docker image to create a containerised Sass compilation environment:

Basic usage

No specific action needs to be taken to use this image in a Pelican theme development workflow. Setting the watch directory and running the container is sufficient to get the SCSS files compiled into CSS files whenever an SCSS file is saved.

docker run -v $PWD/sass:/sass/ -v $PWD/css:/css/ -it michalklempa/dart-sass:latest

This command:

  • Mounts your local sass directory to the container's /sass/ directory
  • Mounts your local css directory to the container's /css/ directory
  • Runs the container in interactive mode, watching for changes in the sass directory

Advanced integration options

Creating a custom Pelican extension

For deeper integration with Pelican, you might want to create a custom extension. This section outlines the approach, though I haven't needed such an extension in my projects so far.

Overriding the entrypoint

The original Docker image runs with a -watch command by default. To make the container compatible with a custom extension, you'll need to override its entrypoint before including integrated sass processing in the Pelican pipeline:

# docker run --entrypoint [new_command] [docker_image] [optional:value]
docker run --entrypoint /opt/dart-sass/sass -v $PWD/sass:/sass/ -v $PWD/css:/css/ -it michalklempa/dart-sass:latest sass:css

Missing autoprefixer support

Warning

This Docker image does not include an [autoprefixer](https://github.com/postcss/autoprefixer), which Bootstrap [lists as a requirement](https://getbootstrap.com/docs/5.2/getting-started/download/#source-files) for compiling Bootstrap from source.

If you need autoprefixer support, consider:

  1. Adding a separate step in your build process
  2. Using an online tool for development: https://autoprefixer.github.io/
  3. Creating a custom Docker image that includes both Dart Sass and autoprefixer (you might refer to this repository for implementation ideas)

Conclusion

This setup provides a straightforward way to use Dart Sass with Pelican for Bootstrap v5 projects. The Docker-based approach ensures that your development environment is isolated and reproducible, making it easier to maintain across different systems.

For most Pelican theme development workflows, the basic usage pattern will be sufficient. If you need more sophisticated integration, consider extending this approach with a custom Pelican plugin or a more comprehensive Docker image.