Extending Carbon Theme

This example shows how to extend a template in Carbon with custom HTML and CSS.

Say you want to add some additional css, place this file in your project (you can choose any name) at /static/custom.css:

div {
  background-color: red;
}

The file carbon/templates/index.html is the root HTML file, which all pages like carbon/templates/page.html inherit from.

This file imports all CSS for the website. This is an excerpt from the carbon/templates/index.html:

<head>
  <!-- ... content exclude ... -->
  <script src="/code_blocks.js" type="text/javascript" defer></script>
  <script src="/theme_toggle.js" type="text/javascript" defer></script>

  <!-- Allow adding custom elements to the <head> -->
  {% block extra_head %}
  {% endblock extra_head %}
</head>

The block extra_head allows you to trivially customize the index.html file. In your project, create /template/index.html with the following contents:

{% extends "carbon/templates/index.html" %}

{% block extra_head %}
  <link
    rel="stylesheet"
    href="{{ get_url(path='custom.css', cachebust=true)} }"
  />
{% endblock extra_head %}

The above will essentially copy all of the code from carbon/templates/index.html and put it into your own /templates/index.html but with an extension, namely it will import your /static/custom.css file.

Your /templates/index.html is now the source of truth.

You can take a look at other templates in carbon/templates/*.html. All of them can be extended in similar ways.

Specifically, all the templates {% extends "carbon/templates/index.html" %} so usually you will want to do the same.

Everywhere you see a {% block %} ... {% endblock %}, you can extend it without having to override the rest of the page!

Custom theme

Similarly, you can override any of the static assets. Carbon uses the carbon/static/carbon/theme.css file for all the colors:

[data-theme="light"] {
  --foreground: #222222;
  --background: #eeeeee;
  --background2: #f4f4f4;
  --secondary: #808080;
  --tertiary: #dddddd;
  --link: #010101;
  --table-border: #d0d0d0;
  --table-row: #f7f7f7;
  --accent: #418001;
  /* same as --accent but hue is 215 */
  --blue: #013680;
  /* same as --accent but hue is 281 */
  --purple: #580180;
  /* same as --accent but hue is 4 */
  --red: #800901;
  /* same as --accent but hue is 138 */
  --green: #018027;
  /* same as --accent but hue is 59 */
  --yellow: #7e7801;
  /* same as --accent but hue is 180 */
  --cyan: #018080;
}

[data-theme="dark"] {
  --foreground: #dddddd;
  --background: #161616;
  --background2: #131313;
  --secondary: #999999;
  --tertiary: #444444;
  --link: #fefefe;
  --table-border: #444444;
  --table-row: #1e1e1e;
  --accent: #cbefa6;
  /* same as --accent but hue is 215 */
  --blue: #a4c3ef;
  /* same as --accent but hue is 281 */
  --purple: #d7a4ef;
  /* same as --accent but hue is 4 */
  --red: #efa9a4;
  /* same as --accent but hue is 138 */
  --green: #a4efba;
  /* same as --accent but hue is 57 */
  --yellow: #efeba4;
  /* same as --accent but hue is 180 */
  --cyan: #a4efef;
}

You can place the file in your own website at /static/css/theme.css and Carbon’s file will be overwritten by your file.

Relevant Zola documentation: