Mintlify Wiki — Layout & Structure Reference

How the live wiki at internal-wiki.xoxoday.com is laid out: navigation structure, where each menu/widget sits, sidebar behaviour, footer layout, and AI assistant placement. Use this to replicate the same structure in a different Mintlify documentation project.

For the visual styling (custom CSS, hover galleries, dot-grid background), see style.css at repo root.

1. Page-level layout — what sits where

Mintlify’s default chrome with our customizations. The wiki uses a 3-column layout on desktop:

┌──────────────────────────────────────────────────────────────────────────┐
│  [Logo]      [Search bar  /  Ask AI]              [Theme toggle]  [User] │  ← Top navbar
├────────────────┬───────────────────────────────────────┬─────────────────┤
│                │                                       │                 │
│  Left          │  Main content                         │  Right TOC      │
│  sidebar       │  (the actual page)                    │  (auto-built    │
│  (nav tree)    │                                       │   from h2/h3    │
│                │                                       │   on page)      │
│                │                                       │                 │
│                │  [Previous page]   [Next page]        │                 │
├────────────────┴───────────────────────────────────────┴─────────────────┤
│  Footer: socials + Feedback + Quick Links columns                        │
└──────────────────────────────────────────────────────────────────────────┘

On mobile, the left sidebar collapses behind a hamburger; the right TOC disappears entirely.

Configured in docs.json → logo and navbar.

Position	Element	Source
Top-left	Logo (light/dark variants)	`logo.light` = `/logo/light.svg`, `logo.dark` = `/logo/dark.svg`
Top-center	Search bar (with “Ask AI” option built in)	Mintlify default (Pro/Enterprise)
Top-right	Theme toggle (light/dark)	Mintlify default
Top-right	(Optional) Navbar links — currently empty	`navbar.links: []`

Currently navbar.links is empty. If you want extra buttons in the top-right (e.g. “Dashboard”, “Sign up”), add them like:

"navbar": {
  "links": [
    { "label": "Dashboard", "href": "https://..." }
  ]
}

No top tabs. Mintlify supports a tabs strip immediately below the navbar (for splitting docs into “Guides / API Reference / Changelog” etc.). We don’t use it. The wiki’s structure lives entirely in the left sidebar.

The sidebar is built from docs.json → navigation.groups. 6 top-level groups in this order:

┌─ Getting started
│    └─ Home (index.mdx)
│
├─ Company
│    ├─ About
│    ├─ Values
│    ├─ Leadership
│    ├─ Offices
│    ├─ Interesting Facts
│    └─ ▾ Teams                          (nested sub-group)
│         ├─ Overview
│         ├─ Sales
│         ├─ Marketing
│         ├─ Product & Design
│         ├─ Tech & QA
│         ├─ Customer Success
│         ├─ Customer Care
│         ├─ Finance & Legal
│         ├─ InfoSec
│         ├─ Implementation
│         └─ Catalog
│
├─ Products
│    ├─ Products Overview
│    ├─ ▾ Empuls
│    │    ├─ Overview, Features, GTM, Competitors, Case Studies, Demo Library
│    ├─ ▾ Plum
│    │    ├─ Overview, Features, GTM, Competitors, Case Studies, FAQs
│    └─ ▾ Loyalife
│         └─ Overview, GTM, Competitors
│
├─ People
│    ├─ Overview
│    ├─ Org Chart
│    ├─ ▾ Onboarding (8 pages, see Onboarding Hub for full list)
│    ├─ ▾ Hiring & talent
│    │    └─ Hiring, Internships
│    ├─ ▾ Goals & KPIs
│    │    ├─ KPIs Hub
│    │    └─ 12 department-level pages
│    └─ ▾ Learning & development
│         ├─ Skill Grid
│         └─ ▾ Xoxo Academy                (nested 2 levels deep)
│              ├─ Landing
│              ├─ Introduction to Xoxoday
│              ├─ AI Literacy
│              ├─ Plum / Loyalife / Empuls
│              ├─ Partnerships
│              └─ Product Deep Dives
│
├─ Assets for Sales & Marketing
│    ├─ GTM Overview
│    ├─ ▾ Asset Library
│    │    └─ Landing, Empuls, Plum, Loyalife, Xoxoday
│    ├─ ▾ Marketing
│    │    └─ Case Studies, Decks & One-pagers, Brand Guidelines, Founder Images
│    └─ ▾ Sales
│         └─ SDR Calling Process, Objection Handling
│
└─ FAQs
     ├─ RFP Overview
     ├─ ▾ RFP Attachments
     │    └─ Hub, Xoxoday, Empuls, Plum, Loyalife
     ├─ ▾ Empuls           (with 3-level deep nesting for sub-modules)
     │    ├─ General Overview
     │    ├─ ▾ Rewards & Recognition (6 pages)
     │    ├─ ▾ Employee Engagement (2 pages)
     │    ├─ ▾ Platform Administration (4 pages)
     │    ├─ Reporting, Integrations, Security, Tech, etc.
     │    └─ ▾ Sales Incentive (12 pages)
     ├─ ▾ Plum             (similar structure with Reward Catalog, Rewards Distribution, Merchant Offers sub-groups)
     ├─ ▾ Loyalife         (similar structure with Loyalty Program Design, Rewards & Redemption, etc.)
     └─ ▾ Xoxoday Generic
          └─ Company Overview, Global Ops, Security, Compliance, etc.

