Creating a custom website theme in NationBuilder is easy to learn, and these docs cover all the essentials on how to get started. You can customize any element of your website and have access to all the objects and variables that make NationBuilder so powerful. NationBuilder extends HTML with the Liquid template language, and extends CSS with SASS. All that means is you can use regular HTML and CSS, but you also get some cool plugins, variables, and logic in both.

Table of contents

• Create a new theme
• The theme template page
• Theme vs. page level editing
• The stylesheet
• How the website templates work together
• Uploading images, jQuery or other assets
• Image sliders
• Fonts
• Display content from one page on another page
• Display content from pages with a certain tag on another page
• Keeping donation pages secure
• More Liquid & Theme Resources

---

Create a new theme

To create a custom website theme, sign in to your nation's control panel and click Websites > Theme. This will display thumbnails of all public themes. 

Clicking a thumbnail instantly changes the way your website looks. It also reveals several theme style variations for you to choose from which offer different colors combinations, fonts and so on.

To customize your website beyond these choices, you need to create a custom theme. To do this, click New custom theme.

Give your theme a name and leave Clone your current theme and Switch site to your new site immediately checked. Then click Create theme. 

---

The theme templates page

When the theme is done cloning, you will land on the templates page of your new custom theme:

Some important files to note are:

• theme.scss is the stylesheet which controls the overall look of your website. 
• layout.html wraps every page and includes your header and footer.
• _columns_1.html wraps the main content area of a page when the sidebar is turned off.
• _columns_2.html wraps the main content area of a page when the sidebar is turned on.
• splash.html wraps your splash page, if you have one enabled.

Listed below these files are templates for every type of page you can create in NationBuilder. Key points to understand about these templates are:

• Changes made to a template here will modify every page of that type across your website. For example, modifying pages_show_blog_post.html will modify all blog posts pages. If you wish to modify a template for a specific page only, click Website, select the page you wish to edit, then click Template.
• Templates ending in _wide.html will be shown when the sidebar is turned off on a page. 

---

Theme vs. page level editing

Theme level editing: There are two levels of editing your theme -- theme level editing and page level editing. Theme level describes editing entire page types across your entire website. Any template edited on the themes template page accessed from Website > Theme is theme level editing.

Page level editing: Page level editing is when you only want to style one specific page. Select the page you want to edit from Website and then Template. Modifying the this template will override the theme level template and only affect this page. The Files page which exists under each page is where you should upload images or assets used for that page only. 

---

The stylesheet

Two of the most powerful features of Sass are variables and mixins. Let's take a quick look at how both work:

Variables:

Sass variables begin with a dollar sign and are followed by a value. Variables allow you to easily produce the same properties throughout your stylesheet. Mixins:

Mixins are one of the most powerful Sass features. They allow re-use of styles – properties or even selectors – without having to copy and paste them or move them into a non-semantic class.

For example, let's say you want rounder corners on a background element. Instead of typing out the border-radius property for all the different browsers, you can just use the border-radius mixin like so:

Now let's take a look at theme.scss. You open the file by clicking the filename theme.scss:

In the image above we see a color palette is defined by setting 6 color variables. This means you only need to figure out the color hex values once, and then you can easily reuse the same colors over and over again in your stylesheet.

If you scroll to the bottom of theme.scss, you'll notice there are no styles at all. Instead, you will see @import "filename". This is because all the styles are being imported from the theme you cloned. So if you cloned the Resolve theme, you will see @import "resolve";. If you click Default (located just above the template editor), you will be able to see the contents of the stylesheets being imported, including the Resolve stylesheet.

The easiest way to manipulate the way elements look on your website is to override these default styles. Using Inspect Element in Chrome and Safari or Firebug in Firefox is the easiest way to reveal which styles are controlling various areas on a given page.

For example, let's say you want to remove the white frame around your logo. First, right click on that area of the page and click Inspect Element. This will reveal the class or id name and attributes. 

You can see Inspect Element revealed the img tag, and on the right you can see that #header_pic needs to be modified in theme.scss to get rid of the border. Next, open theme.scss and make the following change:

Now click Save and publish. That's it -- the border on the logo is gone. Apply this same approach to anything you want to change on your site.

---

How the website templates work together

Let's take a quick look at how the website templates work by clicking on layout.html.

Layout.html is what wraps every page and includes your header and footer. Inside you'll find:

• {{ content_for_header }} loads a critical chunk of code required for your NationBuilder website to function properly. For example, it automatically loads jQuery and relevant meta data. Never remove this.
• {% include "nav" %}  includes the _nav.html file, which contains all the code for your top nav. You will find your _nav.html file on your theme template page if you wish to edit it.
• {% if request.is_sidebar? %} checks to see if the sidebar is enabled on the page being loaded or not. The sidebar can be turned on or off under settings when editing any page. You will notice if the side bar is turned on, then _columns_2.html is shown, and if it's turned off, _columns_1.html is shown.
• {{ content_for_footer }} loads a second batch of critical code required for your NationBuilder website to function properly, such as various jQuery scripts. Never remove this.

_columns_2.html wraps the main content area of a page when the sidebar is turned on. Inside you'll find:

• {{ content_for_notifications }} displays various notification messages, such as when a form is successfully submitted.
• {% yield %} loads the template for the type of page being loaded. For example, if a calendar page is being loaded, the _pages_show_calendar.html template will be loaded here.
• {% if request.logged_in? %} checks to see if the user loading the page is logged in. If they are, it loads _supporter_nav.html in the sidebar. If they aren't, it loads the rest of code in this template in the sidebar. If you want to change what is in the right column when someone is logged in, edit _supporter_nav.html.

---

Uploading images, jQuery or other assets

All images or assets used for your overall theme should be uploaded to Website > Theme > Files.

When referencing images or assets in your theme templates, simply refer to them by the file name. No path is necessary. So if you upload header.jpg, refer to it like this: <img src="header.jpg"" />.

It's easy to install any jQuery script you want. From the theme templates page, click Files > Upload Files to upload all the script files. Next, click Templates > layout.html. Scroll to the bottom of the file and reference the script files somewhere above the </body> tag.

Depending on the installation instructions for the jQuery script you're using, you may need to add additional stylesheets or javascript. If so, the same method applies.

Reference images, stylesheets, and javascript files using just the file name, not the full URL.

This applies everywhere:

• Images in SCSS or CSS files
• Images in img tags:
• Images in CSS tags:
• Images in inline CSS attributes:
• SCSS or CSS files linked in the header:
• Javascript files linked in the header:

If you need to link to an absolute URL, upload the file, then right click on it and choose "Copy Link Address". That link will look something like this: https://nationslug.nationbuilder.com/assets/pages/1/filename.jpg.

If you are referencing an image or file within a <script> tag, upload the file to Website > Theme > Files and use the following code:

---

Image sliders

NationBuilder has a great image slider already built in. We call it a Featured content slider and you can add one to any page. Select a page you want to add it to from Website and click Featured content sliders.

Simply create a label, headline and select a page to link to and then choose the image and click Save featured content slider. Repeat this process until all images you wish to use have been uploaded. You can rearrange the order of the images by drag and dropping the list on the right. 

---

Fonts

Typekit

Because NationBuilder uses TypeKit, you can easily use the following high quality fonts on your website by using the font-family values below.

Please note that because Typekit restricts access to a specific domain, you will need to create your own own kit if you set up a custom domain. Learn more about registering with Typekit here.

Chunk by Ms. Meredith Mandel.

font-family: "chunk-1","chunk-2"

Lobster by Pablo Impallari.

font-family: "lobster-1","lobster-2"

Museo Sans by exljbris Font Foundry.

font-family: "museo-sans-1","museo-sans-2"

Myriad Pro by Adobe.

font-family: "myriad-pro-1","myriad-pro-2"

Museo by exljbris Font Foundry.

font-family: "museo-1","museo-2"