Build Config in Ionic

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.

Elite Ionic Screenshot

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*/

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.


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.

What to watch next...

  • Bart

    Good tutorial! I might just use this as I’m also a markdown adept and use code examples.

    But can’t you just import the css file in main.scss or another bundle? And if not, why not? According to the SASS spec it allows importing both .scss and regular .css files. Just use the .css extension

    The sass to css compolation should happen before any uglifiation or concatenation, so there should be no performance penalty. And the advantage over your solution would be that you don’t have a manual upgrade of the cloned sass.config.js file if Ionic upgrades (or switches bundler yet again… :P). But I could be wrong.

    • Bart

      Ah wait, there IS a performance penalty as importing a .css file falls back to native css @import statement. And that requires another roundtrip, and ofcourse provides
      no minification from your build pipeline (though the Prism download dialogue has a minified version as default).

      But that’d be fixed by renaming the prism.css file to prism .scss and just using’@import ‘prism’ (without extension). This manual step is somewhat simpler than using custom ionic app scripts, so unless you’re already doing that, this might be simpler.

      But I haven’t tried it out yet, so no pudding to proof it with 🙂

  • SaskiaS

    I’m curious, would there be a similar process in adding external .js files? I have quite a few, mainly mathematical, that I really don’t want to convert into typescript…