Knowledge Base formatting example article

Last updated: Mon Dec 17 14:28:15 GMT 2018

This is an example of how a properly formatted Knowledge Base (KB) article should look like. This is the first paragraph. The first paragraph usually describes the problem statement - a brief summary of the whole article. It makes more sense to do it without the "Introduction" section, as this first paragraph is displayed right under the article title in our public KB. This paragraph or two should be followed by a table of contents, something to give the reader a quick glance of what's to come (or a direct access to a subsection for readers that are already familiar with the content of the article.

Nothing is preventing you from creating two introductory paragraphs if that makes more sense for the presentation of your content. However, do not try to squeeze all your content into the introduction - that would defeat the purpose of the, well, "introduction". If you wish to create an article type like that, create an article of the type Question.

Table of contents

Paragraphs

Each paragraph should be enclosed with <p></p> tags. That produces a bit of extra vertical space between paragraphs, making the reading experience more pleasant. SFDC's CKEditor is a bit moody about this - you may need to select that Normal paragraph style twice. It's a bit odd as well - if you keep assigning "Normal" style to text repeatedly, SFDC alternates between enclosing the paragraph in <p></p> tags and removing them - for whatever reason.

This second paragraph has been left without enclosing <p></p> tags intentionally. It clearly shows how that makes paragraph indentation different.

Do not try to manually create vertical space between section's last paragraph and next section's title - that should be handled by CSS configuration. If it isn't, report it internally and it will get fixed.

Screenshots and diagrams

Images should be indented 40px to the right from the left border. This can be achieved by using the indentation icons in the formatting toolbar or manually, by adding style="margin-left: 40px;" to the enclosing <p> tags. Images should be followed by a brief text describing the image (next line, single line, centered, italics), like this:

KB screenshot example
Figure 1: KB screenshot example

Shadow is added to the image via CSS class - add class="screenshot" to the <img> tag in the source editor. The shadow is not visible during editing and preview, but only in the final output.

KB screenshot example

Figure 2: CSS-applied caption formatting via <p> class attribute

Code and console commands

Code and commands are best presented using the "<>" button from the formatting toolbar. This tool generates the <pre></pre> tags in the source:

<html>
    <header>
        <title>Title</title>
    </header>
    <body>
         <p>Content</p>
    </body>
</html>

Shell commands should use the same tool:

$ sudo echo "Execute this command with 'sudo'"
Execute this command with 'sudo'

$ sudo -s

# echo "This command does not need sudo privileges"
This command does not need sudo privileges

This paragraph is testing how inline code formatting looks like. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Headings (this is Heading 1)

Headings should only be formatted by choosing one of the options from the "Format" toolbar. This is an example of how a heading looks like if it is immediately followed by a full paragraph of text. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

This is heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

This is heading 3

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

This is heading 4

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

This is heading 5

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Nested headings - this is Heading 1

Heading 2 without any text under parent Heading 1

Heading 3 without any text under parent Heading 2

Heading 4 without any text under parent Heading 3

Heading 5 without any text under parent Heading 4

These headings do not need any further manual vertical spacing. In the final output (public KB), they will be properly aligned and spaced. If not, we need to fix that in public KB and not create vertical spacing manually. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Heading 2 without any text under it

Heading 3 right under Heading 2, without any text in between

These headings do not need any further manual vertical spacing. In the final output (public KB), they will be properly aligned and spaced. If not, we need to fix that in public KB and not create vertical spacing manually. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lists

This is a <p>-enclosed paragraph followed by an unordered list:

  • Item 1
  • Item 2
  • Item 3

This paragraph is also <p>-enclosed.

But this one isn't <p>-enclosed, followed by unordered list:
  • Item 1
  • Item 2
  • Item 3 that spans multiple lines. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
  • Item 4
This paragraph is also "unenclosed" within <p> tag.

Anyhow, here is a nested list:

  • Item 1: A lot of text here. A lot of text here. A lot of text here.
  • Item 2: Some text, more items:
    • Item 2.1: A lot of text here. A lot of text here. A lot of text here.
    • Item 2.2: A lot of text here. A lot of text here. A lot of text here.
    • Item 2.3: A lot of text here. A lot of text here. A lot of text here. A lot of text here.
  • Item 3: A lot of text here. A lot of text here. A lot of text here.
  • Item 4: A lot of text here. A lot of text here. A lot of text here.

And a nested ordered list:

  1. Item 1
  2. Item 2
    1. Item 2.1
    2. Item 2.2
  3. Item 3
  4. Item 4

Preview suggested CSS changes

Below are suggested KB CSS changes. To preview them in action, open your browser's developer tools, go to the Console tab and paste/execute the following JS code:


$(document.head).append(`
    <style type="text/css">

        .article-content h1, h2, h3, h4, h5 {
            line-height: normal;
        }

        .article-content h2, h3, h4, h5 {
            margin-bottom: 10px;
        }

        .article-content h1 {
            margin-top: 40px;
            font-size: 1.6em;
            margin-bottom: 15px;
        }

        .article-content h2 {
            margin-top: 35px;
            font-size: 1.4em;
        }

        .article-content h3 {
            margin-top: 30px;
            font-size: 1.3em;
        }

        .article-content h4 {
            margin-top: 25px;
            font-size: 1.2em;
        }

        .article-content h5 {
            margin-top: 20px;
            font-size: 1.1em;
        }

        .article-content p {
            margin-top: 10px;
            margin-bottom: 5px;
            padding: 0px;
        }
 
        .screenshot {
            border: 1px solid #D0D0D0;
            box-shadow: 5px 5px 5px #C0C0C0;
            margin-top: 5px;
            margin-right: 5px;
            margin-bottom: 10px;
        }

        .image-caption {
             margin-top: 0px;
             margin-bottom: 5px;
             font-style: italic;
        }

        .article-content pre {
            margin-left: 40px;
        }

        .article-content code {
            padding: 0px 2px 0px 1px;
        }

        .article-content ul {
            margin-top: 5px;
            margin-left: 40px;
            margin-bottom: 5px;
            padding: 0px;
        }
        .article-content ol {
            margin-top: 5px;
            margin-left: 40px;
            margin-bottom: 5px;
            padding: 0px;
        }


        /* Optional */
        /*
        .article-content {
            font-size: 1.1em;
        }

        .share-event-button {
            margin-top: 7px;
        }
        */

    </style>
`);

Related information

The following resources are available for further reading: