Using the Grunt task automator to use LESS in MadCap Flare projects

Using the LESS CSS Preprocessor in your Flare Project

I’ve worked in hundreds of Flare projects since I started my business around 5½ years ago, and when you work in that many projects, you start to notice trends. There are a handful of issues that I know I’m likely to find in nearly any Flare project that I work in, and one of the most predictable issues is unwieldy and inefficient stylesheets.

To properly maintain a stylesheet takes a lot of time. Most Flare users aren’t focused on maintaining stylesheets, but rather on developing great content, so it’s no wonder that the stylesheets can fall into a state of disrepair.

Like with any problem that I see over and over, I want to find a solution. So, a number of months ago, I started looking into ways that I could use a CSS preprocessor to develop CSS for Flare. Having now used this solution in a number of Flare projects, I can safely say that I don’t ever again want to develop CSS without using a preprocessor.

What is a CSS Preprocessor?

In a nutshell, and CSS Preprocessor converts a specific type of file (written in a maintainable and streamlined format) into a CSS file that Flare and web browsers can use. For a good overview, see this intro to CSS Preprocessors.

In the example described in this post, we’ll be setting up a solution that uses the LESS CSS preprocessor to develop CSS.

How do LESS files get converted to CSS files?

In this example, we’re going to set up a solution that uses a task automator called Grunt to automatically convert a LESS file into a CSS file whenever you make a change to the LESS file. Both the LESS file and the resulting CSS file are part of the Flare project. Using Grunt to automatically convert the file, you’ll be able to see changes in your LESS file show up immediately in the topics you’re editing in the Flare XML Editor.

Is This Solution Right for Me?

There are a couple things to consider before making the jump to using LESS to develop CSS.

  • Are you able to do CSS development in code?
    Using LESS requires you to do your CSS development in code. There is no GUI interface. If all you’ve ever used is the Flare CSS editor, then you’ll want to learn how to code CSS first. Once you start using this process, you can use the Flare CSS editor as a CSS viewer, but any changes you make directly in the Flare CSS editor will be lost the next time you update your LESS file.
  • Is your stylesheet complex or fairly simple?
    If your project’s stylesheet is short and simple, then this CSS Preprocessor solution might be overkill. This solution is ideal for more complex stylesheets.

The steps in this procedure will set up a sandbox environment for you to try out LESS. These steps won’t affect your production-level project until you manually configure the files to point to your actual project.

Where can I learn more about LESS?

This article isn’t focused on the merits and capabilities of LESS, but rather on getting it set up and working in Flare. There are all kinds of resources out there to learn more. Lynda and Pluralsight both have courses, and a simple Google search for CSS LESS will yield all kinds of results.

I’m ready! How do I set this up?

In these steps, we’re going to set up Grunt to automatically convert a LESS file into a CSS file in a sample Flare project.

  1. If you don’t already have node.js installed, then download and install it from nodejs.org. Grunt runs on node.js.
  2. On your hard drive, create a folder called C:\grunt-pre. This folder name indicates that this folder contains tasks we’ll automate on a pre-build basis (as opposed to running Grunt on a post build basis).
  3. Download this zip file, and extract the contents into the C:\grunt-pre folder.
  4. Open up a windows command prompt. and run the following commands to install the necessary software for Grunt.
    1. cd C:\grunt-pre. This moves you to the C:\grunt-pre folder.
    2. npm install grunt --save-dev. Install Grunt.
    3. npm install -g grunt-cli. Install the Grunt command line interface.
    4. npm install jit-grunt --save-dev. Install the grunt “Just-In-Time” plugin.
    5. npm install grunt-contrib-less --save-dev. Install the LESS-to-CSS plugin. This plugin performs the actual LESS-to-CSS conversion.
    6. npm install grunt-contrib-watch --save-dev. Install the watch plugin. This is the plugin that allows us to watch our less folder for any changes to the less file.
    7. Once all the software is installted, run grunt pre from the command line. This starts the grunt process. Leave the command line window open.

Grunt is now set up and ready to convert your LESS file to a CSS file in the sample Flare project that is in your grunt-pre folder.

Testing it out

In the C:\grunt-pre folder, there is a sample Flare project in the FlareProject folder. This project includes a sample LESS file and the resulting CSS file.

In a code editor, open the main.less file that is in C:\grunt-pre\FlareProject\less-test\Content\Resources\Stylesheets\less. You can also open Flare and open this file in the Flare’s internal text editor, although I prefer using a code editor (my preferred editor is Visual Studio Code). In this file, you’ll see some non-standard CSS elements, such as variables, mixins, and nested classes.

Make a change to the main.less file. Less supports all CSS, so any standard CSS will do.

Save the file. All the non-standard CSS gets converted to CSS in the main.css file, which is in the Stylesheets folder of the Flare project. If you switch back to your command line window, you’ll see that Grunt converts the LESS file every time you save it.

Setting it up in your own Flare project

If you’ve tested LESS and have decided that you want to start using it in your own Flare project, you’ll need to make a couple adjustments to the Grunt configuration file and add a LESS file to your Flare project. If you’re working in a Flare project that is not bound to source control, I recommend backing up your project before doing these steps.

In this scenario, my production Flare project is in the C:\Flare Projects\My Project folder. In that Flare project, my production stylesheet is Styles.css, and it’s in the Resources\Stylesheets folder.

First, let’s create a new LESS file from your existing CSS file so that no existing styles are lost. In Flare, create a new folder under the Stylesheets folder, and call it less. Copy and paste the Styles.css file into the less folder, and then rename that file (the one in the less folder) to Styles.less.

Next, go to the C:\grunt-pre folder, and open Gruntfile.js in a code editor. On line 14, update the path to the source LESS file and the resulting CSS file in your project. In this example, update the lines as follows:

"C:/Flare Projects/My Project/Content/Resources/Stylesheets/Styles.css": "C:/Flare Projects/My Project/Content/Resources/Stylesheets/less/Styles.less"

Also update the folder to watch on line 21:

"C:/Flare Projects/**/*.less"

Save the Gruntfile.js file.

Finally, go back to the command window and run grunt pre.

Note: If the process is currenlty running, you’ll need to press Ctrl + C to stop it, and then run grunt pre.

Grunt will convert your existing Styles.less file into a new Styles.css file. From this point forward, you can start doing all your CSS development in your LESS file.

Next Steps

As I mentioned previously, the focus of this article is on setting up LESS to work in a Flare project. There is so much more to learn about LESS. Take some time to learn more about LESS so that you can create strategies to effectively manage your CSS over time.

Additional Consulting and Training

We offer professional Flare Training and Consulting services. If you are just getting started in Flare, or if you are an experienced user wondering where your project can be improved, get in touch. We’ll schedule a free strategy session to see how we can help.