Tweaking Confluence Macros in Zendesk

This page guides you through the process of getting specific macros from Confluence Cloud synced to your Zendesk.

General Note about Macro Support
Some Confluence macros are supported out of the box, some need tweaks (as defined in this guide), and some are not supported due to technical limitations with either Zendesk or Confluence Cloud.

The following is a list of macros that need tweaking. These tweaks are defined in below.

Table of Contents Macro
Excerpt Include Macro
Expand Macro
Info, Tip, Warning, Note, Panel Macro
Code Block Macro

If you're using a macro that is not in the list above but is critical to your business to be synced:
Let us know, we'd be happy to look into supporting it!

Table of Contents Macro

If you only care about the table of contents' text content (ie the list of links) there is no additional work to be done. 🎉

The Table of Contents macro can produce link lists with inconsistent paddings and margins in Zendesk. Complete the process below to standardize the appearance of this macro:

Open your Zendesk Guide Appearance Editor.
You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
Edit the CSS
See Zendesk's documentation on how to navigate to their CSS editor

Paste the following CSS snippet at the bottom of your CSS
By default, this is the style.css file

.toc-macro {
  padding: 0;
  font-size: 14px; /* optional */
}
.toc-macro ul {
  list-style: disc; /* disc|square|circle */
  margin-left: 0px;
}
.toc-macro li {
  margin-left: 0px;
  padding-left: 0px;
}
.toc-macro .toc-indentation {
  margin-top: 0;
}
.toc-macro span.TOCOutline {
  padding-right: 5px;
}

Click Save
After clicking the button it will show you a message "You have unpublished changes"
Click Publish changes
The styles in your Zendesk Guide are now updated and the Table of Contents should appear consistently
Celebrate 🎉

Limitations

Custom indentations configured in Confluence cannot be synced
Custom list style types configured in Confluence cannot be synced

Custom indentations or custom list style types can be configured in your Zendesk Guide CSS, but the same settings will apply to all synced ToC macros.

Excerpt Include Macro

The Excerpt Include macro comes in two forms:

Excerpt text only
This is the case if you tick the "Remove surrounding panel" checkbox
Excerpt text with page info
This is the default behavior of Excerpt Include.

For the latter you'll need to add custom style classes to your Zendesk Guide theme in order to display pages including a Excerpt Include macro correctly:

Open your Zendesk Guide Appearance Editor.
You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
Edit the CSS
See Zendesk's documentation on how to navigate to their CSS editor

Paste the following CSS snippet at the bottom of your CSS
By default, this is the style.css file

.panel {
  color: #333;
  padding: 0;
  margin: 10px 0;
  border: 1px solid #cccccc;
  overflow: hidden;
  border-radius: 3px;
  line-height: 20px;
}
.panel > .panelHeader {
  border-bottom: 1px solid #cccccc;
  background-color: #f7f7f7;
  padding: 10px;
}
.panel > .panelContent {
  padding: 10px;
}

Click Save
After clicking the button it will show you a message "You have unpublished changes"
Click Publish changes
The styles in your Zendesk Guide are now updated and the Excerpt Include macro should appear consistently
Celebrate 🎉

If you'd like to customize the excerpt panel styles to integrate better with your Zendesk Guide theme you can do so by tweaking the 3 CSS classes listed.

Expand Macro

Open your Zendesk Guide Appearance Editor.
You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
Edit the CSS
See Zendesk's documentation on how to navigate to their CSS editor

Paste the following CSS snippet at the bottom of your CSS
By default, this is the style.css file

div.expand-control {
  cursor: pointer;
  text-decoration: none;
  margin-bottom: 10px;
}
span.expand-control-icon {
  background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAQAAAC1+jfqAAAALElEQVQoz2NgGGSg4EzBTPwKOgr+F6ThVzKTsJK7Bf/JN4GgG4C+6GAYigAASNYUTGaVYwsAAAAASUVORK5CYII=);
}
span.expand-control-icon.expanded {
  background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAQAAAC1+jfqAAAAMUlEQVQoz2NgGGag4ExBB5TVUXAGm4KOgv8FM4H0TAiNTUkaUOouEKfhtiYNr/SQBQAsPRRMJnnlygAAAABJRU5ErkJggg==);
}
span.expand-control-icon > img {
  visibility: hidden;
}
span.expand-control-text {
  color: #3572b0;
  text-decoration: none;
}
span.expand-control-text:hover {
  text-decoration: underline;
}
div.expand-content {
  height: 0;
  opacity: 0;
  overflow: hidden;
}
div.expand-content.expanded {
  margin: 0 0 10px 20px;
  opacity: 1;
  transition: opacity .5s;
  height: auto;
  overflow: visible;
}

Edit the JS
See Zendesk's documentation on how to navigate to their JS editor

Paste the following JS snippet at the bottom of your JS file right before "});"
By default, this is the script.js file

