Use HTML in the Docs Editor

Our new Docs editor allows your team to make beautiful Docs articles without needing to work with HTML. We know that some of you are really comfortable with HTML and want to take on creating some more custom looks in your articles though — the HTML block tool gives you the option to bring your own HTML expertise and get creative!

This article will cover how to add the HTML block to an article, and offer up a few examples of things you can add to articles.

Check out About the Docs Editor if you're looking for more general help on the editor.

The Docs editor is available to all users and user roles with the Edit articles and categories permission. See User Roles and Permissions for more help on that.

Add the HTML Block

Click the + (plus sign) to the left of a new line, or type / (the forward slash) to open the shortcut menu and choose HTML block.

The HTML block will accept any valid HTML5 tags and event handlers that are usable within the <body> of an HTML document, with the exception of <script> and <style> tags.

See Customize Your Docs Site for information on how to include <script> or <style> elements in the <head> section across your Docs site.

Convert HTML Block to Editor Format

It is possible to convert your HTML Block into regular editor text. Click the kebab menu (three dots menu) in the top-right corner of an HTML block, then click the "Convert to editor format" option.

Elements that remain will only keep the customizations supported directly by the Docs editor. Any HTML classes, inline CSS, or other customizations will be removed.

Example Uses

Below are a few things you can do in the HTML block. You're not limited to these options of course, but these are some of the most commonly needed uses!

Note: You cannot add the HTML block within other elements — you'll need to use the HTML block for the entire paragraph, image, table, etc. to use it to customize any portion of that element.

Embed a Video From Other Hosts

Videos hosted on YouTube, Vimeo, Loom, CloudApp, or Wistia can be added with just a link to the video by using the Insert video option in the editor menu. (See About the Docs Editor: Format Article Content for more help with that menu.)

If your video is hosted with a provider other than the ones supported there though, you can add it using the HTML block. Just paste in the embed code you get from your provider.

The exact code will vary — check in with your video hosting platform's support if you need help finding the embed code for your host. Below is an example of an embed code you might get if you host your videos on Kapwing.

<div style="height: 533.39px; width: 300.00px; position:relative;"><iframe allow="autoplay; gyroscope;" allowfullscreen height="100%" referrerpolicy="strict-origin" src="https://www.kapwing.com/e/646e7619dfa8110017d3545445642fbf" style="border:0; height:100%; left:0; overflow:hidden; position:absolute; top:0; width:100%" title="Embedded content made on Kapwing" width="100%"></iframe></div><p style="font-size: 12px; text-align: right;">Video edited on <a href="https://www.kapwing.com/video-editor">Kapwing</a></p>

You may find you'll need to add a bit of CSS to your video embeds to make sure that they're looking good across all screen sizes and devices. Just add a wrapper around the video embed with the classes video and widescreen .

 <section class="video widescreen"> VIDEO EMBED CODE GOES HERE </section>

If you have any issues getting your video just the way you want it in an article, give us a shout by clicking Contact below with a link to the article that's giving you trouble!

Add a Call to Action Link to Open Docs Beacon

Add a CTA link that will open your Docs Beacon when you want your visitors to reach out to your team. The link requires a bit of specific code with event handlers to ensure that these links work in both your Docs site and any Beacons that serve up Docs articles, so you'll need to use an HTML block to format the element that includes that link.

You can find full documentation of the Docs Beacon and more on this link at Manage Docs Contact With Beacon.

Sample HTML:

<p>If you encounter any issues with placing an order, <a onclick="window.parent.Beacon('open'); window.parent.Beacon('navigate', '/ask'); return false;" href="#">reach out to our team</a> and we'll be happy to help!</p>

Use Definition Lists for Detailed Steps

The definition list element (<dl>) contains a term (<dt>) and a description (<dd>). Use this element to create detailed step-by-step instruction lists.

1: Go to the Winchester.
2: Have a nice cold pint.
3: Wait for this to all blow over.

Note: The background color behind the <dt> elements in a definition list is grey by default. You can change that color with this selector in your custom CSS:
#fullArticle dt {background:yourcolorchoice;}

Sample HTML:

<dl>
	<dt>1</dt>
		<dd>Go to the Winchester.</dd>
	<dt>2</dt>
		<dd>Have a nice cold pint.</dd>
	<dt>3</dt>
		<dd>Wait for this to all blow over.</dd>
</dl>

Use Additional CSS Styles

There are a few style classes that are built into Docs that you can use in the HTML block to further style some elements, and if you've used CSS to customize your Docs site, you may have some custom classes you want to apply. Use the HTML block to create your elements and apply your own styles to them.

See Customize Your Docs Site: Use CSS for more information on adding your own custom CSS to Docs.

Built in classes you can use

Below are classes that are built into Docs that you can apply to your elements as described. Note that if you have applied any custom CSS, your own CSS may cause these to work differently.

Docs automatically resizes images to a maximum width of 1000px and a maximum height of 800px. Add a link to an image with the class of lightbox to offer the option for visitors to click the image to expand to the full size version.

Pro tip: Use <figure> to call the image and set a caption with <figcaption> to let visitors know there's an option to click.

Image of a Banana — Click the image to see a larger version of this banana

Sample HTML — replace the image paths and caption text with your own:

<figure>
<a href="https://yourfilelocation.com/image.png" class="lightbox">
<img src="https://yourfilelocation.com/image.png" alt="">
</a>
<figcaption>Click to see a larger version</figcaption>
</figure>

Remove image border

Images have a rounded border by default in Docs. Call images using the HTML block and add class="noBdr" to the img tag to remove the border.

Image of a Banana

Sample HTML — replace the image path and alt text with your own:

<img src="https://yourfilelocation.com/image.png" class="noBdr" alt="Image of a Banana">