Learn how to use the Freshdesk article editor to create professional, easy-to-read knowledge base articles. This guide covers all formatting options with practical examples and common mistakes to avoid.

Quick Navigation

• Text Formatting Basics - Bold, italic, underline, and more
• Headings & Structure - Organizing your article
• Lists & Numbering - Bullet points and ordered lists
• Callout Boxes - Note, Important, Warning, and Tip callouts
• Tables - Creating and formatting tables
• Images & Media - Adding images with borders
• Code & Quotes - Code blocks and blockquotes
• Best Practices - Pro tips for better articles
• Troubleshooting - Common problems and solutions

Text Formatting Basics

Bold Text

Use bold for: Important keywords, action names, button labels, field names

Italic Text

Use italic for: Emphasis, variable names, file names, software names (in some contexts)

Underline & Other Styles

Avoid underlining textit can be confused with hyperlinks. Use bold or italic instead for emphasis.

Headings & Document Structure

Use headings to create a clear hierarchy and improve readability. Proper heading structure also helps with:

• Table of Contents generation (right sidebar)
• Search engine optimization (SEO)
• Screen reader accessibility
• Skimming and navigation

Heading Levels Explained

Heading Structure Best Practice

H1: Text Formatting Basics
   
   H2: Bold Text
   H2: Italic Text
   
H1: Lists & Numbering
   
   H2: Bullet Lists
   H2: Numbered Lists
   H2: Nested Lists

Lists & Numbering

Bullet Lists (Unordered)

Use for: Non-sequential items, features, requirements, benefits

• Item one - no particular order
• Item two -  equally important
• Item three -  can be in any sequence

Numbered Lists (Ordered)

Use for: Step-by-step instructions, processes, sequences

1. First action -  must be done first
2. Second action -  depends on step 1
3. Final action -  completes the process

Nested Lists

You can nest lists within lists, but keep nesting to maximum 2-3 levels. Deeper nesting becomes hard to read.

• Main item 1
  • Sub-item 1a
  • Sub-item 1b
• Main item 2
  • Sub-item 2a
    • Sub-sub-item 2a-i (avoid going this deep)

Callout Boxes (Note, Important, Warning, Tip)

Callout boxes highlight important information and break up text visually. Each type serves a different purpose.

Note Callout (Blue)

When to use: Additional information, helpful tips, side notes

Example text: "Note: This feature requires administrator privileges"

Important Callout (Red)

When to use: Security warnings, data loss warnings, critical requirements, compliance notes

Example text: "Important: This action cannot be undone. Ensure you have a backup first."

Warning Callout (Orange)

When to use: Risky operations, common mistakes, potential errors, performance impacts

Example text: "Warning: Disabling this setting may affect system performance."

Tip Callout (Green)

When to use: Shortcuts, time-saving tips, pro techniques, workflow improvements

Example text: "Tip: You can use keyboard shortcut Ctrl+S to save quickly."

How to Create Callouts

1. Position your cursor where you want the callout to appear
2. Look for the Quick Insert menu in the toolbar (usually represented by a + or similar icon)
3. Select Callout from the menu options
4. Choose from three types:
   • Orange box = Note callout (blue label)
   • Grey box = Important callout (red label)
   • Blue box = Warning callout (orange label)
5. Type your callout content inside the box

Creating a Tip Callout

Since Freshdesk's quick insert menu doesn't include Tip callouts, you need to manually edit the HTML. Follow these steps:

1. Create a Note callout using the quick insert menu (orange box)
2. Type your tip content inside the callout
3. Click the Code View button in the toolbar
4. Find your callout in the code. It will look like: <pre class="fd-callout fd-callout--note">
5. Change fd-callout--note to fd-callout--tip
6. Click Code View again to return to the visual editor
7. The callout will now display as a green Tip box in the knowledge base

Tables

When to Use Tables

Tables are perfect for comparing options, showing specifications, or organizing data in rows and columns.

• Comparison matrices (compare 2+ products or features)
• Specifications (system requirements, browser support)
• Pricing tables (different plans and features)
• Troubleshooting guides (symptom solution)
• Reference information (shortcuts, codes, commands)

Creating a Simple Table

1. Position your cursor where you want the table
2. Click the Table icon in the toolbar (grid icon)
3. Select the table size (e.g., 3 columns 4 rows)
4. The table will be inserted with a header row (darker background)
5. Click in each cell and add your content

Table with Header Row (Recommended)

Always include a header row (the darker row at the top). This helps users understand what each column represents.

Table Best Practices

• Keep it simple: Aim for 2-4 columns max. Too many columns make tables hard to read on mobile.
• Use clear headers: Make sure the header row clearly labels each column.
• Consistent data: Keep content in each column consistent (all text, all numbers, etc.)
• Don't make huge tables: If your table has more than 8-10 rows, consider breaking it into multiple tables or using a different format.
• Use for data only: Tables should contain data, not full paragraphs. Keep cell content brief.

Troubleshooting Tables

Problem: Table is too wide for the page

• Reduce the number of columns
• Make column headers shorter
• Shorten cell content

Problem: Cells don't align properly

• Click in the cell and use the alignment buttons (left, center, right)
• Right-click a column header to adjust column width

Images & Media

Adding Images

Images should be: Relevant, clear, not too large, properly formatted

1. Position your cursor where you want the image
2. Click the Image icon in the toolbar (picture icon)
3. Upload from your computer or paste a URL
4. Add alt text (description for accessibility)
5. Click Insert

Adding Image Borders

Borders help images stand out and frame them professionally. In the knowledge base, borders display as a 2px black border.

1. Click the image in your article
2. Select Style to open the dropdown
3. Select the "Bordered" option to apply a border.
4. The border will appear in the published article

Example image with border:

Image Best Practices

• Use clear images: Avoid blurry screenshots. Use high contrast to make text readable.
• Add alt text: Describe the image briefly. This helps visually impaired users and improves SEO.
• Annotate when needed: Use arrows, boxes, or text overlays to highlight important parts.
• Keep file sizes reasonable: Large images slow down page loading. Optimize before uploading.
• Center important images: Images explaining a concept should be centered, not left-aligned.
• Use borders for UI screenshots: This helps distinguish screenshots from regular content.

Code Blocks & Blockquotes

Code Blocks

Use for: SQL queries, configuration files, code snippets, API calls, commands

1. Click the Code block icon in the toolbar (looks like { })
2. Select the programming language (SQL, JavaScript, Python, Bash, etc.)
3. Paste or type your code
4. The code will display with syntax highlighting and line numbers

Example SQL query:

SELECT * FROM users WHERE status = 'active' ORDER BY created_date DESC;

Code block best practices:

• Always specify the language (helps with syntax highlighting)
• Include comments explaining complex code
• Replace sensitive information with placeholders: example_database, YOUR_API_KEY, etc.
• Keep code blocks short (10-20 lines max). If longer, break it into sections.

Blockquotes

Use for: Quoted text, testimonials, indented references

"This is a blockquote. It's indented and displayed in a slightly different style to distinguish it from regular paragraphs."

Creating blockquotes: Unlike callouts, blockquotes don't have a dedicated formatting button. To add a blockquote, you must use the HTML method:

1. Click the Code View button in the toolbar
2. Position your cursor where you want the blockquote
3. Add the HTML code: <blockquote dir="ltr"><p dir="ltr">Your quoted text here</p></blockquote>
4. Click Code View again to return to the visual editor
5. Your blockquote will display with indentation and styling

Best Practices for Professional Articles

1. Structure Your Articles Logically

