Including Custom CSS Files in the Ionic Build Process

HTML has to take first place for markup languages, but Markdown is up there with my favourites. I use markdown for pretty much all the writing I do, and I’m also using it to format all of the lessons in Elite Ionic.

It’s not much use displaying Markdown as is, though, if I want to use it for displaying the lessons in the application for the course (which is built with Ionic) then I’m going to need it converted to HTML. On top of that, I also need syntax highlighting for the <code> blocks. I spent a little while looking for a library to handle converting markdown into HTML and set up syntax highlighting – I tried a few different options and then came across Angular 2 Markdown.

It uses Marked for markdown conversion and Prism for syntax highlighting, and it works fantastically in an Ionic application.

The setup for this plugin is mostly pretty straightforward, so I’m not going to repeat the documentation here. However, the documentation describes the setup for Angular, not Ionic, and as part of the setup process, it requires that you include a custom CSS file from Prism.

In order to include this file, you could add the CSS file to your src/assets folder and then add the following to your index.html file:

<link href="assets/css/prism-okaidia.css" rel="stylesheet" />

Although this is not the most Ionic/Angular way to do it, I don’t think this method is particularly bad. However, there is a better way to do it. The performance penalty for including the CSS file this way may be small, but if you were to include lots of files in this manner you could start to see a serious performance hit as the boot time of our application is slowed down waiting for network requests to load unoptimised files.

Creating a Custom SASS Configuration for Ionic

As part of the build process, Ionic will build a main.css file using SASS which will contain all of the CSS code for your application. This will include all of the .scss files throughout your application, as well as some other files that are imported like Ionic’s themes, ionicons, and fonts.

What we want to do is let our Prism theme files in on this build party. To do that, we are going to need to create a custom SASS configuration file.

Create a folder called in the root folder of your application called config

We are going to use this folder to hold our configuration file (and you could also add other config files here as well).

Copy sass.config.js from node_modules/@ionic/app-scripts/config/sass.config.js to your new config folder

This is the SASS configuration file that Ionic uses by default. We are making our own copy of it and we are going to make some slight modifications. Although it may seem easier, don’t be tempted to just make the change directly in the existing sass.config.js file, as that will just be overwritten when you install the node_modules in your application.

Modify the includePaths array in config/sass.config.js to reflect the following:

includePaths: [
    /*other files*/
    'node_modules/prismjs/themes'
  ],

Make sure you leave the other paths in the array untouched, but you should add the new paths that you want to include here. In this case, we are including the themes for Prism.

Add the following entry to your package.json file:

"config": {
    "ionic_sass": "./config/sass.config.js"
  }

This will tell Ionic to use our custom SASS configuration file instead of the default one. You can use this same method to override any of the build configurations. You can find a list of the different files and the keys that you need to add to package.json here: Ionic App Scripts.

Add the following import to src/theme/variables.scss:

@import 'prism-okaidia';

Now you just need to import whatever theme you want from the Prism ‘themes’ folder – once that is done, the CSS file will be available to use in your application.

Summary

The primary benefit of doing this is that the CSS files are now just included as part of Ionic’s normal build process, which means they will be included in the minimised main.css file. That means one less network request (or many fewer network requests if you were including multiple files) and no extra effort required to minimise the file.