> For the complete documentation index, see [llms.txt](https://api-docs.devhub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.devhub.com/content-resources/themes.md).

# Themes

## Themes

The Themes resource is the primary way our system stores the Site themes that generally control the header, footer and CSS styles that can be reused and assigned to many Sites.

***Warning:** the Themes resource is currently only supported within the Site Builder and internally within the platform. If you are integrating this endpoint be aware that your published themes will be fully backwards compatible, but the specific fields and methods may change in the future.*

## Theme Model

### Theme object

The theme object contains the following fields

| Attribute               | Type      | Description                                                                                                                                                                                                                    |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id                      | integer   | unique id of the theme                                                                                                                                                                                                         |
| active                  | boolean   | Boolean to show this theme to users within the Site Builder                                                                                                                                                                    |
| name                    | string    | Unique slug for the theme. Can only contain lowercase letters, numbers and dashes                                                                                                                                              |
| display\_name           | string    | Theme name that is shown within the Site Builder                                                                                                                                                                               |
| parent\_id              | integer   | ID of the parent theme that this theme is extending                                                                                                                                                                            |
| render\_mode            | string    | The render mode to be used to render this theme. Choices are `legacy` or `mastertheme`                                                                                                                                         |
| extra\_css              | string    | The CSS used to render this theme                                                                                                                                                                                              |
| footer\_code            | string    | Extra HTML to add to all the site/theme pages right before the ending `</body>` tag                                                                                                                                            |
| footer\_template        | object    | HTML content that will be rendered at the bottom of the page body                                                                                                                                                              |
| header\_code            | string    | Extra HTML to add to all the site/theme pages right before the ending `</head>` tag                                                                                                                                            |
| header\_template        | object    | HTML content that will be rendered at the top of the page body                                                                                                                                                                 |
| module\_templates       | list      | List of module templates that can be used to override the default HTML used for rendering of various modules                                                                                                                   |
| theme\_html             | string    | The main wrapper HTML used to render the theme when using the `legacy` theme rendering mode                                                                                                                                    |
| site\_override          | object    | Site override configuration for master themes. Contains a lookup of languages to `site_id` to be used for overriding content. See [site override options for more details](/content-resources/themes.md#site-override-options) |
| site\_override\_objects | list      | List of site elements that should be overridden by the extended Site ID. See [site override options for more details](/content-resources/themes.md#site-override-options)                                                      |
| preview\_url            | string    | Hostname that is used to load the auto-generated thumbnail image used to display the theme in the Site Builder                                                                                                                 |
| added                   | timestamp | Date and time theme was created                                                                                                                                                                                                |
| modified                | timestamp | Date and time theme was modified                                                                                                                                                                                               |
| user\_id                | integer   | Reference id to the User that created this theme                                                                                                                                                                               |

#### Example object:

```javascript
{
  "active":true,
  "added": "2019-04-25T16:14:06",
  "display_name": "Custom Theme",
  "extra_css": "body { background-color: red }",
  "footer_code": "<script type=\"text/javascript\" src=\"...",
  "footer_template": {
    "added": "2019-04-25T16:59:52",
    "content": "<footer>...</footer>",
    "id": 123,
    "modified": "2019-04-25T17:02:17",
    "type": "footer"
  },
  "footer_template_id": 123,
  "header_code": "<link href=\"https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,500,600,700,700i|Montserrat:300,400,500,600,700\" rel=\"stylesheet\">",
  "header_template": {
    "added": "2019-04-25T16:59:52",
    "content": "<header id=\"header\"></header>",
    "id":124,
    "modified": "2019-04-25T17:02:17",
    "type": "header"
  },
  "header_template_id":124,
  "id":11,
  "module_templates": [

  ],
  "name": "custom-api-theme",
  "parent_id": null,
  "preview_url": "example.somedomain.com",
  "render_mode": "legacy",
  "resource_uri": "/api/v2/themes/11/",
  "site_override":{
    "en":174635
  },
  "site_override_objects": [
    "linklists",
    "pages",
    "theme_settings",
    "extra_css",
    "header_code",
    "footer_code",
    "logo_fallback",
    "plugins"
  ],
  "style_css": "/* Blank style */",
  "theme_html": "<!doctype html>\n<html>\n<head>\n  <title>{{ page.title }}</title>\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale = 1.0, maximum-scale=1.0, user-scalable=no\">\n  {% block framework %}\n  {% endblock %}\n  {% include \"themes/header_content.html\" %}\n</head>\n<body>\n\n{% include \"themes/prebody_content.html\" %}\n\n{% if header_template %}\n{{ header_template|safe }}\n{% endif %}\n\n{% include \"themes/layout_content.html\" %}\n\n{% if footer_template %}\n{{ footer_template|safe }}\n{% endif %}\n\n{% include \"themes/footer_content.html\" %}\n\n</body>\n</html>"
}
```

### Site Override Options

These configuration options are use to enable a Theme to override the content of any Site that is assigned that Theme. This is called a "master theme" within our platform and can be used to extend pages, page content, theme settings, plugins, etc from one central `site_id`

#### `site_override`

The below configuration would use the content identified in `site_override_objects` when rendering the site if that site's language is set to `en`

```javascript
"site_override":{
  "en": 174635
}
```

#### `site_override_objects`

The below configuration would denote that most content of the Site should be pulled from the `site_override` Site. This includes pages, the content on those pages, the navigation list (if applicable), and any plugins enabled.

```javascript
"site_override_objects": [
  "linklists",
  "pages",
  "plugins"
]
```

## Create a theme

`POST /api/v2/themes/`

### Required fields

| Attribute     |
| ------------- |
| display\_name |
| theme\_html   |

#### Example request to create a custom theme

```javascript
{
  "active":true,
  "display_name": "Custom Theme",
  "extra_css": "body { background-color: red }",
  "footer_code": "<script type=\"text/javascript\" src=\"https://cdnjs.cloudflare.com/ajax/libs/bootstrap-lightbox/0.7.0/bootstrap-lightbox.min.js\">",
  "footer_template": {
    "content": "<footer>Footer content</footer>"
  },
  "header_code": "<link href=\"https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,500,600,700,700i|Montserrat:300,400,500,600,700\" rel=\"stylesheet\">",
  "header_template": {
    "content": "<header id=\"header\">Header content</header>"
  },
  "render_mode": "legacy",
  "style_css": "/* Blank style */",
  "theme_html": "<!doctype html>\n<html>\n<head>\n  <title>{{ page.title }}</title>\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale = 1.0, maximum-scale=1.0, user-scalable=no\">\n  {% block framework %}\n  {% endblock %}\n  {% include \"themes/header_content.html\" %}\n</head>\n<body>\n\n{% include \"themes/prebody_content.html\" %}\n\n{% if header_template %}\n{{ header_template|safe }}\n{% endif %}\n\n{% include \"themes/layout_content.html\" %}\n\n{% if footer_template %}\n{{ footer_template|safe }}\n{% endif %}\n\n{% include \"themes/footer_content.html\" %}\n\n</body>\n</html>"
}
```

## Updating a theme

`PUT /api/v2/themes/:id/`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://api-docs.devhub.com/content-resources/themes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.