Add Custom HTML to your Help Centre

The editor provided with Zendesk Guide has lots of useful tools to create articles, especially if you’re new to creating help centre content.

The Zendesk Guide article editor.

For web developers though, this editor can feel limiting pretty quickly. You may have thought “Aha, there’s a code editor option — I’ll be able to add my custom HTML directly onto the page from there”. Well, yes and no.

To help protect the average user, by default Zendesk Guide quarantines a wide range of HTML tags to reduce the chance that someone may try to exploit your site using malicious code. I somewhat understand the rationale, but to me the added security comes at the cost of serious confusion for anyone looking to create more advanced articles.

To make things worse for the beginner, the editor doesn’t make it clear what it’s doing, or which tags are being quarantined. Instead, they’re simply stripped when the page is rendered in the browser.

After a lot of searching, I finally found some documentation for tags and attributes deemed ‘safe’:

strong, em, b, i, p, code, pre, tt, samp, kbd, var, sub, sup, dfn, cite, big, small, address, hr, br, id, div, span, h1, h2, h3, h4, h5, h6, ul, ol, li, dl, dt, dd, abbr, acronym, a, img, blockquote,
del, ins, u, table, thead, tbody, tfoot, tr, th, td, colgroup

Attributes have similar restrictions, too. Here’s the ‘safe’ ones:

href, src, width, height, alt, cite, datetime, title, class, name,
xml:lang, abbr, target, border

What if you want to expand beyond these tags and create your own custom HTML? There’s quite a few steps involved, but once you’ve created your first custom article, the rest will be a breeze.

Enable unsafe HTML

Open Zendesk Guide and open Guide Admin. Click on the Settings cog from the left-hand column to view Guide Settings:

Zendesk Guide admin page.

Scroll down and find Display unsafe content. Make sure the box is checked and then click Save:

Display unsafe content option in Zendesk Guide.

You’re now all set to add custom HTML to your article pages.

Create an HTML article

You can create an HTML article in the same way as any other web page. It’s best to do this in a text editor rather than directly within Zendesk Guide. You can use any editor you’re comfortable with, but I prefer Sublime Text.

Designing an HTML page in Sublime Text.

Save the page locally as an HTML file and you’ll be able to test it in any web browser. You can create the page identically to a standard HTML document — including adding CSS classes and external files like fonts or images.

Convert HTML for Guide

Although we’ve enabled HTML for Zendesk Guide, we can’t directly copy the page we’ve created into an article. This is because despite lifting the restrictions, the page renderer will still strip anything in the <head> section of our page.

To get around this, we’ll use a trick that email designers have used for years: inline CSS. By adding our CSS rules directly to each tag where they’re used, we can bypass any restrictions and make our page look exactly how we want.

Inlining CSS is an incredibly laborious task, but thankfully those crafty email designers have created tools to automate the process. MailChimp make a particularly good one — simply open the tool, paste your full HTML page (including any CSS styling) and hit the Convert button:

CSS Inliners are usually used for email, but work perfectly for articles, too!

Cleaning the code

Our CSS styles have now been successfully inlined. You might have already noticed that the tool your original <style> tags and CSS are still present, along with a few other tags that we won’t need to add the article to Zendesk Guide.

Strip any remaining tags that won’t be used.

Copy your newly inlined HTML and paste it into a new file in your text editor. Delete your entire <head> section, as well as the <html> and <body> tags.

Add to Article

We’re ready to add our custom HTML to our article! Create a new article and select the Source code option from the editor toolbar:

The Source code allows you to directly edit the article’s HTML

Copy your inlined and edited HTML into the editor window and then click OK:

Your HTML will look rather messy in the editor window.

You should now see your HTML in the preview window for the article. Don’t be too worried if it doesn’t look exactly the same as in your tests — it should render correctly once opened from the help centre itself.

Things may look somewhat odd at this stage — don’t worry.

Test it Out

Save your article and click Preview in Help Center:

You should now see your perfectly formatted HTML! If you’re using images or custom fonts, be sure to store them online and create absolute paths back to the files in your design, otherwise the files won’t load.

Tips & Tricks

You’re page is looking great, but what if you need to change it at a later date? Editing inlined CSS is rather unpleasant, so I recommend saving all of your HTML files in a folder on your computer so that you can easily edit your designs.

Once you’ve started to get the hang of creating HTML articles, you might want to consider creating a standard template to keep the design of your articles consistent. I always include common design elements like headings, links, and tables as a CSS template that I can drop in to speed up the process.

Jennifer Rowe

August 22, 2018 23:32

Thanks for sharing this, Mathew!

Anthony Inman

May 03, 2019 22:31

Mathew

Thanks for putting this together. I wish I knew about MailChimp a couple years ago. My IT department doesn't let me mess with the Theme code in our Guide, so I about a year ago I started adding CSS inline with my HTML to put some life into my articles. I created a ton of templates in Code Writer to use when creating articles. It literally saves me hours when I create new articles.