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

# DocFx to Mintlify cheat sheet

> Quick before-and-after examples for contributors updating content from DocFx-era formatting to Mintlify-compatible formatting.

Use this page as a quick reference when updating older content to current SuperOfficeDocs conventions.

For the full rules, see the [Markdown guide][1], [How to use links in docs][2], [How to include code in docs][3], and [Metadata (YAML front-matter)][4].

## Callouts

**Before (DocFx):**

```md theme={null}
> [!NOTE]
> This is important.
```

**After (Mintlify):**

```mdx theme={null}
<Note>
This is important.
</Note>
```

Also use `<Tip>`, `<Warning>`, and `<Danger>`.

## Includes

**Before (DocFx):**

```md theme={null}
[!include[foo](./includes/foo.md)]
```

**After (Mintlify):**

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

<Foo />
```

## Code snippets

**Before (DocFx range include):**

```md theme={null}
[!code-csharp[CS](file.cs?range=1,3)]
```

**After (Mintlify):**

Use a fenced code block directly, or include a whole `.md` or `.mdx` sample file.

```csharp theme={null}
Console.WriteLine("Hello");
```

## Tabs

**Before (DocFx):**

```md theme={null}
## [REST](#tab/rest)
content
## [SOAP](#tab/soap)
content
***
```

**After (Mintlify):**

```mdx theme={null}
<Tabs>
<Tab title="REST">
content
</Tab>

<Tab title="SOAP">
content
</Tab>
</Tabs>
```

## Expand/collapse sections

**Before:**

```html theme={null}
<details><summary>Title</summary>
Content
</details>
```

**After:**

```mdx theme={null}
<Accordion title="Title">
Content
</Accordion>
```

## Video embeds

**Before:**

```md theme={null}
[!Video https://www.youtube.com/embed/VIDEO_ID]
```

**After:**

```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>
```

## Links between docs pages

* Use `/` in paths.
* Remove `.md` and `.mdx` from link targets.
* Use relative links inside the same topic.
* Use root-relative links only when crossing topic or language boundaries.

**Before:**

```md theme={null}
[Metadata](./metadata.mdx)
```

**After:**

```md theme={null}
[Metadata](./metadata)
```

## Anchors

**Preferred on headings:**

```md theme={null}
## My heading {#my-heading}
```

Link to it like this:

```md theme={null}
[Jump](#my-heading)
```

Use `<a id="..."></a>` only when anchoring non-heading content.

## Xref links

**Before:**

```md theme={null}
<xref:some.uid>
```

**After:**

Use a normal markdown link instead.

## Forms

**Before:**

```html theme={null}
<script src="...superoffice...form..."></script>
```

**After:**

```mdx theme={null}
<SOForm scriptUrl="..." />
```

## .md vs .mdx

Use `.mdx` whenever the page contains:

* component tags such as `<Note>`, `<Tabs>`, or `<Accordion>`
* `import ... from ...`

Use `.md` for plain markdown-only content.

## Frontmatter essentials

Keep frontmatter complete and current:

* `uid`
* `title`
* `description`
* `keywords`
* `author`
* `date`
* `content_type`
* `language`

## Stop doing this

* Don't use DocFx callout, include, tab, or code-include syntax.
* Don't link to `.md` or `.mdx` files directly.
* Don't use `xref`.
* Don't rely on HTML comments for lint suppression in MDX.
* Don't use page-relative image paths; use root-relative `/media/loc/...` paths.

[1]: ./index

[2]: ./links-in-docs

[3]: ./code-in-docs

[4]: ./metadata