$('.expand-control').click(function() {
  $(this).parent().find('.expand-content').toggleClass('expanded');
  $(this).find('.expand-control-icon').toggleClass('expanded');
});

Info, Tip, Warning, Note, Panel Macro

The message box macros require additional styling to display correctly. There are two strategies:

Use Zendesk styles
This approach uses Zendesk's message styles to display message boxes from Confluence.
Move Confluence styles to Zendesk
This approach uses Confluence's message styles to display message boxes in Zendesk.
It also requires to add an icon font (ie Font Awesome) to display message icons.

Option 1: Use Zendesk Styles

Complete the process below to get Zendesk styles for message boxes in Zendesk:

Open your Zendesk Guide Appearance Editor.
You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
Edit the CSS
See Zendesk's documentation on how to navigate to their CSS editor

Paste the following CSS snippet at the bottom of your CSS
By default, this is the style.css file

.confluence-information-macro {
  padding: 10px;
  margin-left: 0px;
  margin-right: 15px;
  margin-top: 15px;
  margin-bottom: 15px;
  color: #03363d;
}
.confluence-information-macro p {
  margin: 0;
}
.confluence-information-macro > p.title {
  display: inline;
  margin-right: 5px;
  font-weight: bold;
}
.confluence-information-macro > .confluence-information-macro-body {
  display: inline-block;
}
.confluence-information-macro > .confluence-information-macro-icon {
  display: none;
}
.confluence-information-macro-note {
  background-color: #fbf2d0;
}
.confluence-information-macro-tip {
  background-color: #def1f4;
}
.confluence-information-macro-information {
  background-color: #fbf2d0;
}
.confluence-information-macro-warning {
  background-color: #FFDED9;
}

/* panel */
.panel {
  color: #333;
  padding: 0;
  margin: 10px 0;
  border: 1px solid #cccccc;
  overflow: hidden;
  border-radius: 3px;
  line-height: 20px;
}
.panel p {
  margin: 0;
}
.panel > .panelHeader {
  border-bottom: 1px solid #cccccc;
  background-color: #f7f7f7;
  padding: 10px;
}
.panel > .panelContent {
  padding: 10px;
}

Click Save
After clicking the button it will show you a message "You have unpublished changes"
Click Publish changes
The styles in your Zendesk Guide are now updated and the Confluence message box macros should appear in Zendesk message styles
Celebrate 🎉

Option 2: Move Confluence Styles to Zendesk Guide

Complete the process below to get Confluence-like styles for message boxes in Zendesk:

Open your Zendesk Guide Appearance Editor.
You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
Edit the document head

Paste the following HTML snippet at the bottom of your document head
It adds Font Awesome 5 to your Zendesk Guide to display message icons

<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.0.8/css/solid.css" integrity="sha384-v2Tw72dyUXeU3y4aM2Y0tBJQkGfplr39mxZqlTBDUZAb9BGoC40+rdFCG0m10lXk" crossorigin="anonymous">
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.0.8/css/fontawesome.css" integrity="sha384-q3jl8XQu1OpdLgGFvNRnPdj5VIlCvgsDQTQB6owSOHWlAurxul7f+JpUOVdAiJ5P" crossorigin="anonymous">

Edit the CSS
See Zendesk's documentation on how to navigate to their CSS editor

Paste the following CSS snippet at the bottom of your CSS
By default, this is the style.css file

.confluence-information-macro {
  background: #fcfcfc;
  border: 1px solid #ccc;
  border-radius: 5px;
  color: #333;
  margin: 10px 0 1em 0;
  min-height: 20px;
  padding: 10px 10px 10px 36px;
  position: relative;
}
.confluence-information-macro p, .panel p {
  margin: 0;
}
.confluence-information-macro.has-no-icon {
  padding-left: 10px
}
.confluence-information-macro:first-child {
  margin-top: 0;
}
.confluence-information-macro-warning {
  background: #fff8f7;
  border-color: #d04437;
}
.confluence-information-macro-information {
  background-color: #fcfcfc;
  border-color: #aab8c6;
}
.confluence-information-macro-tip {
  background-color: #f3f9f4;
  border-color: #91c89c;
}
.confluence-information-macro-note {
  background: #fffdf6;
  border-color: #ffeaae;
}
.confluence-information-macro > .title {
  font-weight: bold;
}
.confluence-information-macro > .title >strong {
  font-weight: inherit;
}
.confluence-information-macro .confluence-information-macro-icon {
  display: block;
  left: 10px;
  line-height: 20px;
  position: absolute;
  top: 12px;
  vertical-align: text-bottom;
}
.confluence-information-macro .confluence-information-macro-icon.aui-iconfont-info:before {
  font-family: Font Awesome\ 5 Free;
  content: "\f05a";
  color: #4a6785;
}
.confluence-information-macro .confluence-information-macro-icon.aui-iconfont-error:before {
  font-family: Font Awesome\ 5 Free;
  content: "\f06a";
  color: #cf4336;
}
.confluence-information-macro .confluence-information-macro-icon.aui-iconfont-approve:before {
  font-family: Font Awesome\ 5 Free;
  content: "\f058";
  color: #14892c;
}
.confluence-information-macro .confluence-information-macro-icon.aui-iconfont-warning:before {
  font-family: Font Awesome\ 5 Free;
  content: "\f071";
  color: #594300;
}
.confluence-information-macro>.confluence-information-macro-body>p:empty {
  display:none;
}

