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.

Paragraphs
Screenshots and diagrams
Code and console commands
Headings
Nested headings
Nested heading 2
Heading 2 without text under it
Lists
Preview suggested CSS changes
Further reading (or "Related information")

Paragraphs

Each paragraph should be enclosed with 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 tags and removing them - for whatever reason.

This second paragraph has been left without enclosing 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 tags. Images should be followed by a brief text describing the image (next line, single line, centered, italics), like this:

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.

Figure 2: CSS-applied caption formatting via 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.

Testing code highlighting - HTML:

<html>
  <body class="strong">
    <div class="light">Asdf</div>
  </body>
</htm>

Testing code highlighting - JavaScript:

function asdf(arg1, arg2) {
  val = arg1 + arg2;
  console.log(val);
  return val;
}

Testing code highlighting - Bash:

~/dev/thousandeyes/apidoc/v6$ git status

On branch master
Your branch is up to date with 'upstream/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   admin/_posts/2015-03-23-accountgroup_modify.md
	modified:   admin/_posts/2016-04-22-user_add.md
	modified:   admin/_posts/2016-04-23-user_modify.md

no changes added to commit (use "git add" and/or "git commit -a")

~/dev/thousandeyes/apidoc/v6$

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

This is heading 4

This is heading 5

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

Lists

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

Item 1
Item 2
Item 3

This paragraph is also -enclosed.

But this one isn't -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 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:

Item 1
Item 2
1. Item 2.1
2. Item 2.2
Item 3
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(`
    
`);

Related information

The following resources are available for further reading:

Internal KB formatting guidelines

Knowledge Base formatting example article

Table of contents