Better Data

DEPLOYMENT

Documentation Site Deployment Guide

Edit this page

Documentation Site Deployment Guide

This documentation site is built with Mintlify and can be deployed to docs.betterdata.co.

Prerequisites

  1. Mintlify Account: Sign up at mintlify.com
  2. GitHub Repository: Documentation should be in a Git repository
  3. Domain: Configure DNS for docs.betterdata.co

Local Development

1. Install Mintlify CLI

1npm install -g mintlify

2. Run Local Server

1cd docs-site
2mintlify dev

The docs will be available at http://localhost:3000

3. Preview Changes

Mintlify automatically reloads when you edit .mdx files.

Deployment

Step 1: Connect Repository

  1. Go to mintlify.com/dashboard
  2. Click "New Site"
  3. Connect your GitHub repository
  4. Select the docs-site directory

Step 2: Configure Domain

  1. In Mintlify dashboard, go to Settings → Domain
  2. Add custom domain: docs.betterdata.co
  3. Copy the CNAME record

Step 3: Update DNS

Add CNAME record to your DNS provider:

1Type: CNAME
2Name: docs
3Value: cname.mintlify.com

Step 4: Deploy

Push to main branch:

1git add docs-site/
2git commit -m "Add documentation site"
3git push origin main

Mintlify automatically deploys on push!

Option 2: Self-Hosted

Build Static Site

1cd docs-site
2mintlify build

This generates a _site directory with static HTML.

Deploy to Vercel

1npm install -g vercel
2vercel --prod

Deploy to Netlify

1npm install -g netlify-cli
2netlify deploy --prod --dir=_site

Configuration

Update mint.json

Replace placeholder values:

1{
2  "name": "Better Data LLM Gateway",
3  "logo": {
4    "dark": "/logo/dark.svg",
5    "light": "/logo/light.svg"
6  },
7  "favicon": "/favicon.svg",
8  "colors": {
9    "primary": "#4F46E5"
10  },
11  "topbarCtaButton": {
12    "name": "Get Started",
13    "url": "https://app.betterdata.io/signup"
14  }
15}

Add Logo Files

  1. Create docs-site/logo/ directory
  2. Add dark.svg (for dark mode)
  3. Add light.svg (for light mode)
  4. Add favicon.svg (browser favicon)

Configure Analytics

Update Google Analytics ID:

1{
2  "analytics": {
3    "ga4": {
4      "measurementId": "G-YOUR-ACTUAL-ID"
5    }
6  }
7}

Replace with actual URLs:

1{
2  "footerSocials": {
3    "github": "https://github.com/llm-commerce-gateway/llm-commerce-gateway",
4    "discord": "https://discord.gg/betterdata",
5    "twitter": "https://x.com/betterdatainc"
6  }
7}

Directory Structure

1docs-site/
2├── mint.json              # Main configuration
3├── getting-started/       # Getting started guides
4│   ├── introduction.mdx
5│   ├── quickstart.mdx
6│   ├── concepts.mdx
7│   └── ...
8├── guides/               # Integration guides
9│   ├── claude-mcp.mdx
10│   ├── chatgpt.mdx
11│   └── ...
12├── integrations/         # Platform integrations
13│   ├── shopify.mdx
14│   ├── square.mdx
15│   └── ...
16├── hosted/              # Hosted features
17│   ├── overview.mdx
18│   ├── analytics.mdx
19│   └── ...
20├── reference/           # API reference
21│   └── ...
22├── api-reference/       # REST API docs
23│   └── ...
24└── images/             # Assets
25    ├── logo/
26    └── screenshots/

Writing Documentation

Page Frontmatter

Every .mdx file should start with frontmatter:

1---
2title: 'Page Title'
3description: 'Brief description for SEO'
4icon: 'rocket'  # Optional icon
5---

Components

Mintlify provides built-in components:

Cards

1<CardGroup cols={2}>
2  <Card
3    title="Feature"
4    icon="star"
5    href="/link"
6  >
7    Description
8  </Card>
9</CardGroup>

Code Blocks

1<CodeGroup>
2 
3\`\`\`typescript TypeScript
4const example = 'code';
5\`\`\`
6 
7\`\`\`python Python
8example = "code"
9\`\`\`
10 
11</CodeGroup>

API Endpoints

1---
2title: 'Endpoint Name'
3api: 'GET /v1/endpoint'
4---
5 
6<ParamField query="param" type="string">
7  Parameter description
8</ParamField>
9 
10<ResponseField name="field" type="string">
11  Response field description
12</ResponseField>

Callouts

1<Note>
2  This is a note
3</Note>
4 
5<Warning>
6  This is a warning
7</Warning>
8 
9<Tip>
10  This is a tip
11</Tip>

SEO Optimization

Meta Tags

Add to mint.json:

1{
2  "metadata": {
3    "og:image": "https://docs.betterdata.co/og-image.png",
4    "twitter:site": "@betterdatainc"
5  }
6}

Sitemap

Mintlify automatically generates:

  • sitemap.xml
  • robots.txt

Search Optimization

Enable Algolia search (optional):

1{
2  "search": {
3    "prompt": "Search documentation..."
4  }
5}

Maintenance

Update Documentation

  1. Edit .mdx files in docs-site/
  2. Commit and push to GitHub
  3. Mintlify auto-deploys in ~30 seconds

Add New Pages

  1. Create .mdx file in appropriate directory
  2. Add to navigation in mint.json
  3. Commit and push

Monitor Analytics

View docs analytics in Mintlify dashboard:

  • Page views
  • Popular pages
  • Search queries
  • User feedback

Troubleshooting

Build Errors

1# Check for syntax errors
2mintlify dev
3 
4# Validate mint.json
5mintlify validate

Ensure all pages in mint.json navigation exist:

1# Check for missing files
2find docs-site -name "*.mdx" | sort

CNAME Not Working

  1. Verify DNS propagation: dig docs.betterdata.co
  2. Check CNAME points to cname.mintlify.com
  3. Wait 24-48 hours for DNS propagation

Resources

Ready to deploy! 🚀

Your documentation site will be live at https://docs.betterdata.co