Tweaking Confluence Macros in Zendesk


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

The following is a list of macros that need tweaking. These tweaks are defined in below. 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:

  1. Open your Zendesk Guide Appearance Editor.
    You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
  2. Edit the CSS
    See Zendesk's documentation on how to navigate to their CSS editor
  3. 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;
    }
  4. Click Save
    After clicking the button it will show you a message "You have unpublished changes"
  5. Click Publish changes
    The styles in your Zendesk Guide are now updated and the Table of Contents should appear consistently
  6. Celebrate 🎉
Limitations
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:

  1. Excerpt text only
    This is the case if you tick the "Remove surrounding panel" checkbox
  2. 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:

  1. Open your Zendesk Guide Appearance Editor.
    You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
  2. Edit the CSS
    See Zendesk's documentation on how to navigate to their CSS editor
  3. 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;
    }
  4. Click Save
    After clicking the button it will show you a message "You have unpublished changes"
  5. Click Publish changes
    The styles in your Zendesk Guide are now updated and the Excerpt Include macro should appear consistently
  6. 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

  1. Open your Zendesk Guide Appearance Editor.
    You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
  2. Edit the CSS
    See Zendesk's documentation on how to navigate to their CSS editor
  3. 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;
    }
  4. Edit the JS
    See Zendesk's documentation on how to navigate to their JS editor
  5. 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:

  1. Use Zendesk styles
    This approach uses Zendesk's message styles to display message boxes from Confluence.
  2. 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:

  1. Open your Zendesk Guide Appearance Editor.
    You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
  2. Edit the CSS
    See Zendesk's documentation on how to navigate to their CSS editor
  3. 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;
    }
    
  4. Click Save
    After clicking the button it will show you a message "You have unpublished changes"
  5. Click Publish changes
    The styles in your Zendesk Guide are now updated and the Confluence message box macros should appear in Zendesk message styles
  6. Celebrate 🎉

Option 2: Move Confluence Styles to Zendesk Guide

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

  1. Open your Zendesk Guide Appearance Editor.
    You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
  2. Edit the document head
  3. 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">
    
  4. Edit the CSS
    See Zendesk's documentation on how to navigate to their CSS editor
  5. 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;
    }
  6. Click Save
    After clicking the button it will show you a message "You have unpublished changes"
  7. Click Publish changes
    The styles in your Zendesk Guide are now updated and the message box macros should appear in Confluence's message styles
  8. 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:

  1. Open your Zendesk Guide Appearance Editor.
    You can find it at https://[yourzendeskhandle].zendesk.com/hc/admin/appearance#editor
  2. Edit the "Document head"
  3. 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>
  4. Edit the JS
    See Zendesk's documentation on how to navigate to their JS editor
  5. 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();
  6. Click Save
    After clicking the button it will show you a message "You have unpublished changes"
  7. 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
  8. Celebrate 🎉

Anchor Macro

General Limitations