> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Markdown guide

> This Markdown style guide is intended to ensure that the markup of SuperOfficeDocs has a consistent style, and is easy to navigate and maintain.

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][1] 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*

* Unordered list items
* [link example](https://community.superoffice.com/)

The examples above would look like this in Markdown:

```markdown theme={null}
1. Ordered list items
1. **bold list item**
1. *italic list item*

* Unordered list items
* [link example](https://community.superoffice.com/)
```

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

<Note>
  This is important.
</Note>

The call-out above would look like this in markdown:

```markdown theme={null}

<Note>
This is important.
</Note>

```

If you want to include a call-out in your docs content, the following types are currently supported (see [Mintlify's callout components][8] for the full reference):

```markdown theme={null}

<Note>
Information the user should notice even if skimming.
</Note>

<Tip>
Optional information to help a user be more successful.
</Tip>

<Warning>
Negative potential consequences of an action.
</Warning>

<Danger>
Dangerous certain consequences of an action.
</Danger>

```

And here is something to note about call-outs!

<Note>
  You cannot include a call-out inside a table.
</Note>

To insert a line break in a call-out, separate paragraphs with blank lines like this:

```markdown theme={null}

<Tip>
Paragraph 1.

Paragraph 2.
</Tip>

```

Don't use the HTML `<br />` tag to split call-outs.

Don't stack multiple call-outs directly after each other.

<Note>
  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.
</Note>

<Note>
  `.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.
</Note>

## 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][6], 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:**

```markdown theme={null}
![Image of Yaktocat](https://octodex.github.com/images/yaktocat.png)
```

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

```markdown theme={null}
![Image of Yaktocat][img1]
```

Reference section at the end of the file:

```markdown theme={null}
[img1]: https://octodex.github.com/images/yaktocat.png
```

<Note>
  We prefix all labels referring to images with **img**.
</Note>

### Screenshots

All screenshots are styled with a green frame like this:

![Example image styling -screenshot][img1]

To produce this effect, add the string " -screenshot" at the end of the alt tag:

```markdown theme={null}
![Alt text -screenshot][img1]
```

### 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][img2]

To produce this effect, add the string " -app-screen" at the end of the alt tag:

```markdown theme={null}
![Alt text -app-screen][img2]
```

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][11].

Use the `<i>` tag with the `ph` base class and the icon name:

```html theme={null}
<i class="ph ph-split-horizontal" aria-hidden="true"></i>
<i class="ph ph-warning" aria-label="Warning"></i>
```

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:

```mdx theme={null}
<Frame caption="Watch the walk-through">
  <iframe
    width="100%"
    height="420"
    src="https://www.youtube-nocookie.com/embed/VIDEO_ID"
    title="Watch the walk-through"
    allowfullscreen
  ></iframe>
</Frame>
```

See [Mintlify's video embed docs][9] 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:

```mdx theme={null}
import Foo from "./snippets/foo.md";

Text before <Foo /> and after.
```

* 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][10]: 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][12] 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][6] 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][13] 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][14]. 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][15] for the case that established this pattern.

## Links

For information about the syntax for links, see [How to use links in docs][6].

## 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][5] in Markdown files.

<Note>
  The frontmatter date format is MM.DD.YYYY. For example, `date: 11.30.2025`
</Note>

## Source code

For information about the syntax for source code, see [How to include code in docs][7].

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

| Character | Description         |
| --------- | ------------------- |
| \\        | backslash           |
| \`        | backtick            |
| \*        | asterisk (star)     |
| \_        | underscore          |
| \{}       | curly braces        |
| \[]       | square brackets     |
| ()        | parentheses         |
| #         | hash mark           |
| +         | plus sign           |
| -         | minus sign (hyphen) |
| .         | dot (period)        |
| !         | exclamation mark    |

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

| default (left) |     centered    | right |
| -------------- | :-------------: | ----: |
| corn           | (winter) squash | beans |

The table above would look like this in markdown:

```markdown theme={null}
| 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:
  * 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>.

## Helpful links

Here are a few resources to help with Markdown to help get you started:

* [Markdown guide][2] with examples and formatting info
* [Dillinger.io][3] is an online Markdown tool that can help convert HTML to Markdown and to work with Markdown
* Here's a helpful [Markdown plugin for Visual Studio Code][4]

[1]: ../style-guide/index

[2]: https://www.markdownguide.org/getting-started/

[3]: https://dillinger.io/

[4]: https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one

[5]: ./metadata

[6]: ./links-in-docs

[7]: ./code-in-docs

[8]: https://www.mintlify.com/docs/components/callouts

[9]: https://www.mintlify.com/docs/create/image-embeds#youtube-embeds

[10]: https://developer.mozilla.org/en-US/docs/Glossary/Identifier

[11]: https://phosphoricons.com/

[12]: ../files-and-folders#media-folder

[13]: ../files-and-folders#file-names-and-file-extensions

[14]: https://github.com/SuperOfficeDocs/docs/issues/235

[15]: https://github.com/SuperOfficeDocs/docs/issues/244

[img1]: /media/loc/en/contribute/plain-action-buttons.png

[img2]: /media/loc/en/mobile/allow-call-identification.png