Programming

Customize a Bootstrap Theme with Umbraco

Lately, I've been looking at a few different options for a CMS platform. Of the ones that I've looked at, I think Umbraco makes the most sense, considering that most of my work uses C# & .Net, it has online hosting for ~$35/month, and it's been the easiest for me to understand.

Kevin Williams

Kevin Williams

— 3 min read

Lately, I've been looking at a few different options for a CMS platform. Of the ones that I've looked at, I think Umbraco makes the most sense, considering that most of my work uses C# & .Net, it has online hosting for ~$35/month, and it's been the easiest for me to understand.

One of the downsides however, is that it doesn't come with any pre-built "themes," so it's up to you to build everything. While not necessarily a problem, it can pose a challenge if you're not great with frontend design, such as in my case. I decided to use Bootstrap while I was testing it out and took a lot of their example components and layouts.

One thing I wanted to do right away was customize the theme colors. Of course, the docs seemed simple enough, but not having worked with sass before, I was a bit lost. Luckily, I found this video which explained everything and worked quite well.

Add Bootstrap

The first thing we have to do is add bootstrap to the Umbraco project. This can be done by adding a libman.json file to the root directory

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "bootstrap@5.2.3",
      "destination": "wwwroot/lib/bootstrap/"
    }
  ]
}

Once the file's been created, you can right click on the solution from Visual Studio and choose "Restore Client-Side Libraries." This should add a /lib/bootstrap directory under wwwroot.

Define Your Theme Colors

Now that we have the bootstrap files, we can create an scss file that contains our definitions and then import everything else from bootstrap

$primary: #306B2B;
$secondary: #FF9F1D;

@import "lib/bootstrap/scss/bootstrap.scss";

My current directory structure at this point looks like the following:

- Project
  - wwwroot
    - lib
      - bootstrap
        - css
        - js
        -scss
    - my-styles.scss

Add NPM Dependencies

At this point, we have the sass files, but they can't be used quite yet. First, we have to compile the sass into css. This can be done by adding a package.json to the project with the following contents:

{
  "dependencies": {
    "gulp": "4.0.2",
    "gulp-sass": "5.1.0",
    "sass": "1.57.1"
  }
}

Once the file's been created, you can right click on the file through Visual Studio and choose "Restore Packages"

Create a Task Runner

We're going to compile the sass files during the build process, and to do this we'll create a gulpfile.js that uses the packages defined in our package.json from earlier

const { src, dest } = require('gulp');
const sass = require('gulp-sass')(require('sass'))

exports.default = function () {
    return src('./wwwroot/my-styles.scss')
        .pipe(sass())
        .pipe(dest('./wwwroot/css'));
}

This will take the sccs file that we created earlier, compile it, and then place the output in the wwwroot/css directory

To get it to run during the build, right click the gulpfile from within Visual Studio and choose Task Runner Explorer. A "Tasks" section should show up with "default" option under it. Right clicking on "default" will allow us to choose when the task runs

TaskRunner
⚠️
If you get an error about gulp not being recognized after restoring the packages from the package.json, you may need to run "npm -g install gulp-cli"

Build the Project & Include the css

With the task runner setup, we can now build the project and our sass files will be compiled and placed in the wwwroot/css folder

dotnet build

The last step is to actually include the css in our website. In my case, I created a "Main" template that everything inherits from so I just included the reference there

@using Umbraco.Cms.Web.Common.PublishedModels;
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@{
	Layout = null;
}

<!doctype html>
<html lang="en" class="h-100">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        
        <link rel="stylesheet" href="/css/ktechfarms.css">
        <script src="/lib/bootstrap/js/bootstrap.min.js"></script>
    </head>
 	<body class="d-flex flex-column h-100">
        
        @await Html.PartialAsync("Navigation")
        
        <main class="flex-shrink-0">
            @RenderBody()
        </main>
        
        @await Html.PartialAsync("Footer")

    </body>
</html>

And now, all of my "primary" items use the custom colors

PrimaryButton

Read more