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.
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
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.
Please sign in to leave a comment.