​

Adspirer Docs Mintlify Audit Report

​

Overview

This is a thorough audit of the Adspirer documentation site built on Mintlify. The audit compares what features you’re currently using against the full set of Mintlify capabilities, identifies issues found by the CLI tools, and provides prioritized recommendations. The Adspirer docs site was built in a single intensive session on February 22nd, 2026, with 28 commits going from zero to a polished, production-ready state. It covers 33 MDX pages across AI clients, ad platforms, agent skills, guides, and a knowledge base.

---

​

CLI Audit Results

​

Build Validation: Passed

The mint validate command completed successfully with no errors.

​

Broken Links: 1 Found

The file knowledge-base/multi-account.mdx contains a broken link to ai-clients/claude with a hash anchor team-enterprise-setup. That anchor does not exist on the Claude page. This needs to be fixed or removed.

​

Accessibility: Issues Found

The primary color, hex 3B82F6, fails WCAG double-A contrast ratio against a light background. The contrast ratio is 3.68 to 1, but the minimum required is 4.5 to 1. The dark color, hex 0F172A, also fails against a dark background with a contrast ratio of only 1.08 to 1. All 34 MDX files passed the alt text check for images and videos. Consider changing the primary color to hex 2563EB or 1D4ED8 to meet accessibility standards.

---

​

Features Currently In Use

Your docs site already uses a strong set of Mintlify features. Here’s what’s working well.

​

Components

Cards, Columns, Steps, Tabs, Accordions, Callouts including Info, Note, Warning, Tip, and Check types. Also Badge, Frame, Tooltip, Prompt, Update for the changelog, Mermaid diagrams, Tables, Code blocks, and Icons.

​

Configuration

You have the maple theme, custom colors, light and dark logos, a custom favicon, dark mode default, 3-tab navigation structure with Documentation, Guides, and Knowledge Base. Global anchors for Blog, MCP Server, and Changelog. Navbar with Book Meeting link and Get Started primary CTA button. Google Analytics 4 integration. Contextual menu with copy, view, ChatGPT, Claude, Perplexity, MCP, Cursor, and VS Code options. SEO with canonical URL and indexing set to all. Footer with social links to Twitter, GitHub, and LinkedIn.

​

AI Features

The llms.txt file, llms-full.txt file, and skill.md file are all auto-generated by Mintlify. The contextual menu for AI tool integration is configured. You also have a mintignore file for excluding draft content.

---

​

Tier 1: Quick Wins with High Value

These are features you should add right away. Each takes just minutes to implement.

​

1. Banner for Site-Wide Announcements

Add a dismissible banner to promote new features, sales, or product updates. This appears at the top of every page. Configure it in docs.json with a banner object containing content text and dismissible set to true. For example, you could announce “New: TikTok Ads support is live!” with a link to the TikTok Ads page.

​

2. Feedback Collection

Enable thumbs up and thumbs down voting on every documentation page. This gives you direct insight into which pages are helpful and which need improvement. Check your Mintlify dashboard, as this may already be enabled by default. You can also enable “Suggest Edit” and “Raise Issue” buttons that link to your GitHub repository.

​

3. URL Redirects

Set up redirects in docs.json to preserve SEO when you rename or move pages. This is critical as your docs grow. Mintlify supports permanent 301 redirects and wildcard patterns. Even if you have none now, set up the empty array so the pattern is ready.

​

4. Custom 404 Error Page

Replace the default error page with a branded one. Configure errors.404 in docs.json with a custom title and description that includes a link back to the docs home page. You can also set redirect to false to show the custom page instead of auto-redirecting.

​

5. Search Prompt Customization

Brand the search experience by adding a custom placeholder text like “Search Adspirer docs…” in the search bar. Configure this with search.prompt in docs.json.

​

6. Page Keywords in Frontmatter

Add keywords to your most important pages to help users find them through search. For example, the Google Ads page could have keywords like google ads, ppc, sem, adwords, and search ads. Add these to at least your top 10 most visited pages.

​

7. Sidebar Titles

Several of your guide pages have long titles that get truncated in the sidebar. Use the sidebarTitle frontmatter field to set shorter display names. For example, “How to Automate Google Ads Campaigns with AI” could show as just “Automate Google Ads” in the sidebar.

​

8. RSS Feed for Changelog

Your changelog already uses Update components, which means Mintlify can generate an RSS feed. Add rss: true to your changelog.mdx frontmatter to activate it. The feed will be available at your changelog URL with rss.xml appended. Promote this so users can subscribe to updates.

​

9. More Reusable Snippets

You only have one snippet file, which is unused boilerplate. Many patterns repeat across your 8 AI client setup pages, such as prerequisites sections, FAQ sections, and call-to-action blocks. Extract these into shared snippets to keep content consistent and easier to maintain.

---

​

Tier 2: Medium Effort, Strong Value

These features require a bit more work but significantly improve the docs experience.

​

10. Tiles Component

Tiles create visual showcase grids with patterned backgrounds. They’re a more visual alternative to Cards and would work well for your AI clients grid on the introduction page.