Formula that works: Note that your article title is managed separately from the HTML content (by Freshdesk's header settings). Your HTML content should start with:

• Introduction paragraph - 1-2 sentences explaining the topic
• H1 Quick Navigation (optional) - Jump links to main sections
• H1 First Major Section - Your main content sections
• H2 Subsections - Break up content within each H1 section
• H1 Troubleshooting - Common problems and solutions
• H1 Related Articles - Links to similar content

2. Use Consistent Formatting

• Bold for UI elements and buttons (always)
• Italic for variable names and file paths (always)
• Code blocks for commands and code (always)
• H1 for major sections (always)
• H2 for subsections within H1 sections (always)

Consistency helps readers quickly understand what type of information they're looking at.

3. Break Up Long Text

Use these techniques to keep articles scannable:

• Use headings to create sections
• Keep paragraphs short (3-5 sentences max)
• Use bullet lists instead of long paragraphs
• Add callout boxes to highlight important info
• Use tables for comparisons
• Add images/screenshots to break up text

4. Write for Scanning

Most readers scan articles rather than reading every word. Help them find what they need:

• Put the most important info first
• Use descriptive headings that explain what's in each section
• Use bold text to highlight key terms
• Start lists and callouts on new lines (not inline)

5. Be Specific and Concrete

 Avoid: "Click the button to save your changes"

 Do this: "Click the Save button in the top right corner to save your changes"

Specific instructions are easier to follow and reduce confusion.

6. Use Callouts Strategically

Good use of callouts:

• Warning about data loss or security risk
• Keyboard shortcut or time-saving tip
• Important requirement or prerequisite
• Common mistake to avoid

Don't use callouts for: Normal instructions, background information, or definitions

Troubleshooting Common Formatting Issues

Callouts Not Displaying Correctly

Problem: You created a callout but it shows the wrong color or missing label.

Solution:

1. Click inside the callout to position your cursor
2. In the toolbar, look for the Callout dropdown menu
3. Make sure you've selected the correct type: Note (blue), Important (red), Warning (orange), or Tip (green)
4. If it still doesn't work, delete the callout and create a new one

Images Are Too Large or Too Small

Problem: After uploading, your image is displaying at the wrong size.

Solution:

1. Right-click the image
2. Look for Resize or Image Properties
3. Adjust the width/height (keep aspect ratio locked to avoid distortion)
4. Click Update or Apply

Table Won't Fit on the Page

Problem: Your table is too wide and users have to scroll horizontally to see all columns.

Solution:

• Reduce columns: Can you combine any columns or remove unnecessary ones?
• Shorten headers: Use abbreviations or shorter column names
• Shorten content: Keep cell content brief (use acronyms, abbreviations)
• Break into multiple tables: If you have 5+ columns, split into 2 smaller tables

Creating Custom Callouts with HTML

When to use: When you need to create a Tip callout or manually edit existing callout types.

Instructions:

1. Click the Code View button in the toolbar
2. Find your callout code or position cursor where you want to add one
3. Use one of these HTML snippets:
   • <div class="fd-callout fd-callout--note">Your text</div> for Note
   • <div class="fd-callout fd-callout--info">Your text</div> for Important
   • <div class="fd-callout fd-callout--idea">Your text</div> for Warning
   • <div class="fd-callout fd-callout--tip">Your text</div> for Tip
4. Click Code View again to return to the visual editor
5. Your callout will display with the correct style and color

Heading Doesn't Appear in Table of Contents

Problem: You created an H2 heading but it's not showing in the Table of Contents (right sidebar).

Possible causes:

• The heading wasn't formatted as H2check that it has the heading style applied
• You used bold text instead of actually selecting "Heading 2" from the dropdown
• The article needs to be saved and republished

Solution:

1. Click your heading to position the cursor in it
2. In the toolbar, find the paragraph/style dropdown (usually shows "Normal" or "Paragraph")
3. Select Heading 2 from the list
4. Save the article
5. Refresh the pagethe heading should now appear in the Table of Contents

Copy-Pasted Content Has Strange Formatting

Problem: You pasted text from another document and it brought unwanted formatting (weird fonts, colors, sizes).

Solution (Method 1 - Paste Special):

1. Before pasting, look for a Paste Special option in the Edit menu or right-click menu
2. Select Paste as Plain Text
3. The text will paste without any formatting
4. Then apply your desired formatting (headings, bold, etc.)

Solution (Method 2 - Clear Formatting):

1. Paste the text normally
2. Select all the pasted text (Ctrl+A)
3. Click the Clear Formatting button in the toolbar (usually looks like an "X" with lines)
4. Reapply your formatting

Pro Tips & Tricks

Use Keyboard Shortcuts

Use the Preview Feature

Before publishing your article:

1. Click Preview button (or similar)
2. Check how your article looks to readers
3. Verify images are centered and sized correctly
4. Check that the Table of Contents shows all your headings
5. Make sure links work

Create a Template

If you write similar articles regularly, create a template:

1. Write one article with your preferred structure
2. Add placeholder text for each section
3. Save it as a draft
4. When creating a new article, duplicate this template and fill in the details

Quick Reference: Formatting Checklist

Before publishing your article, check:

• Major sections use H1 headings
• Subsections use H2 headings (not H3)
• Important info is highlighted with callouts (Note, Important, Warning) or bold text
• Tip callouts are created using the HTML method
• Steps are numbered (not bulleted)
• Lists of items are bulleted (not numbered)
• Tables have header rows
• Images have alt text and are properly sized
• Code blocks specify the language
• Blockquotes are created using HTML if needed
• Links are descriptive ("Click here to learn more" vs "Click here")
• No orphaned formatting (bold text with nothing to emphasize)
• Spelling and grammar checked
• Preview looks good on desktop and mobile