Skip to main content
Skip table of contents

Get Started with Theme Development

For teams looking to build a totally custom website, you can build a completely custom theme with the Velocity templating engine using HTML, CSS, and JavaScript.

 By developing a completely unique theme, you can create any kind of website, intranet, blog, or whatever you can imagine.

Here are just a few examples of custom themes created with Scroll Viewport:

  • Atlassian – Atlassian uses multiples spaces to separate documentation for each product with awesome search so you can quickly find what you're looking for.
  • BMC – BMC uses expand macros and clear content overviews to quickly answer questions.
  • Igel – The unique theme Igel created really brings their brand together.

    To quickly create and customize a help center without writing code, we recommend the The Help Center Theme.

Edit a Theme to Get Started

  1. In the space where you want to develop a custom theme, choose Space toolsApps from the bottom of the sidebar.
  2. Choose Scroll Viewport.
  3. Create a viewport or choose Configure on an existing viewport.
  4. On the Theme tab, choose ... on a theme and choose Edit.

    Is 'Edit' unavailable?

    This may be because you do not have  Confluence administrator  permissions or you're trying to edit a theme bundled with Scroll Viewport, or a theme that was  installed as an add-on. It's not possible to edit these themes – just copy the theme and edit the new copy. Keep in mind that you can't develop a custom theme based on the  The Help Center Theme.

    As a space administrator you can always customise the The Help Center Theme, or even edit themes to full extent, if your Confluence administrators extends the theme editing permissions to you.

    Now, you can edit the theme using the built-in theme editor:

Theme Creation Basics

In the editor you can create and modify Velocity templates, CSS, JS and other files. To upload a file, click Select files. Please note:

  • Remember to reference any CSS, JS files in your templates such as described in the Referencing JS/CSS and Image Files page.
  • Scroll Viewport only supports Velocity 1.6 code in templates. Using Velocity 1.7 code can cause your templates to not work as expected.

Themes must contain at least a page.vm, and you can also add other template types:

Template location and name

Description

Relevant content types

Example

/page.vm

Renders a page.

PAGE

Add page templates

/blog.vm

Renders a blog post.

BLOG_POST

Add blog templates 

/blogs.vm

Renders the blog post overview.

BLOG_POST

Add blog templates

/error.vm

Renders errors, such as 404 (Not found) or 403 (No Permission).

You define additional error templates handle specific errors. For example error404.vm will be used to render 404 errors.

both

Add error templates

/search.vm

Renders search results, that are accessed with <viewport-url>/search?q=<search-terms>

both

Search Template Recipe

For more information about templates, please check the template contexts available to you.

Using the Theme Editor

Scroll Viewport's theme editor provides some features that help you editing themes.

Placeholders

The theme editor will recommend any available placeholders.

Code assistant

The editor provides code completion for properties in CSS files and for HTML tags and template placeholders in Velocity markup files (*.vm).

To open the code assistant, press Ctrl-Space. The code assistant is also opened automatically whenever you enter a dollar sign ($) in a vm file.

Download a theme as a file

You can use the editor to download a theme as a JAR file by clicking Actions > Download Theme.

You can then install the theme on other Confluence instances as an add-on.

Configurable Themes

If you only want some file(s) from your theme to be edited by others you can define your theme as a configurable theme.

Viewport Developer tools

You can use our Viewport Developer tools to make theme creation and development a much faster process. This is useful, when developing a Scroll Viewport theme in a local IDE. In this case, a yarn file can watch the resources, automatically upload the resources to Scroll Viewport, and even have BrowserSync to sync the browser.

REST API

Even though we provide a lot of information through the Placeholders API, it comes handy to know the Confluence REST API. There are several examples of usage in the Template Recipes section of the Viewport guides. Like described in the "Like button" recipe.

Depending on the version of your Confluence installation, you can browse the latest API in the Confluence docs. Additionally, you can choose your version.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.