wiki/content/pages/docs-deployment.md at 7a8a1c61e39057fc75d93e2072a4ffa01cff6a43

x/wiki

mirror of https://github.com/waynesutton/markdown-site.git synced 2026-01-12 04:09:14 +00:00

Files

Wayne Sutton 5a8df46681 feat: Add semantic search with vector embeddings

Add vector-based semantic search to complement keyword search.
  Users can toggle between "Keyword" and "Semantic" modes in the
  search modal (Cmd+K, then Tab to switch).

  Semantic search:
  - Uses OpenAI text-embedding-ada-002 (1536 dimensions)
  - Finds content by meaning, not exact words
  - Shows similarity scores as percentages
  - ~300ms latency, ~$0.0001/query
  - Graceful fallback if OPENAI_API_KEY not set

  New files:
  - convex/embeddings.ts - Embedding generation actions
  - convex/embeddingsQueries.ts - Queries/mutations for embeddings
  - convex/semanticSearch.ts - Vector search action
  - convex/semanticSearchQueries.ts - Result hydration queries
  - content/pages/docs-search.md - Keyword search docs
  - content/pages/docs-semantic-search.md - Semantic search docs

  Changes:
  - convex/schema.ts: Add embedding field and by_embedding vectorIndex
  - SearchModal.tsx: Add mode toggle (TextAa/Brain icons)
  - sync-posts.ts: Generate embeddings after content sync
  - global.css: Search mode toggle styles

  Documentation updated:
  - changelog.md, TASK.md, files.md, about.md, home.md

  Configuration:
  npx convex env set OPENAI_API_KEY sk-your-key

  Generated with [Claude Code](https://claude.com/claude-code)

  Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

  Status: Ready to commit. All semantic search files are staged. The TypeScript warnings are pre-existing (unused variables) and don't affect the build.

2026-01-05 18:30:48 -08:00

3.1 KiB

Raw Blame History

title, slug, published, order, showInNav, layout, rightSidebar, showFooter, docsSection, docsSectionOrder, docsSectionGroup, docsSectionGroupIcon

title	slug	published	order	showInNav	layout	rightSidebar	showFooter	docsSection	docsSectionOrder	docsSectionGroup	docsSectionGroupIcon
Deployment	docs-deployment	true	6	false	sidebar	true	true	true	6	Setup	Rocket

Deployment

Netlify setup

Connect GitHub repo to Netlify
Build command: npm ci --include=dev && npx convex deploy --cmd 'npm run build'
Publish directory: dist
Add env variables:
- CONVEX_DEPLOY_KEY (from Convex Dashboard > Project Settings > Deploy Key)
- VITE_CONVEX_URL (your production Convex URL, e.g., https://your-deployment.convex.cloud)

Both are required: deploy key for builds, URL for edge function runtime.

Convex production

npx convex deploy

Edge functions

RSS, sitemap, and API routes are handled by Netlify Edge Functions in netlify/edge-functions/. They dynamically read VITE_CONVEX_URL from the environment. No manual URL configuration needed.

Convex schema

// convex/schema.ts
export default defineSchema({
  posts: defineTable({
    slug: v.string(),
    title: v.string(),
    description: v.string(),
    content: v.string(),
    date: v.string(),
    published: v.boolean(),
    tags: v.array(v.string()),
    readTime: v.optional(v.string()),
    image: v.optional(v.string()),
    excerpt: v.optional(v.string()), // For card view
    featured: v.optional(v.boolean()), // Show in featured section
    featuredOrder: v.optional(v.number()), // Order in featured (lower = first)
    authorName: v.optional(v.string()), // Author display name
    authorImage: v.optional(v.string()), // Author avatar image URL
    lastSyncedAt: v.number(),
  })
    .index("by_slug", ["slug"])
    .index("by_published", ["published"])
    .index("by_featured", ["featured"]),

  pages: defineTable({
    slug: v.string(),
    title: v.string(),
    content: v.string(),
    published: v.boolean(),
    order: v.optional(v.number()),
    excerpt: v.optional(v.string()), // For card view
    image: v.optional(v.string()), // Thumbnail for featured cards
    featured: v.optional(v.boolean()), // Show in featured section
    featuredOrder: v.optional(v.number()), // Order in featured (lower = first)
    authorName: v.optional(v.string()), // Author display name
    authorImage: v.optional(v.string()), // Author avatar image URL
    lastSyncedAt: v.number(),
  })
    .index("by_slug", ["slug"])
    .index("by_published", ["published"])
    .index("by_featured", ["featured"]),
});

Troubleshooting

Posts not appearing

Check published: true in frontmatter
Run npm run sync for development
Run npm run sync:prod for production
Use npm run sync:all or npm run sync:all:prod to sync content and update discovery files together
Verify in Convex dashboard

RSS/Sitemap errors

Verify VITE_CONVEX_URL is set in Netlify
Test Convex HTTP URL: https://your-deployment.convex.site/rss.xml
Check edge functions in netlify/edge-functions/

Build failures

Verify CONVEX_DEPLOY_KEY is set in Netlify
Ensure @types/node is in devDependencies
Build command must include --include=dev
Check Node.js version (18+)

3.1 KiB Raw Blame History