Once you start investigating the new SuperOfficeDocs files, you’ll notice a different style of syntax. This is something called markdown and it’s the commonly accepted format and syntax for tasks just like this. Markdown is simple and easy to use. You can find links to help you get started with Markdown at the bottom of this page.
For example, you’ll do things like
**A BOLDED WORD** instead of typing
<strong>A BOLDED WORD</strong> just to bold some text, which saves you multiple keystrokes.
This guide is intended to ensure that the markup of SuperOfficeDocs has a consistent style, and is easy to navigate and maintain.
Adopting these guidelines also limits variation, thereby eliminating confusion, guesswork, and debates.
Use the style guide as a companion guide.
One benefit to markdown is that the style and formatting of the content can be more simple and uniform across pages. The following examples of formatting and elements can help get you started with the basics. You can find the details in the subsequent alphabetic sections about layout, formatting, and structure.
- Ordered list items
- bold list item
- italic list item
- Unordered list items
- link example
The examples above would look like this in Markdown:
1. Ordered list items 2. **bold list item** 3. *italic list item* * Unordered list items * [link example](https://community.superoffice.com/)
Angle brackets are used for HTML and XML tags and to denote placeholders in code.
The opening angle bracket must be escaped in text. For example, type \<cust ID> to produce <cust ID>. You don't have to escape angle brackets in text formatted as inline code or in code blocks.
Apostrophes and quotation marks
Use basic straight apostrophes and quotation marks. If copying into Markdown, use Ctrl+Shift+V.
Start the line with a >
Bold and italic
- Use a pair of double stars for bold emphasis.
- Don't use underscores to mark emphasis.
- Don't use uppercase for emphasis.
- Don't use quotes for emphasis.
- Use a pair of single stars for italic emphasis.
Call-outs (alerts, admonitions)
One thing you may see in the documentation is the use of call-outs. These show up in the form of light-colored boxes with words such as NOTE, IMPORTANT, or WARNING in them.
They look like this:
This is important.
The call-out above would look like this in markdown:
> [!NOTE] > This is important.
If you want to include a call-out in your docs content, the following types are currently supported:
> [!NOTE] > Information the user should notice even if skimming. > [!TIP] > Optional information to help a user be more successful. > [!CAUTION] > Negative potential consequences of an action. > [!WARNING] > Dangerous certain consequences of an action.
And here is something to note about call-outs!
You cannot include a call-out inside a table.
- Start the line with 1 or more #. The number of hashes determines the heading level. For example, ## means H2.
- Don't nest headings lower than H4.
- There must be a space between the last # and heading text.
Even though Markdown supports inline HTML, we (generally) don't use it on
docs.superoffice.com. It is likely to cause build errors or warnings.
<br>to break a line in table cells and alerts.
- Download links, for example,
<a href="../assets/downloads/mirroredtables.docx" download>Mirrored Tables document</a>
You can use either .jpg or .png images. Place images in the appropriate media folder.
![Image of Yaktocat](https://octodex.github.com/images/yaktocat.png)
We use reference-style links for image paths to improve the readability of the Markdown and simplify maintenance.
Example: the above image of Yaktocat written as reference-style
![Image of Yaktocat][img1]
Reference section at the end of the file:
<!-- Referenced images--> [img1]: https://octodex.github.com/images/yaktocat.png
We prefix all labels referring to images with img.
Reusable icons are placed in the repository's top-level media/icons/ folder. Don't set alt text for icons.
Included Markdown files
When the same content should be repeated on multiple pages, you can use includes.
Reusable content snippets are placed in their own Markdown files in the /includes subfolder and referenced from where they should be inserted. The reference is replaced at build time by the extensions.
Includes are not rendered in the GitHub preview.
- <title> is the name of the file
- <filepath> is the relative path to the file
- INCLUDE must be capitalized
- there must be a space before the <title>
Block include (on a separate line):
Inline include (within a line):
[!INCLUDE [<title>](<filepath>)] and after.
Here are requirements and considerations for include files:
Write all the text in an include file as complete sentences or phrases. Avoid creating a dependency on preceding text or following text on the page that references the include.
Don't nest includes.
Place images used by includes in a /includes/media subfolder.
Don't add metadata at the top of include files.
Relative links within an include file are relative to that file, not where it is included.
You can use reference-style links within the file, but not to set the path for the [!INCLUDE]
For information about the syntax for links, see How to use links in docs.
- Use numbers for ordered lists.
- Use stars for bulleted lists. Don't use dashes.
To include an image, a call-out, a new paragraph, or a child list, indent that content 4 spaces relative to the list item it belongs to.
We use Yaml key-value front-matter syntax to embed metadata in Markdown files.
For information about the syntax for source code, see How to include code in docs.
Special characters that need to be escaped
Markdown treats the following characters as ordinary text if there is a backslash escape character in front of them. For example,
\#. If you don't use escape characters, you can get undesired results when you type them directly.
|-||minus sign (hyphen)|
- Follow standard conventions for fenced and inline code. If you wouldn't escape it in the source code file, don't escape it in Markdown-formatted code.
- Underscore characters within a word. For example, you can write
my_functionwithout escaping. However, leading and trailing underscores require it:
- Separate columns with a pipe character (|). Use surrounding pipes too.
- Separate the header row from the body with a row of dashes (and pipes to match the columns).
- Put 1 space on either side of a pipe (except the left-most and right-most).
- You can align the columns by using colons.
The table above would look like this in markdown:
| default (left) | centered | right | |--------|:------:|-------:| | corn | (winter) squash | beans |
Whitespace and line breaks
- Put 1 space after a sentence (except if followed by a line break).
- Put 1 empty line before and after all block elements:
- Press Enter once to break within a paragraph (<br>). Press Enter twice to start a new paragraph.
- Use horizontal rulers sparingly if at all. Type 3 or more consecutive hyphens to produce an <hr>.
Here are a few resources to help with Markdown to help get you started: