Use Zendesk and HC Guides
- Article title.
- Text type menu, where you can choose between paragraph (regular text) and different sizes of headings.
- Text formatting, where you can make text bold, italic, underlined or into code block.
- Create numbered lists, bullet points, as well as indent/outdent text.
- Add a link.
- Add an image or GIF.
- Add a video.
- Add a table.
- Open source code window.
Tips & Tricks
- Find the article within Todoist HC.
- Click your avatar in the top bar.
- Select Edit article.
- You are now in Preview mode. Click Edit on Zendesk in the top-right corner.
- This will open the article in Zendesk.
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:
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.
- Get the URL of the article you're editing. For example: https://todoist.com/help/articles/backups
- Add ?refresh=true to the end of the URL. For example: https://todoist.com/help/articles/backups?refresh=true
- Reload the page
Format 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:
- 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.
- Open the source code window and add <div data-accordion=""> before the h4 heading.
- 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.
- 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).
- 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.
- GOOD: https://todoist.com/help/articles/360000636289
- BAD: https://todoist.com/help/articles/set-a-recurring-due-date
- BAD: https://todoist.com/fr/help/articles/set-a-recurring-due-date
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 title<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 query | What it does |
#Today | Shows all tasks due today |
no date | Shows 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 query | What it does |
---|---|
#Today | Shows all tasks due today |
no date | Shows 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 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:
- Desktop step 1
- 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>
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:
- 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.
- 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.
Insert an image using the image icon in the top menu.
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:
the source code should say:
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:
To add this styling, add
For mobile images that need a phone frame use to the source code of your image. For example:
(for an Iphone frame) or
(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.
Web icons
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.
With Doister avatars:
You can choose from list of names to display avatars inline. For example, this paragraph displays 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:
- Add the avatar image to the collection in Contentful.
- Notify a Brand developer via Github issue to update the avatar list.
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:
- Create a h3 heading. This heading will become the text the user can click on to expand the text underneath.
- Open the source code window and add <div data-accordion=""> before the heading.
- Add data-accordion-title="" right after h3 between the code brackets, e.g.: <h3 data-accordion-title="">This is a title</h3>
- 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>