​

NexusFeed Docs Site — Setup Runbook

​

Part 1 — Create the public GitHub repo (5 min)

1. Go to https://github.com/organizations/NexusFeed/repositories/new (assumes you own the NexusFeed org — if not, create it first at https://github.com/organizations/new, free tier is fine).
2. Repository name: nexusfeed-docs
3. Description: Public documentation for NexusFeed — LTL fuel surcharge and ABC liquor license data APIs.
4. Public visibility. No README, no .gitignore, no license (we’ll push a populated repo).
5. Click Create repository.
6. Note the clone URL: https://github.com/NexusFeed/nexusfeed-docs.git

cd "c:/Users/ladou/Documents/B2B Agentic Arbitrage Hub/docs-site"
git init
git add .
git commit -m "Initial docs site — 10 carriers, 5 states, verifiability contract"
git branch -M main
git remote add origin https://github.com/NexusFeed/nexusfeed-docs.git
git push -u origin main

​

Part 2 — Connect the repo to Mintlify (10 min)

1. Go to https://mintlify.com/start and sign in with GitHub.
2. Authorize Mintlify to access the NexusFeed/nexusfeed-docs repository (you can grant access to just that one repo).
3. Mintlify will scan the repo and detect docs.json. It should auto-deploy a preview URL like https://nexusfeed.mintlify.app within 1-2 minutes.
4. Open the preview URL and click through the pages to sanity-check:
   • Home page renders
   • All 10 carrier pages in the sidebar
   • All 5 state pages in the sidebar
   • API Reference tab loads from the live OpenAPI spec
5. If the API Reference tab shows an error, verify https://api.nexusfeed.dev/openapi.json loads directly in a browser. It should. If it doesn’t, Mintlify can’t reach it — check Railway logs and CORS.

​

Part 3 — Connect the custom domain docs.nexusfeed.dev (15 min)

​

3a. In Mintlify

1. Open the Mintlify dashboard for the nexusfeed-docs project.
2. Go to Settings → Custom Domain.
3. Enter docs.nexusfeed.dev.
4. Mintlify will show you a CNAME target, typically cname.vercel-dns.com or cname.mintlify.app — copy this value.

​

3b. In Cloudflare

1. Log into Cloudflare and select the nexusfeed.dev zone.
2. Go to DNS → Records.
3. Click Add record:
   • Type: CNAME
   • Name: docs
   • Target: (the value from Mintlify, e.g. cname.mintlify.app)
   • Proxy status: DNS only (gray cloud) — Mintlify serves its own TLS, so Cloudflare’s proxy isn’t needed and may cause SSL issues
   • TTL: Auto
4. Save.

​

3c. Verify

curl -sI https://docs.nexusfeed.dev | head -n 1

• The custom domain is shown in the address bar
• The TLS certificate is valid (padlock icon)
• All pages load correctly

​

Part 4 — Submit to Google Search Console (10 min)

1. Go to https://search.google.com/search-console and sign in.
2. Click Add property.
3. Choose URL prefix (not Domain) — enter https://docs.nexusfeed.dev.
4. Google will ask you to verify ownership. The easiest method is HTML tag:
   • Copy the meta tag Google gives you (it looks like <meta name="google-site-verification" content="...">).
   • Add it to docs.json under a top-level "metadata" field, or add an index.html override — Mintlify supports custom head tags via a "metadata" block like:
     "metadata": {
       "google-site-verification": "paste_the_content_value_here"
     }
     
   • Commit, push, wait for Mintlify to redeploy (~1 min), then click Verify in Google Search Console.
5. Once verified, go to Sitemaps in the left sidebar.
6. Mintlify auto-generates /sitemap.xml. Enter sitemap.xml and click Submit.
7. Google will show “Success” and begin crawling. First pages usually appear in the index within 48-72 hours.

​

Also submit to Bing Webmaster Tools (5 min, optional but cheap)

1. Go to https://www.bing.com/webmasters.
2. Click Add site → enter https://docs.nexusfeed.dev.
3. Use the Import from Google Search Console option — it auto-verifies using your existing GSC credentials. No separate meta tag needed.
4. Submit the sitemap: https://docs.nexusfeed.dev/sitemap.xml.

​

Part 5 — Sanity-check SEO readiness (5 min)

# Check each of these returns 200 and proper content
curl -sI https://docs.nexusfeed.dev | head -n 1
curl -sI https://docs.nexusfeed.dev/quickstart | head -n 1
curl -sI https://docs.nexusfeed.dev/verifiability | head -n 1
curl -sI https://docs.nexusfeed.dev/carriers/odfl | head -n 1
curl -sI https://docs.nexusfeed.dev/states/california-abc | head -n 1
curl -sI https://docs.nexusfeed.dev/sitemap.xml | head -n 1

• <title> includes “NexusFeed”
• <meta name="description"> is present with a useful description
• OpenGraph tags exist (og:title, og:description, og:image) so social previews render cleanly

​

Part 6 — Write the Show HN post (90-120 min, separate session)

• Title: “Show HN: Scraping 10 LTL carrier fuel surcharges and 5 state liquor license databases into one MCP server”
• Length: 1200-1800 words
• Narrative: lead with the Illinois Akamai bypass story (it’s the best technical anecdote), move into the 10-carrier breakdown, explain the _verifiability contract as the key design decision, close with a “try it” CTA linking to docs.nexusfeed.dev.
• Canonical publish location: Dev.to or your own docs.nexusfeed.dev/blog/... route if you add one.
• Cross-post: Hacker News (Show HN), Lobste.rs, r/programming, r/SideProject, r/webscraping, Indie Hackers milestone.
• Post timing: Tuesday or Wednesday, 8-10am ET. Avoid weekends and late nights.

​

Part 7 — Write and send the 20 cold emails (90-120 min, separate session)

• List source: Apollo free tier or Hunter.io. Target 3PL CTOs, freight broker heads-of-engineering, logistics SaaS founders (Loadsmart, Convoy alumni, Flock Freight alumni), liquor compliance software teams (Provi, Sevenfifty).
• Email format: 4 sentences, not a pitch, a question. Ends with a link to docs.nexusfeed.dev.
• Delivery: Manual sends from personal Gmail. No automation, no sequences.
• Response plan: Reply within 2 hours to any reply.

​

Troubleshooting

​

”Mintlify build failed”

• Invalid JSON in docs.json (trailing commas, unquoted keys)
• A page referenced in navigation.tabs[].groups[].pages that doesn’t exist as an MDX file
• Frontmatter missing from an MDX file (every page needs --- block with title and description)

​

“API Reference tab is empty”

• Railway deploy is healthy (visit https://api.nexusfeed.dev/health)
• CORS allows Mintlify’s origin (should — FastAPI default CORS is permissive for unauthenticated GETs on /openapi.json)

​

“docs.nexusfeed.dev returns 404 but www.docs.nexusfeed.dev works”

​

”Google Search Console says ‘couldn’t verify’”

• The metadata field is at the top level of docs.json, not nested inside navigation
• Mintlify has redeployed since you pushed the change
• View Source on the home page shows the <meta name="google-site-verification" ...> tag

​

Rollback

1. In the Mintlify dashboard → Settings → delete the custom domain docs.nexusfeed.dev.
2. In Cloudflare → DNS → delete the docs CNAME record.
3. The preview URL https://nexusfeed.mintlify.app (or whatever Mintlify assigned) will still work for editing.
4. Re-add the custom domain when ready.