Formatting a help center article


Using Zendesk and HC Guides

Screenshot_2020-12-15_at_15.34.17.png
  1. Article title.
  2. Text type menu, where you can choose between paragraph (regular text) and different sizes of headings.
  3. Text formatting, where you can make text bold, italic, underlined or into code block.
  4. Create numbered lists, bullet points, as well as indent/outdent text.
  5. Add a link.
  6. Add an image or GIF.
  7. Add a video.
  8. Add a table.
  9. Open source code window.

Tips & Tricks

  1. Find the article within Todoist HC.
  2. Click your avatar in the top bar.
  3. Select Edit article.
  4. You are now in Preview mode. Click Edit on Zendesk in the top-right corner.
  5. This will open the article in Zendesk.

Screenshot_2021-02-12_at_10.03.54.png

We can’t quite preview articles the same way we used to in the old HC. Instead you can preview you article by using the link format:

https://todoist.com/help/preview?id=ARTICLENUMBER

As an example, let's say your article number is 11111111, you can preview your article by using the link below:

https://todoist.com/help/preview?id=11111111

You can learn how to find your article's number in the next section.

You can find the article number in the URL when you view your article in Zendesk or when viewing your article in Preview mode:

Screenshot_2021-02-12_at_10.14.29.png

If you're making changes to an article in Zendesk and it's taking a while for the changes to reflect within HC, you can force a page refresh.

  1. Get the URL of the article you're editing. For example: https://todoist.com/help/articles/backups
  2. Add ?refresh=true to the end of the URL. For example: https://todoist.com/help/articles/backups?refresh=true
  3. Reload the page

Formatting text

All code described in this section will need to be added in the source code of the article. You can see how to open the source code window in the Introduction to Zendesk section at the top of this article.