.panel {
  color: #333;
  padding: 0;
  margin: 10px 0;
  border: 1px solid #cccccc;
  overflow: hidden;
  border-radius: 3px;
  line-height: 20px;
}
.panel p {
  margin: 0;
}
.panel > .panelHeader {
  border-bottom: 1px solid #cccccc;
  background-color: #f7f7f7;
  padding: 10px;
}
.panel > .panelContent {
  padding: 10px;
}

Click Save
After clicking the button it will show you a message "You have unpublished changes"
Click Publish changes
The styles in your Zendesk Guide are now updated and the message box macros should appear in Confluence's message styles
Celebrate 🎉

Code Block Macro

If you only care about the text content of this macro there is no additional work to be done. 🎉

In order to highlight code syntax in Zendesk Guide a third party JavaScript library called SyntaxHighlighter is required. Complete the following process to get your code block macro content highlighted correctly:

Open your Zendesk Guide Appearance Editor.
You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
Edit the "Document head"

Paste the following HTML snippet at the bottom of your document head
It includes the necessary scripts and styles for the SyntaxHighlighter library

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/SyntaxHighlighter/3.0.83/styles/shCore.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/SyntaxHighlighter/3.0.83/styles/shThemeDefault.css" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/SyntaxHighlighter/3.0.83/scripts/shCore.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/SyntaxHighlighter/3.0.83/scripts/shAutoloader.js"></script>

Edit the JS
See Zendesk's documentation on how to navigate to their JS editor

Paste the following JS snippet at the bottom of your JS file right before "});"
It makes sure the correct syntax highlighting scripts are used and initializes the highlighter.

var brushCdnBaseUrl = 'https://cdnjs.cloudflare.com/ajax/libs/SyntaxHighlighter/3.0.83/scripts/';
SyntaxHighlighter.autoloader(
  ['xml', brushCdnBaseUrl + 'shBrushXml.js'],
  ['java', brushCdnBaseUrl + 'shBrushJava.js'],
  ['js', 'jscript','javascript',  brushCdnBaseUrl + 'shBrushJScript.js'],
  ['css', brushCdnBaseUrl + 'shBrushCss.js'],
  ['cpp', brushCdnBaseUrl + 'shBrushCpp.js'],
  ['bash', 'shell', brushCdnBaseUrl + 'shBrushBash.js'],
  ['sql', brushCdnBaseUrl + 'shBrushSql.js'],
  ['actionscript3', 'as3', brushCdnBaseUrl + 'shBrushAS3.js'],
  ['applescript', brushCdnBaseUrl + 'shBrushAppleScript.js'],
  ['c#', 'csharp', brushCdnBaseUrl + 'shBrushCSharp.js'],
  ['coldfusion', brushCdnBaseUrl + 'shBrushColdFusion.js'],
  ['delphi', brushCdnBaseUrl + 'shBrushDelphi.js'],
  ['diff', brushCdnBaseUrl + 'shBrushDiff.js'],
  ['erlang', brushCdnBaseUrl + 'shBrushErlang.js'],
  ['groovy', brushCdnBaseUrl + 'shBrushGroovy.js'],
  ['jfx', brushCdnBaseUrl + 'shBrushJavaFX.js'],
  ['php', brushCdnBaseUrl + 'shBrushPhp.js'],
  ['perl', brushCdnBaseUrl + 'shBrushPerl.js'],
  ['text', brushCdnBaseUrl + 'shBrushPlain.js'],
  ['powershell', brushCdnBaseUrl + 'shBrushPowerShell.js'],
  ['py', brushCdnBaseUrl + 'shBrushPython.js'],
  ['ruby', brushCdnBaseUrl + 'shBrushRuby.js'],
  ['sass', brushCdnBaseUrl + 'shBrushSass.js'],
  ['scala', brushCdnBaseUrl + 'shBrushScala.js'],
  ['vb', brushCdnBaseUrl + 'shBrushVb.js']
);
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();

Click Save
After clicking the button it will show you a message "You have unpublished changes"
Click Publish changes
The document header and scripts in your Zendesk Guide are now updated and the Code Block macro should highlight your synced code
Celebrate 🎉

Tweaking Confluence Macros in Zendesk

Table of Contents Macro

Excerpt Include Macro

Expand Macro

Info, Tip, Warning, Note, Panel Macro

Option 1: Use Zendesk Styles

Option 2: Move Confluence Styles to Zendesk Guide

Code Block Macro

Anchor Macro

General Limitations