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.
  • CA Technologies – CA Technologies' theme includes selectors for switching languages and versions. They also give users the ability to add comments on any page for easy feedback.
  • Igel – The unique theme Igel created really brings their brand together.
  • K15t – We use Scroll Viewport too! We collaborated with our entire team to create our site content in Confluence and developed our custom theme using Scroll Viewport.

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 tools > Apps 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'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.

    - Edit a theme that's global without Confluence administrator permissions.

    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.

Gulp Viewport Plugin

You can use the Gulp Viewport plugin or the Viewport Developer tools to make theme creation a much faster process. This is useful, when developing a Scroll Viewport theme in a local IDE. In this case, a Gulp 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.