There are 3 different sizes of headings you can use in HC. Depending on what heading you use, this may have an impact on the formatting of your article:

  • h2: All h2 headings become part of the article's table of contents.
  • h3: You can use H3 as a way to format the size of a text. It can also be used as the header of an accordion (often used in What's New articles – see instructions below).
  • h4: You can also use h4 to format the size of a text. It can also be used as a smaller header of an accordion (most commonly used for FAQ in our HC articles – see instructions below).

Warning

It's recommended that you not use the h1 heading in HC articles.

The table of content is populated with all H2 titles. If your H2 title is too long for the TOC you can customize it with the following code:

<h2>FULL TITLE <span data-hd-shorttitle>SHORT TITLE</span></h2> So for example, if you have a H2 title called `New in Todoist: Get Sorted` and you think it looks a bit too long for the table of contents, you can shorten it to something like `Get Sorted`. In order to do that, you'll use the below source code: <h2>New in Todoist: Get Sorted <span data-hd-shorttitle>Get Sorted</span></h2>

If you want a piece of text to become expandable, you can add an accordion. Here's how:

  1. If you haven't already, create a h4 heading. This heading will become the text the user can click on to expand the text underneath. 
  2. Open the source code window and add<div data-accordion=""> before the h4 heading.
  3. Identify where you want the accordion to stop. Add</div> under this text.

Your source code will end up looking like this:

<div data-accordion="">
  <h4>Text the user will click on to expand text below</h4>
  <p>Text that the accordion will expand to</p>
</div>

Quick tip

Note: Read the instructions below if you want to create a How it works accordion for the What's New article.

You can add several h4 headings within the same accordion, so you won't have to format each piece of text you want to be expandable separately. Note: this only works for h4. A great example of this is when we add FAQ to an article. The source code for the FAQ of an article should end up looking like this:

<h2>FAQ</h2>
 <div data-accordion="">
    <h4>Question 1</h4>
       <p>Answer 1</p>
    <h4>Question 2</h4>
       <p>Answer 2</p>
    <h4>Question 3</h4>
       <p>Answer 3</p>
 </div>

To add a hairline divider in your article, add <hr /> in the source code.

When linking to another HC article, you should:
    1. Use the article ID number in the URL instead of the name of the article (you can learn how to find your article's number under Tips & Tricks in this guide).
    2. When linking to a HC article you should always remove the language identifier (i.e. in English articles this would be en-us) from the link. This ensures that if a non-English speaker opens the link, the article will automatically switch to that user's language.

Note

By using the URL that has the article number, you also ensure that if the article is renamed (which would also change the name of the link that doesn't use the article number), the URL will still work and send the user to the correct article.

As an alternative to using a link, a button can be used for emphasis. A button will behave in the same manner as a link but it needs to be added via the source code. You should provide a URL (using the same best practices above) for the button via the `href` property. 

Note

If you want the button to open the link in a new tab, you can add the property `target="_blank"` to the button.

For example, the below source code will create this button:

<button href="https://todoist.com/help/articles/formatting-a-help-center-article" target="_blank">
  Button title
</button>

Sometimes we use images to act as buttons, meaning that if you click on the image you get sent to the URL the images links to. When we do this, it's important to remember to add the `data-nolightbox` code, otherwise users will see a weird preview pop-up of the image before we get forwarded to the URL.

Here's an example of how to add the `data-nolightbox` code:

<imgsrc="/hc/article_attachments/115002221085/download-chrome.svg" alt="download-chrome.svg" data-nolightbox>

You can add a table to your article simply by using the table icon in the Zendesk menu. This will create a basic table that will look something like this:

Filter queryWhat it does
#TodayShows all tasks due today
no dateShows all tasks that don’t have a due date.

However, if you would like to create a table that looks a bit fancier, you can copy-paste the code below into the source code of your article.

<table>
    <thead>
        <tr>
            <th style="width: 220px">Filter query</th>
            <th>What it does</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>#Today</td>
            <td>
           Shows all tasks due today
            </td>
        </tr>
        <tr>
            <td>no date</td>
            <td>
                Shows all tasks that don’t have a due date.
            </td>
        </tr>
    </tbody>
</table>

This will create a table that looks like this:

Filter queryWhat it does
#TodayShows all tasks due today
no dateShows all tasks that don’t have a due date.

Once you've created the table you can then edit its content, as well as use Zendesk's table menu to add rows or columns.

Add a platform pickers and boxes

All code described in this section will need to be added in the source code of the article. You can see how to open the source code window in the Introduction to Zendesk section at the top of this article.

When adding a platform picker, you need two pieces of code:

  • <div data-platforms="">
    • inserts a platform picker into your article.
  • <div data-platform="web mac windows-10 ios android">
    • determines what platform a set of instructions refers to. For example, if a set of instructions only refers to the macOS and iOS apps, you would add the code <div data-platform="mac ios">.

After each set of platform-specific instructions, add </div> in the source code, in order to "close" the instructions for that specific platform(s).

In order to mark where the platform picker should end (i.e. after the last set of platform-specific instructions), you should add another </div> to close out the platform picker.

As an example, if you add the below code to an article:

<div data-platforms="">
 <div data-platform="web mac windows-10">
   <ol>
    <li>Desktop step 1</li>
    <li>Desktop step 2</li>
   </ol>
 </div>
  <div data-platform="android ios">
   <ol>
    <li>Mobile step 1</li>
    <li>Mobile step 2</li>
    </ol>
 </div>
 </div>    

You'll get the below platform picker:

  1. Desktop step 1
  2. Desktop step 2

Warning

It's important that you write the platform names exactly as listed below in the source code (i.e. don't write win-10 instead of windows-10 or macOS instead of mac), otherwise the platform picker will not be formatted correctly:

  • web
  • mac
  • windows-10
  • ios
  • android

Add the code <div class="box-tip">TEXT</div> with your tip in the middle of the code. For example, adding the code <div class="box-tip"> Here's a tip! </div> would create the below Quick Tip box:

Quick tip

Here's a tip!

Evert · Customer Experience

You can also include an author in your tip box by using the following attributes:

  • data-box-name
  • data-box-avatar

Add a role or description as well by adding a child span to the note box:

<span data-box-description="">Customer Experience</span>

Read the docs for more information

Add the code <div class="box-note">TEXT</div> with your note in the middle of the code. For example, adding the code <div class="box-note"> Here's a note! </div> would create the below Note box:

Note

Here's a note!

Add the code <div class="box-warning">TEXT</div> with your warning in the middle of the code. For example, adding the code <div class="box-warning"> Here's a warning! </div> would create the below Warning box:

Warning

Here's a warning!

Icons, images, videos, and GIFs

Images or GIFs for HC articles may be requested in two ways:

  1. If the new image is part of an active DO (a new feature for example), the article writer should ask the designer assigned to that DO to create the image.
  2. If the new image in a one-off and isn’t linked to an active DO, the article writer should create a task in the HC Image Requests Todoist project and notify both the Brand Design hero and the Product Design hero. Heroes will work together on that image.
If you have any question regarding Help Center images you can discuss them in this Twist thread.

Insert an image using the image icon in the top menu.

Screenshot_2021-02-08_at_13.20.57.png

Setting the image size

Then set the width of the image manually in the source code by adding width="PIXELSIZE". The width the image should be set at will be noted in the file name:

For example, for the file duplicate-project_ios_276.jpg, the source code should say:

image1.png

Warning

Never set the height of the image, only the width.

Styling Todoist desktop images

Note

Since the New Twist launch, this particular guideline only pertains to Todoist images.

Most Todoist images should include what the Design team calls a basic frame, which includes a shadow and round corners. It looks like this:

Screenshot_2021-01-29_at_17.41.08.png

To add this styling, add data-screenframe="" to the source code of your image. For example:

image2.png

For mobile images that need a phone frame use data-phone-frame="ios" (for an Iphone frame) or data-phone-frame="android" (for an Android phone frame).For example:
<img src="path-to-phone-screen.jpg" data-phone-frame="ios" alt="Add a new Task" />
<img src="path-to-phone-screen.jpg" data-phone-frame="android" alt="Add a new Task" />

Warning

Other types of graphics might not need the basic frame, like the one in this article for example. If you are unsure if an image needs the basic frame, check with the designer who created it.

CenteringTo center an image simply change the text alignment to centered.center-image.pngFullscreen imagesSometimes, you don‘t want images to show in full screen. This is especially true in cases where you're using an image to represent a link (such as we do in our Download Todoist and Download Twist articles). In order to achieve this, you need to add data-nolightbox at the end of the source code entry for your image, for example:<img src="IMAGECODE" alt=IMAGETITLE" data-nolightbox=""/>

Web icons

Use a <span> HTML element with the data-icon attribute set to the icon name prefixed with web-.-> Here the full list of all web iconsExample:
For example, pull up a list <span data-icon="web-Boards"></span> of all your tasks labeled @email <span data-icon="web-ActivityLog"></span> that…

F1MCdamw.png

iOS icons

Use a <span> HTML element with the data-icon attribute set to the icon name prefixed with ios-.

-> Here the full list of all IOS icons

Example:

You can expand by clicking this icon: <span data-icon="ios-Expand"></span>.

icon-example2.png

Android icons

Use a <span> HTML element with the data-icon attribute set to the icon name prefixed with android-.

-> full list of Android icons

Example:

You can expand by clicking this icon: <span data-icon="android-Expand"></span>.

icon-example3.png

Videos should have been uploaded to our account in Wistia.com, using these instructions.

Warning

GIFS are not recommended. Instead use a video uploaded to Wistia. You can set it to loop if this is really needed but we recommend to let the viewer decide it they want to see it again.

To add the video to your article, use the Zendesk formatting tool and paste your video's embed link.

video-instructions.jpg

With Doister avatars:

You can choose from list of names to display avatars inline. For example, this paragraph displays Stijn and Paweł. Another example is Anthony and Craig. Pass a single string value separated by spaces to the attribute data-inline-avatars. The avatars will be displayed in the order in which they are added to the data attribute.

As an example:

<p>
    A paragraph with <span data-inline-avatars="stijn pawel"></span> Doisters
    Stijn and Paweł.
</p>

See the list of available Doisters here.

Quick tip

To add more Doisters to this collection:

With custom avatar urls:

Or use custom images with the data-inline-avatar-urls attribute, like these.

As an example:

<p>
  A paragraph with <span data-inline-avatar-urls="https://images.ctfassets.net/dm4oa8qtogq0/109MBRGv6gUnztliQ3xYJ8/02940c02ab862aa6a907130170cc46ad/jef-avatar.jpg https://images.ctfassets.net/dm4oa8qtogq0/76JhiwmYL0eYkOU5NQ4SGk/0e4bf0bed885dda4c27cfe3809f66195/brenna-avatar.jpg"></span> custom avatars.
</p>
  

Use labels

Labels control additional information that can be added to your article other than the article itself, such as what subscriptions and platforms a feature can be used with, whether there should be a table of contents, and whether users should be able to provide feedback on the article.

Subscription labels (Todoist only): add labels for what subscriptions the feature is available for.

  • td-free: If the feature is available on the free version of Todoist.
  • td-pro: if the feature is available to Pro users.
  • td-business: if the feature is available to Business users.

Platform labels: add labels for all the platforms the feature is available on.

  • web
  • macOS
  • windows 10
  • android
  • ios
  • linux

If your article is about an experimental feature, you can add the label experimental.

Each article has 4 "related articles" which have been automatically generated. If you wish to select one - or several - related article(s) for your article, you can do so by adding the label `related-ARTICLENUMBER`.

So for example, if you wish to set this article as a related article, you should get the article's number, which is 360007666099. Your label will therefore be `related-360007666099`.

(You can learn how to find your article's number under Tips & Tricks in this guide).

You can set up to 4 related articles. If you set less than 4, the rest will be automatically generated.

Feedback vote label: Determines whether users will be able to vote on whether an article is helpful or not. 

  • vote-disabled

Table of contents label: Disables the table of contents from an article. 

  • toc-disabled

Format the What's New page/changelog

It's super easy to format the changelog in Zendesk! Just remember to not paste content from another program like the What's New in TD Google Doc without doing plain format pasting (for example, use Ctrl + Alt + V or Cmd + Alt + V).

But here's exactly how to do it!

Use this if you have a long Header 2 title for the changelog.

 <h2 data-shorttitle="[SHORT TOC TITLE]">[LONG BODY TITLE]</h2>
  

Once you put in the Header 2 title, add an image or body copy below. If you have additional sections of content, add them with the Header 3 titles and images and body copy as well. Example:

<h3>60+ essential resources for productive learning</h3>
<p>
<img src="https://get.todoist.help/hc/article_attachments/13397641556636" alt="">
</p>
<p>
From the most effective study techniques to must-have organizational apps (other than Todoist 😉)...
</p>

Note: Make sure to add alt text for images in the code, unless it is a decorative image (like above) and then delete the alt text.

Finally, end the changelog with the classic accordion code below for optimizations, bug squishes, and version numbers.

Here‘s how to use the accordion for an expandable How it works section:

  1. Create a h3 heading. This heading will become the text the user can click on to expand the text underneath. 
  2. Open the source code window and add <div data-accordion=""> before the heading.
  3. Add data-accordion-title="" right after h3 between the code brackets, e.g.: <h3 data-accordion-title="">This is a title</h3>
  4. Identify where you want the accordion to stop. Add </div> under this text.
<div data-accordion=""> 
<h3 data-accordion-title="">How it works</h3>
<ul>
<li>Bullet</li>
<li>Bullet</li>
</ul>
</div>