Building an Org Mode Website: Part 6 - Integrating SCSS Style Sheets

Published: August 2, 2025

Integrating SCSS Style Sheets

For most of my web projects I have been in the habit of using SCSS style sheets to generate the CSS for the website. SCSS is a way to generate CSS code using a c-like block structure and has robust support for modules, variables and other features that can make crafting a CSS style sheet a little more organized than just writing CSS directly.

Setting up SASS

SCSS files require processing before they can be used on a website. The Sass program is the tool that does that. If you do not already have Sass installed, you can go to https://sass-lang.com/ for details on how to install it for your system and how to write SCSS code. Once installed, you do need to make sure that the Emacs can run the sass program. With some of the standard ways of installing sass, it does not end in what Emacs uses for your $PATH variable. In my case, for some of my computers I needed to manually create a symlink from ~/.local/bin/sass to the actual location of the program.

SCSS Publishing Function

The Org Mode publishing system has an option to add a 'preparation' function to a project in your org-publish-project-alist variable. An example of how that can work is listed below.

("org-scss"
 :base-directory "./assets/scss"
 :base-extension "css"
 :publishing-function org-publish-attachment
 :publishing-directory "./staging"
 :recursive t
 :preparation-function
 (lambda (project-plist)
   (call-process "sass" nil nil nil
                 (expand-file-name
                  (plist-get project-plist :base-directory)))))

When this project is published, Emacs will first call the function assigned to the ':preparation-function' parameter and then continue with the rest of the publishing actions defined by the project. In this example, the SCSS code is placed in './assets/scss', Emacs runs sass on the directory, and then copies any css files in that directory to the publishing directory, './staging'.

Post Publishing Actions

You can use the ':completion-function' to do any clean-up actions after the publishing fuctions. For example, you might want to delete any files that are generated by the sass program after you have copied over the CSS output to your publishing directory.

Other Notes

Publishing Other Types of Generated Files

You can, of course, use this basic technique to publish other types of files or do other processing before copying files to your publishing directory. For example, if you have some Javascript code on the website, it could be run through a minifier/compressor before being published.

My SCSS Source Files

If interested, the SCSS code that I am using for this website is available on GitHub at this address: https://github.com/KigraSoft/ks-scss-styles.