​

11. Expandables Component

Use Expandables to show and hide detailed content on demand. This would be perfect for the massive 100-plus tools table in agent-skills/tools.mdx. Group tools by category with expandable details instead of one giant table.

​

12. Tree Component

The Tree component displays hierarchical file and directory structures with keyboard navigation. It would be useful on your MCP page to visualize configuration file structures or project layouts.

​

13. Panel Component

The Panel component replaces the right-side table of contents with custom content. Use it to pin important supplementary information, related links, or quick references alongside main content.

​

14. View Component for Conditional Content

The View component shows different content based on user-selected options in a dropdown. You could use this to conditionally render platform-specific instructions, such as showing Google Ads versus Meta Ads examples.

​

15. Custom Fonts

You’re using Mintlify’s default fonts. Custom fonts from Google Fonts strengthen brand identity. Consider using Inter or your brand’s font for both headings and body text.

​

16. Background Decoration

Add visual flair with background decorations. Options include gradient, grid, and windows effects. This can make your docs feel more polished and on-brand.

​

17. Open Graph Thumbnails

Configure custom social sharing images so when someone shares a docs link on Twitter, LinkedIn, or Slack, it shows a branded preview card. Set this up with thumbnails in docs.json.

​

18. Footer Link Columns

Your footer only has social links. Add organized columns with useful links grouped by category, such as Product links like MCP Server and Pricing, and Resources links like Blog and Changelog.

​

19. GEO: Generative Engine Optimization

Mintlify has a dedicated guide for optimizing docs to appear in AI-generated answers from tools like ChatGPT and Perplexity. Since Adspirer is an AI-native product, this is highly relevant. Follow their GEO guide to optimize page structure, descriptions, and content for AI citation.

​

20. Wide Page Mode for Large Tables

Your agent-skills/tools.mdx page has massive tables. Add mode: wide to its frontmatter to remove the table of contents and give more horizontal space.

​

21. Custom CSS with Tailwind

You have zero custom CSS. Tailwind CSS version 3 is built into Mintlify. You could use it to create branded callout styles or fine-tune the visual design of specific elements.

​

22. Custom Scripts

Add JavaScript files for custom tracking, chatbot widgets, or interactive elements. Place any .js file in your content directory and it runs globally on every page.

---

​

Tier 3: Bigger Investment, Plan-Dependent

These features require more significant effort or higher-tier Mintlify plans.

​

23. AI Assistant

The built-in AI chat answers questions from your docs using agentic retrieval-augmented generation. Auto-enabled on Pro and Enterprise plans. Users can access it via a button, keyboard shortcut Command-I, or URL parameters. You can customize its behavior with an Assistant.md file. Especially valuable for your use case since your users are already AI-native.

​

24. Mintlify Agent and Autopilot

This feature monitors your codebase for changes and automatically proposes documentation updates. Given how fast Adspirer iterates, this would keep docs current automatically. Available in the dashboard or via API, with support for GitHub Actions automation. You can customize its behavior with an AGENTS.md file.

​

25. PDF Exports

Let users download your entire documentation as a PDF. Useful for enterprise customers who need offline access or compliance documentation. Available on Enterprise plans.

​

26. Support Widget Integration

Embed Intercom or Front chat widgets directly in your docs so users can get support without leaving the page. Configure with a single app ID in docs.json.

​

27. Additional Analytics Beyond GA4

You only have Google Analytics 4. Consider adding PostHog for product analytics and session replay, Hotjar for heatmaps to see where users click and scroll, Mixpanel for funnel analysis and conversion tracking, or Microsoft Clarity which is free for user behavior analytics.

​

28. Versioning

If your MCP API evolves with breaking changes, you can version your docs. Configure version switching in the global navigation so users can toggle between version 1 and version 2 documentation.

​

29. Internationalization

If you expand internationally, Mintlify supports 18 plus languages with AI-powered translations. It maintains structure, formatting, and links automatically. Translations require PR review before publishing.

​

30. Content Gating and Authentication

If you need to restrict certain documentation to paying customers, Mintlify supports password protection, OAuth, JWT authentication, and group-based access control. You can have public and protected pages coexisting on the same site.

---

​

Implementation Status (Feb 22, 2026)

​

Implemented

​

Additional Changes

​

CLI Results After Implementation

---

​

Summary

Your Adspirer docs site is well-built and uses most of Mintlify’s core components effectively. The biggest gaps were in configuration features like banner, redirects, custom 404 page, and search prompt — these have all been implemented. The medium-effort items like Expandables, Tree, wide mode, and reusable snippets have also been added. Remaining items (Tiles, Panel, View, OG images, custom CSS/scripts) can be tackled as needed. Tier 3 features (AI Assistant, Agent, PDF exports) require the Pro plan. All 33 pages now have enhanced frontmatter with icons, keywords, and sidebar titles. Five reusable snippets are ready for use across pages. The tool catalog uses Expandable sections with inline Badge types for better scanning.