Writing a Confluence Theme
|Level of experience||BEGINNER|
|Atlassian application||CONFLUENCE 4.X+|
On this page:
This tutorial shows you how to create a Confluence custom theme as a plugin. You'll add
colour-scheme modules to your plugin to personalize look and feel. You can replace your organization's hex codes for the example colors used in this tutorial.
Concepts covered in this tutorial:
colour-schememodules to your plugin descriptor
- Using FastDev to reload Confluence with source code changes
You should have a basic understanding of HTML and CSS. You can complete this tutorial successfully even if you've never created a plugin before.
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you have finished, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:
Step 1. Create and prune the plugin skeleton
In this step, you'll create a plugin skeleton using
atlas- commands. Since you won't need some of the files created in the skeleton, you'll also delete them in this step.
- Open a terminal and navigate to your Eclipse workspace directory.
Enter the following command to create a Confluence plugin skeleton:
When prompted, enter the following information to identify your plugin:
Confirm your entries when prompted with
Your terminal notifies you of a successful build:
Change to the project directory created by the previous step.
Delete the test directories.
Setting up testing for your plugin isn't part of this tutorial. Use the following commands to delete the generated test skeleton:
Delete the unneeded Java class files.
- Edit the
Remove the generated
Save and close
Import your project into your IDE
Make your project available to Eclipse.
You'll see a successful build message:
You can open a new terminal window to perform this action.
- Click File > Import.
Eclipse starts the Import wizard.
- Expand the General folder tree to choose Existing Projects into Workspace.
- Click Next.
- Click Browse and enter the root directory of your workspace.
Your Atlassian plugin folder should now appear under Projects.
- Ensure your plugin checkbox is ticked and click Finish.
Eclipse imports your project, and it's now visible in your Package Explorer view.
Step 2. Create a simple theme & update the
When you generated the plugin skeleton, a CSS directory was created automatically under
src/main/resources/css. In this step, you'll add some rudimentary CSS to the file. You'll also declare this CSS resource in the
atlassian-plugin.xml descriptor file. This file describes how your plugin should interact with Confluence.
You'll add the
Theme module to disable Confluence's default theme (
<param name="includeClassicStyles" value="false"/>), and instead include a resource to your custom CSS file. This module uses an existing Confluence class,
BasicTheme, which instructs Confluence to load the theme from your plugin. This module also includes an optional
description field, which are both visible from the Confluence Admin pages.
- In your IDE, navigate to
- Open the
Add the following CSS to the file.
This transforms the normally Atlassian-blue
- Save and close the file.
Add the following
<theme>module before the closing tag of
falseso Confluence ignores backwards-compatible classic themes.
The paths to resources you add here are to Confluence directories, not your plugin: You'll add your resource in the next step.
Add your CSS file as a resource inside the
- Save the file.
Update your project changes.
In this step we use Eclipse. You'll want to use the equivalent command for your IDE from the project root.
Here's what the descriptor file should look like up to this point:
Step 3. Build, install, and run your plugin
In this step you'll install your plugin and run Confluence. You'll activate your Simple Theme and verify your CSS changes.
Open a terminal window and navigate to the plugin root folder.
Start up Confluence from your project root using the
This command builds your plugin code, starts a Confluence instance, and installs your plugin. This may take a few minutes.
Locate the URL for Confluence.
Your terminal outputs the location of your local Confluence instance, defaulted to http://localhost:1990/confluence.
- Open your browser and navigate to your local Confluence instance.
- Login with
- Click the Cog icon from the navigation bar, and choose Confluence Admin.
The administration console loads.
- Click Themes from the left-hand sidebar, under Look & Feel.
The Site Theme page loads, with your custom-created "Simple Theme" listed as an option. Note the title and descriptive text match what you entered.
- Choose the radio button for Simple Theme and click Confirm.
The page reloads, with no changes apparent: the changes you made don't effect the admin page.
- Click the Confluence logo from the upper left corner to return to the main dashboard.
Your CSS is installed! All spaces, save the admin console, will have this navigation color scheme now.
Step 4. Add a
colour-scheme module to the descriptor file
Black is classic, but in this step you'll use a sophisticated
colour-scheme module to your descriptor file. Right now, your plugin is pretty basic – it's a theme that just turns the header black. Here, you'll expand your theme to add multiple colors and layouts, and use FastDev to reload the changes in Confluence.
After the closing
</theme>tag and before the closing
</atlassian-plugin> tag, add the following to your file.
This creates an earthy theme with a white background, with different links, text colors, and other attributes.
Now, tie your
colour-schememodule to your
Add the following code before the closing
</theme>tag to include it in the resources.
- Save and close the file.
Update your project changes.
If using Eclipse, issue the following command from your project root:
Expand the toolbar on the bottom of the Confluence page, and click SHIFT+RELOAD or Run Fast Dev .
After FastDev completes, you should see the changes applied.
This is what your
atlassian-plugin.xml descriptor file should resemble at this point:
You've changed the look and feel of your Confluence instance. For a more customized workspace in Confluence, you might consider customizing layouts of your Confluence spaces.