Skip to main content
docs.json’s seo key controls how this site behaves in search engines and in link previews on other platforms (Slack, LinkedIn, and so on). This page covers what’s configured today. Expect it to grow as more of Mintlify’s seo.* options get used.

​
Automatic per-page social previews

Every page automatically gets og:title, og:description, og:image, and matching twitter:* meta tags, with no per-page configuration required. Mintlify renders these directly from that page’s own frontmatter title and description. See Metadata for how those fields are written. Improving a page’s link-preview text is a metadata edit, not an seo setting.

​
Custom background

The auto-generated preview image renders the title and description onto a background image, set once for the whole site:
images/og-background.png is a brand-color gradient with the Hugo mascot placed in the bottom-right corner. Mintlify’s title/description text always renders in the top-left, so Hugo stays clear of it regardless of how long a given page’s title or description is.

​
Canonical URL

canonical is a base domain, not a fixed single URL. Mintlify appends each page’s own path to it automatically.

​
Structured data and organization

Not yet configured. Mintlify can publish a seo.organization block (name, logo, social profiles) that feeds the site’s structured-data graph, separate from the social-preview thumbnails above.

​
Indexing controls

Mintlify generates a standard sitemap.xml and robots.txt automatically, listing only pages included in docs.json’s navigation. Either file can be overridden by placing a same-named file at the project root. There is no per-language variant and no filtering hook beyond that: a hidden page (hidden: true frontmatter) is excluded from both by default unless seo.indexing is added to docs.json. This native sitemap is unrelated to the Userflow sitemap below: one is for search-engine crawling, the other feeds a third-party in-app tool.

​
Userflow’s sitemap

Userflow (the in-app onboarding tool built into the CRM product) has a Resource Center knowledge-base search block per language, each configured with a Knowledge base URL pointed at docs.superoffice.com/learn-<lang>.html. That URL has to keep resolving to a flat list of current help-article links for its language, independent of Mintlify’s own sitemap. Six hidden pages, learn-<lang>.mdx at the repo root, serve this today. Each is a flat <a href='URL'>URL</a><br /> list, matching the legacy DocFx pipeline’s format. Each lists:
  • Every page under that language’s own */learn/* folders
  • Every page anywhere in the repo flagged userflow_index: true in frontmatter (see Metadata): a hand-curated addition for pages outside a learn folder, such as admin/ how-tos. A flagged page with no language prefix (for example integrations/) is treated as shared and appears in every language’s list.
tools/build-learn-sitemaps.py regenerates all six pages from the current content tree and nav config: no dependency on a built site, so it is safe to re-run any time a learn or userflow_index page changes. The old /learn-<lang>.html URLs redirect to the new pages via config/redirects.json, so nothing needs to change in Userflow’s own settings. No scheduled automation regenerates these pages yet, unlike the broken-link-detection automation in Automated tests. Re-run the tool by hand for now.

​
Related content

  • Metadata: the frontmatter fields that feed every page’s automatic social preview, and the userflow_index/hidden properties.
  • Configuring Mintlify: where seo sits inside docs.json’s overall layout.