Critical setting: "interaction": { "drilldown": false } at the root of docs.json. This makes clicking on a group label (like “Products”) only expand/collapse the group — it does NOT navigate to the first child page. Without this, Mintlify auto-navigates to the first sub-page, which is confusing when users just want to browse.

Nesting depth

1 level (e.g. “Getting started” → home page) — simple list
2 levels (e.g. “Company” → “Teams” → pages) — most common
3 levels (e.g. “FAQs” → “Empuls” → “Rewards & Recognition” → pages) — used for RFP repository where there’s genuine topical hierarchy

Avoid going beyond 3 levels — the sidebar gets hard to scan.

Hidden pages

Some .mdx files exist in the repo but are not in docs.json — they’re stub pages, hidden from the sidebar until content lands. Tracked in STUB_PAGES.md at the repo root. Currently 19 hidden pages (HR policies stubs, sales playbook stubs, etc.).

4. Right sidebar — Table of Contents

Auto-generated by Mintlify from h2 and h3 headings on the current page. No config needed. Shows page sections with click-to-jump anchors. Hidden on mobile and when the page has fewer than 2 headings.

5. AI Assistant (“Ask AI”)

Enabled by default on Pro/Enterprise Mintlify plans. No explicit config in docs.json — Mintlify includes it automatically. Where it appears:

Inside the top-center search bar as an “Ask AI” option (modern Mintlify default)
Can also appear as a contextual menu in the page header (where users can pick “Copy”, “View as Markdown”, “Open in ChatGPT”, “Open in Claude”)

We haven’t customized AI placement; Mintlify’s default behaviour is used. Indexing: The AI uses the wiki’s content as its knowledge base. To explicitly include hidden/stub pages in AI’s index, add to docs.json:

"seo": { "indexing": "all" }

We don’t currently set this — only nav-visible pages are indexed.

6. Search

Top-center of the navbar. Mintlify default — full-text search across all pages. Triggered by Cmd/Ctrl + K or clicking the bar. No config needed. Works out of the box.

7. Theme toggle

Top-right of the navbar. Toggles between light and dark mode. Mintlify default — no config needed. Light mode uses background.color.light = #F7F9FF (frosty blue-white). Dark mode uses background.color.dark = #06182D (deep navy).

Configured in docs.json → footer:

┌─────────────────────────────────────────────────────────────────────────┐
│                                                                         │
│  [LinkedIn] [YouTube] [Instagram]    Feedback           Quick Links     │
│                                       Share feedback      Xoxoday Web   │
│                                       or content         Empuls         │
│                                       suggestion         Plum           │
│                                                          Loyalife       │
│                                                          Refer & Apply  │
└─────────────────────────────────────────────────────────────────────────┘

Left: social icons → LinkedIn, YouTube, Instagram. Center & right: two columns of link groups. Configured as:

"footer": {
  "socials": {
    "linkedin": "https://linkedin.com/company/...",
    "youtube": "https://youtube.com/c/...",
    "instagram": "https://instagram.com/..."
  },
  "links": [
    {
      "header": "Feedback",
      "items": [
        { "label": "Share feedback...", "href": "mailto:..." }
      ]
    },
    {
      "header": "Quick Links",
      "items": [
        { "label": "Website", "href": "..." },
        { "label": "Empuls", "href": "..." },
        ...
      ]
    }
  ]
}

9. Article-level UI elements (Mintlify defaults)

These appear inside the main content area, automatically:

Element	Where	How to control
Breadcrumbs	Top of main content (above page H1)	Auto from the nav path
H1 (page title)	Top of main content	From frontmatter `title:`
Page description	Below H1, slightly greyed	From frontmatter `description:`
Previous / Next page nav	Bottom of main content	Auto from `docs.json` nav order
”Was this page helpful?” feedback	Bottom of page	Mintlify default

10. Background and theming (visual chrome)

Configured in docs.json:

"background": {
  "decoration": "gradient",
  "color": {
    "light": "#F7F9FF",
    "dark": "#06182D"
  }
}

decoration: "gradient" → adds a soft top-edge gradient glow (Mintlify built-in)
color.light / color.dark → base background colours for each theme

On top of this, style.css adds a subtle dot-grid pattern via CSS — only visible if style.css is loaded (Pro plan custom CSS feature). Brand colour scheme:

"colors": {
  "primary": "#0A51E8",   // links, buttons, active states
  "light":   "#3B82F6",   // hover / softer brand variants
  "dark":    "#1D4ED8"    // darker brand accents
}

Used by Mintlify for links, CTA buttons, active sidebar items.

11. Replicating this layout in a new wiki

Copy these files first:

docs.json          ← all navigation, footer, theme config
favicon.png        ← top-left icon (browser tab)
logo/light.svg     ← top-left logo (light mode)
logo/dark.svg      ← top-left logo (dark mode)
style.css          ← optional, visual extras (Pro plan)

Then in docs.json, swap these brand-specific bits:

Field	Current value	Replace with
`name`	`"Xoxoday Internal Wiki"`	new wiki name
`colors.primary/light/dark`	`#0A51E8 / #3B82F6 / #1D4ED8`	new brand hex codes
`background.color.light/dark`	`#F7F9FF / #06182D`	new page background hex
`navigation.groups`	the 6 groups above	your section structure
`footer.socials`	LinkedIn/YouTube/Instagram URLs	your org’s socials
`footer.links`	Feedback + Quick Links groups	your footer links
`logo.light/dark`	SVG paths	your brand logos

Keep these settings as-is for consistent UX behaviour:

Field	Value	Why
`theme`	`"mint"`	Standard Mintlify theme
`interaction.drilldown`	`false`	Sidebar groups expand-only (no auto-navigate)
`background.decoration`	`"gradient"`	Top-edge gradient glow

12. Patterns we follow for new pages

When adding a new section to the wiki, the consistent layout is: Sidebar nesting rule: 1–2 levels deep is best. Go to 3 levels only when there’s a real categorical hierarchy (like the RFP repository’s product → module → topic structure). Hub-page pattern: Whenever a section has more than ~4 pages, create a landing/hub page first that summarises each sub-page in 3-4 lines with a link. Used on:

Onboarding Hub (/onboarding/overview)
Asset Library (/asset-library)
RFP Attachments (/rfp-attachments)
KPIs Hub (/people/kpis)
Xoxo Academy (/people/learning/xoxo-academy)

Stub page pattern: Pages that are work-in-progress get a <Info>**Stub** ...</Info> banner at the top and are removed from docs.json nav until content lands. Tracked in STUB_PAGES.md. Cross-section linking: Use absolute paths like /asset-library/empuls (relative to wiki root). Mintlify resolves these correctly.

13. Quick reference: every Mintlify config key we use

{
  "theme": "mint",
  "name": "Wiki Name",
  "colors": { "primary", "light", "dark" },
  "favicon": "/favicon.png",
  "background": {
    "decoration": "gradient",
    "color": { "light", "dark" }
  },
  "interaction": { "drilldown": false },
  "navigation": { "groups": [...] },
  "logo": { "light", "dark" },
  "navbar": { "links": [] },
  "footer": {
    "socials": { "linkedin", "youtube", "instagram" },
    "links": [ { "header", "items": [...] } ]
  }
}

That’s the complete set. Everything else (search, AI assistant, theme toggle, TOC, breadcrumbs, prev/next nav, “Was this helpful?”) is Mintlify’s default and needs no config.

UI REPLICATION GUIDE

Mintlify Wiki — Layout & Structure Reference

1. Page-level layout — what sits where

2. Top navbar

3. Left sidebar — the actual navigation structure

Sidebar interaction

Nesting depth

Hidden pages

4. Right sidebar — Table of Contents

5. AI Assistant (“Ask AI”)

6. Search

7. Theme toggle

8. Footer

9. Article-level UI elements (Mintlify defaults)

10. Background and theming (visual chrome)

11. Replicating this layout in a new wiki

12. Patterns we follow for new pages

13. Quick reference: every Mintlify config key we use

​Mintlify Wiki — Layout & Structure Reference

​1. Page-level layout — what sits where

​2. Top navbar

​3. Left sidebar — the actual navigation structure

​Sidebar interaction

​Nesting depth

​Hidden pages

​4. Right sidebar — Table of Contents

​5. AI Assistant (“Ask AI”)

​6. Search

​7. Theme toggle

​8. Footer

​9. Article-level UI elements (Mintlify defaults)

​10. Background and theming (visual chrome)

​11. Replicating this layout in a new wiki

​12. Patterns we follow for new pages

​13. Quick reference: every Mintlify config key we use

Mintlify Wiki — Layout & Structure Reference

1. Page-level layout — what sits where

2. Top navbar

3. Left sidebar — the actual navigation structure

Sidebar interaction

Nesting depth

Hidden pages

4. Right sidebar — Table of Contents

5. AI Assistant (“Ask AI”)

6. Search

7. Theme toggle

8. Footer

9. Article-level UI elements (Mintlify defaults)

10. Background and theming (visual chrome)

11. Replicating this layout in a new wiki

12. Patterns we follow for new pages

13. Quick reference: every Mintlify config key we use