Skip to main content
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.
  1. Ordered list items
  2. bold list item
  3. italic list item
The examples above would look like this in Markdown:

​
Angle brackets

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.

​
Blockquotes

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 or WARNING in them. They look like this:
This is important.
The call-out above would look like this in markdown:
If you want to include a call-out in your docs content, the following types are currently supported (see Mintlify’s callout components for the full reference):
And here is something to note about call-outs!
You cannot include a call-out inside a table.
To insert a line break in a call-out, separate paragraphs with blank lines like this:
Don’t use the HTML <br /> tag to split call-outs. Don’t stack multiple call-outs directly after each other.
Markdownlint’s link and image checks (MD034, MD045, MD051, MD052, MD053) don’t look inside HTML/JSX tags like <Note>, <Tip>, <Warning>, or <Danger>. Links and images inside call-outs are still caught by mint validate, but not by markdownlint.
.vale.ini has folder-scoped overrides for contribute/: Microsoft.Contractions is off, since contractions are allowed here, and Microsoft.GeneralURL is off, since URL is the correct term for this technical audience rather than address. Separately, a BlockIgnores pattern excludes raw MDX import ... from "..."; lines, including inside fenced ```mdx examples, from Microsoft.Semicolon. Without it, Vale parses the JS import statement as an English sentence.

​
Headings

  • 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.

​
HTML

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. Exceptions:
  • Use <br /> to break a line in table cells. Do not force line breaks within paragraphs.
  • Download links, for example, <a href="/downloads/mirroredtables.docx" download>Mirrored Tables document</a>.
  • Use <details> and <summary> to create drop-down content.
  • Use <script> to bring in SuperOffice forms.
  • Use <i> with Phosphor classes for icons. Always set aria-label or aria-hidden="true".

​
Images

You can use either .png or .jpg images. Image files must be less than 20 MB. Place images in the appropriate media sub folder. Reference images with a root-relative path: /media/loc/en/{topic}/{filename} (or /media/loc/en/{topic}/{subfolder}/{filename} for topics large enough to need one). Unlike page links, images are always root-relative, with no same-topic exception: the media folder is one shared location, not duplicated per language or per topic, so there’s no “close by” case to be relative to, and a root-relative path resolves the same way no matter which page, or which language’s translated include, references it. Format: ![Alt text](path) Example:

​
Reference-style images

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 Inline:
Reference section at the end of the file:
We prefix all labels referring to images with img.

​
Screenshots

All screenshots are styled with a green frame like this: Example image styling -screenshot To produce this effect, add the string ” -screenshot” at the end of the alt tag:

​
App screens

Mobile app screenshots use a height-constrained frame instead of the full-width screenshot frame, since phone screens are tall and narrow: Allow call identification -app-screen To produce this effect, add the string ” -app-screen” at the end of the alt tag:
Use -app-screen for screenshots of the Mobile CRM app. Use -screenshot for desktop or browser screenshots.

​
Icons

We use Phosphor icons in the documentation. Browse the available icons on Phosphor Icons. Use the <i> tag with the ph base class and the icon name:
You can style icons with i.ph. The VS Code Markdown preview loads .vscode/markdown.css, which imports the Phosphor icon font so icons render while you edit. Don’t put an icon on an H1. The page H1 is hidden from view (the title already shows in the page header), but the heading text (icon markup included) still feeds the “On this page” sidebar, where it would show up as raw tag text instead of a rendered icon.

​
Accessibility

Always set either aria-label or aria-hidden="true" on every icon.
  • Use aria-label when the icon replaces a visible UI label or carries meaning on its own.
  • Use aria-hidden="true" when the icon is decorative, or when nearby text already names the action.

​
Videos

Embed a YouTube video by wrapping an <iframe> in a <Frame> component, using the no-cookie embed URL:
See Mintlify’s video embed docs for the full reference, including hosting your own video files instead of YouTube.

​
Snippets

One of the core principles of software development is DRY (Don’t Repeat Yourself). It applies to documentation too. If you find yourself repeating the same content in multiple places, create a snippet to keep it in sync. A snippet is a Markdown file placed in a folder named snippets: either next to the pages that use it, for content shared within one topic, or at the repository root, /snippets, for content shared across many topics or languages. Both levels use the same folder name; what differs is where the folder sits, not what it’s called.

​
Snippets syntax

Import the file at the top of the page, below the front matter, then reference it as a component wherever it should appear:
  • The import path (the string after from) is a JSX import, not a content link: it stays a literal relative path to the file (for example, ./snippets/foo.md), regardless of the root-relative rule for content links described below.
  • The component name (Foo above) can be anything valid as a JSX identifier: pick something that describes the content.
  • You can import and use the same component more than once on a page.
Here are requirements and considerations for snippet files.

​
Guidelines

  • Write all the text in a snippet as complete sentences or phrases. Avoid creating a dependency on preceding text or following text on the page that references it.
  • Don’t nest snippets.
  • Place images used by a snippet in the shared media folder like any other image, and reference them with a root-relative path.
  • Don’t add metadata or HTML comments at the top of a snippet file.
  • A relative link inside a snippet resolves against the snippet’s own location, not the page that imports it, so a topic-local snippet can follow that topic’s normal relative-link rule, but a repository-root snippet reused across different topics or languages should use root-relative links, since it has no single “close by” tree to be relative to. See page links for the general rule.

​
Local versus repository-root snippets

Reused only within one topic or section? Put it in that topic’s own snippets folder. Reused across multiple topics, sections, or languages? Put it in the repository-root /snippets folder instead. Because both levels share the same folder name, the way to tell them apart is the import path’s relative depth: ./snippets/... or ../snippets/... points to a topic-local folder close by; a longer chain like ../../../snippets/... reaching all the way to the repository root points to the shared one. When in doubt, check where the path actually resolves.

​
Naming conventions

Name a snippet file for what it is, not for what page uses it: that’s what keeps it reusable. Existing snippets follow a small set of prefixes:
  • req-: a plan or feature requirement (req-cep.mdx)
  • note-: a <Note> callout (note-req-saint.mdx)
  • warn-: a <Warning> callout (warn-company-table.mdx)
  • lim-: a limitation (lim-starter.mdx)
  • table-: a reference table (table-misc.md)
  • tip-: a <Tip> callout
  • step- / goto-: a UI navigation step
See Files and folders for the .md versus .mdx extension rule.

​
The /snippets subfolders

The repository-root /snippets folder has a few subfolders, each holding a group of related fragments reused the same way:
  • /snippets/license: plan and license requirement blurbs. Sourced by English content directly; da, de, nl, no, and sv each have their own translated equivalents instead of importing this folder: see the next section for why.
  • /snippets/merge-field, /snippets/variable, and /snippets/functional-rights: reference tables of literal system-defined names (merge-field tags, template variables, functional right names), imported identically by all 6 languages. This is the repository-root pattern working as intended.
There’s no /snippets/release-notes folder today: release notes live at the top-level /release-notes folder, unrelated to /snippets. Create a new subfolder when you have multiple related fragments reused the same way (mirroring license, merge-field, or variable). A single one-off fragment goes directly at the /snippets root instead.

​
Why license snippets exist per language

English’s plan and license snippets live at /snippets/license. Each of da, de, nl, no, and sv has its own language-root snippets folder (for example de/snippets) holding translated equivalents of the same fragments, but not all of them exist in every language yet. This split is deliberate, not a bug: translated text can’t live in one shared, root-relative file the way a language-agnostic reference table can: each language needs its own wording. But nothing enforces parity between the English source and the translated copies: that’s exactly how 3 files ended up untranslated in all 5 languages. When you add a new file to /snippets/license, also add (or file a translation task for) the matching file in each language’s own snippets folder. Contrast this with /snippets/functional-rights: the table lists literal permission names defined by the SuperOffice product itself, not translatable prose, so there’s nothing to translate accurately without duplicating the product’s own (English) terminology. Each language’s page imports the one English table directly and adds a translated <Note> explaining why: see issue #244 for the case that established this pattern. For information about the syntax for links, see How to use links in docs.

​
Lists

  • 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 (without breaking the continuity of the list), indent that content 4 spaces relative to the list item it belongs to. Exception: if the child list is the same type as its parent (numbered inside numbered, or bulleted inside bulleted), indent it 2 spaces instead.

​
Metadata (front-matter)

We use Yaml key-value front-matter syntax to embed metadata in Markdown files.
The frontmatter date format is MM.DD.YYYY. For example, date: 11.30.2025

​
Source code

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.

​
Exceptions

  • 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_function without escaping. However, leading and trailing underscores require it: \_my_function.

​
Tables

  • 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:

​
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:
    • paragraphs
    • headings
    • lists
    • tables
    • images
  • 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: