Skip to main content
Use this page as a quick reference when updating older content to current SuperOfficeDocs conventions. For the full rules, see the Markdown guide, How to use links in docs, How to include code in docs, and Metadata (YAML front-matter).

​
Callouts

Before (DocFx):
After (Mintlify):
Also use <Tip>, <Warning>, and <Danger>.

​
Includes

Before (DocFx):
After (Mintlify):

​
Code snippets

Before (DocFx range include):
After (Mintlify): Use a fenced code block directly, or include a whole .md or .mdx sample file.

​
Tabs

Before (DocFx):
After (Mintlify):

​
Expand/collapse sections

Before:
After:

​
Video embeds

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

​
Anchors

Preferred on headings:
Link to it like this:
Use <a id="..."></a> only when anchoring non-heading content. Before:
After: Use a normal markdown link instead.

​
Forms

Before:
After:

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