So I’ve finally gotten the time to sit down and get started on this guide. Not a lot of custom themes have been made so far, with a lot of our energies lately been focused on the plugin system (as well as the soft-launch of our hosting platform). A lot of inspiration has come from Convoe… at this point, he probably knows the theming system better than I do. The last theme I made was about a month ago for One Hundred Free Books and since then I haven’t really gotten a chance to play around. So here goes, I hope this is useful to someone and would love to see one or two great themes come out as a result of this!

Lavender Theme for NodeBB

As usual, if reading isn’t really your thing just hop over to the theme’s repository and start tinkering away :)

Click through to proceed to part 1 of this guide. :)

---

Beginner’s Note: Use supervisor to detect changes and automatically restart NodeBB

Getting Started

First lets create a new repository for our theme, we’ll call it nodebb-theme-lavender (Yes, all official NodeBB themes will be named after towns in a certain game you’ve all played. And this one is going to be purple). Place this folder in your node_modules folder. We’ll create a theme.json file in our theme directory that will look something like this:

node_modules/nodebb-theme-lavender/theme.json

{
    "id": "nodebb-theme-lavender",
    "name": "Lavender Theme for NodeBB",
    "description": "A simple theme for NodeBB. Check out the theming guide that accompanies this work at https://burnaftercompiling.com",
    "url": "https://www.github.com/psychobunny/nodebb-theme-lavender",
    "screenshot": null,
    "templates": "templates",
    "staticDir": "static"
}

We’ll create three folders in that directory, less, static, and templates. For this theme, we’re going to loosely base it off the vanilla theme. So first order of business is to create a theme.less file in the root directory (this is the main less file that NodeBB looks for) that includes the theme.less file from the vanilla theme. You could skip this step if you’re planning on creating a brand new theme from scratch.

node_modules/nodebb-theme-lavender/theme.less

@import "../nodebb-theme-vanilla/less/vanilla";
@import "../nodebb-theme-vanilla/modules";
@import "./less/style";

Create a blank less/style.less file and we’re good to go. Head over to the themes section in the Admin Control Panel and activate your theme. You will have to restart your server at this point for the changes to take affect. (NB: Unlike plugins, if you update theme.json you’ll need to reactivate it in the ACP. We’ll fix this before 0.3.x). Voila! Congratulations….. nothing should have changed (this is a good thing). This is because we’re importing the vanilla less files and haven’t actually overridden any templates yet.

progress! *insert golf-clap.gif*

If you ran into any trouble, make sure your theme directory looks exactly like it does at this commit here.

Custom Templates

When you navigate around NodeBB, the template system lazy-loads templates from the server. So if you navigated to /category, it will attempt to load category.tpl first from your custom theme directory (the only major file that breaks this rule is home.tpl for /). Failing to find a custom template, it will revert to loading the default file found at public/templates/category.tpl.

Creating a custom template is as easy as dropping the replacement into your defined custom template directory. Start with copying header.tpl straight from the default public/templates/header.tpl into our custom templates directory.

Let’s verify that we’ve successfully overridden the customized header.tpl. Locate the <navbar> and replace its navbar-inverse class with navbar-default. You should get something that looks like this:

starting to get somewhere…

(Stuck? Your theme’s code should look exactly like it does at this commit)

Importing and Overriding Bootstrap

Alright now for the fun part, we’ll copy over BS3′s less files (direct link) into a less/bootstrap folder. In our style.less, import all the BS files like so:

@import "./bootstrap/bootstrap";

And now we’re ready to start overriding Bootstrap. If you like, you could make changes straight into the BS less files. The problem is that it makes life a bit harder when keeping up to date with newer versions of BS. So I’d recommend the only file you change in there is less/bootstrap/bootstrap.less. I went in and changed the variables.less file to point to a custom variables.less file:

@import "../variables.less";

You could copy and paste the original contents into that file and start modifying from there :) I don’t intend on turning this tutorial into a “How to create a Bootstrap theme” (there are plenty of resources available on the internet), so I’m going to cheat a bit and fast forward here. I used a variables.less from an open source BS theme called “White Plum” by divshot. Had to modify it a bit to not break with 3.0.3 but you get the picture. Head on over to the repository at this commit to find out how it looks!

heh, bet you didn’t notice I reused this screenshot

That’s a wrap.

Okay I hope that Part 1 was useful for you. As I continue working on the Lavender theme I’ll be writing notes on what to include in future tutorials. Keep an eye out on that repository, I might be experimenting around with it and trying crazy things with it that might be useful to you. In later parts to this guide, I’ll definitely cover more advanced tasks like custom modules (ex. the composer or chat window), and augmenting the plugin system to keep your theme modular and easy to update.

If you ran into any issues or would like me to cover something specific, feel free to drop by our community site or hit me up on @o9k. Good luck!