x/wiki

mirror of https://github.com/waynesutton/markdown-site.git synced 2026-01-11 20:08:57 +00:00

Files

Wayne Sutton 3658c9c93c update: dashbaord siteconfig and Ask AI documentation alignment

2026-01-10 11:55:43 -08:00

10 KiB

Raw Blame History

title, description, date, slug, published, tags, readTime, featured, layout, featuredOrder, blogFeatured, image, excerpt, docsSection, docsSectionOrder, docsSectionGroup, docsLanding

title

description

date

slug

published

How to use the Markdown sync dashboard

The dashboard at /dashboard gives you a centralized interface for managing your markdown blog. You can edit posts, sync content, configure settings, and more without switching between your editor and terminal.

Accessing the dashboard

Navigate to /dashboard in your browser. The dashboard isn't linked in the navigation by default, so you'll access it directly via URL.

Authentication

The dashboard supports optional WorkOS authentication. Configure it in siteConfig.ts:

dashboard: {
  enabled: true,
  requireAuth: false, // Set to true to require WorkOS authentication
},

When requireAuth is false, the dashboard is open to anyone who knows the URL. For production sites, set requireAuth: true and configure WorkOS authentication. See How to setup WorkOS for authentication setup.

If WorkOS isn't configured and requireAuth is true, the dashboard shows setup instructions instead of the login prompt.

Content management

Posts and pages list

View all your posts and pages in one place. Each list includes:

Filter by status: All, Published, Drafts
Search by title or content
Pagination with "First" and "Next" buttons
Items per page selector (15, 25, 50, 100)
Quick actions: Edit, View, Publish/Unpublish

Posts and pages display with their titles, publication status, and last modified dates. Click any item to open the editor.

Post and page editor

Edit markdown content with a live preview. The editor includes:

Markdown editor on the left
Live preview on the right showing how content appears on your site
Draggable frontmatter sidebar (200px-600px width)
Independent scrolling for editor and preview sections
Download markdown button to save changes locally
Copy to clipboard for quick sharing

The frontmatter sidebar shows all available fields with descriptions. Edit values directly, and changes appear in the preview immediately.

Write post and write page

Create new content without leaving the dashboard. The write interface includes:

Full-screen markdown editor
Frontmatter reference panel with copy buttons
Word, line, and character counts
Download markdown button
Content persists in localStorage

Write your content, fill in frontmatter fields, then download the markdown file. Save it to content/blog/ or content/pages/, then sync to Convex.

AI Agent

The dashboard includes a dedicated AI chat section separate from the Write page. Use it for:

Writing assistance
Content suggestions
Editing help
Answering questions about your content

The AI Agent uses Anthropic Claude API and requires ANTHROPIC_API_KEY in your Convex environment variables. Chat history is stored per-session in Convex.

Ask AI (header chat)

The Ask AI feature adds a chat button to your site header that lets visitors ask questions about your content. It uses RAG (Retrieval Augmented Generation) to find relevant content and provide AI-powered answers.

To enable Ask AI:

Enable semantic search in siteConfig.ts:

semanticSearch: {
  enabled: true,
},

Configure Ask AI:

askAI: {
  enabled: true,
  defaultModel: "claude-sonnet-4-20250514",
  models: [
    { id: "claude-sonnet-4-20250514", name: "Claude Sonnet 4", provider: "anthropic" },
    { id: "gpt-4o", name: "GPT-4o", provider: "openai" },
  ],
},

Set required environment variables in Convex:
- OPENAI_API_KEY for embeddings
- ANTHROPIC_API_KEY or OPENAI_API_KEY for the LLM

When enabled, a chat button appears in the header. Clicking it opens a modal where visitors can ask questions. The AI retrieves relevant content from your posts and pages, then generates answers with source citations.

All Newsletter Admin features are integrated into the dashboard:

Subscribers: View, search, filter, and delete subscribers
Send newsletter: Select a blog post to send to all active subscribers
Write email: Compose custom emails with markdown support
Recent sends: View the last 10 newsletter sends (posts and custom emails)
Email stats: Dashboard with total emails sent, newsletters sent, active subscribers, and retention rate

Newsletter features require AgentMail configuration. Set AGENTMAIL_API_KEY and AGENTMAIL_INBOX in your Convex environment variables.

Content import

Import articles from external URLs using Firecrawl:

Enter the URL you want to import
Click "Import"
Review the imported markdown draft
Edit if needed, then sync to Convex

Imported posts are created as drafts (published: false) by default. Review, edit, set published: true, then sync.

Firecrawl import requires FIRECRAWL_API_KEY in your .env.local file.

Site configuration

The Config Generator UI lets you configure all siteConfig.ts settings from the dashboard:

Site name, title, logo, bio
Blog page settings
Featured section configuration
Logo gallery settings
GitHub contributions
Footer and social footer
Newsletter settings
Contact form settings
Stats page settings
Dashboard settings

Make changes in the UI, then download the generated siteConfig.ts file. Replace your existing config file with the downloaded version.

Index HTML editor

View and edit index.html content directly:

Meta tags
Open Graph tags
Twitter Cards
JSON-LD structured data

Edit values in the UI, then download the updated HTML file. Replace your existing index.html with the downloaded version.

Analytics

The dashboard includes a real-time stats section (clone of /stats page):

Active visitors with per-page breakdown
Total page views
Unique visitors
Views by page sorted by popularity

Stats update automatically via Convex subscriptions. No page refresh needed.

Sync commands

Run sync operations from the dashboard without opening a terminal:

Development:

npm run sync - Sync markdown content
npm run sync:discovery - Update discovery files (AGENTS.md, llms.txt)
npm run sync:all - Sync content + discovery files together

Production:

npm run sync:prod - Sync markdown content
npm run sync:discovery:prod - Update discovery files
npm run sync:all:prod - Sync content + discovery files together

Sync server

For the best experience, start the sync server to execute commands directly from the dashboard:

npm run sync-server

This starts a local HTTP server on localhost:3001 that allows the dashboard to execute sync commands and stream output in real-time.

When sync server is running:

Server status shows "Online" in the sync section
"Execute" buttons appear for each sync command
Clicking Execute runs the command and streams output to the terminal view
Real-time output appears as the command runs
No need to copy commands to your terminal

When sync server is offline:

Server status shows "Offline" in the sync section
Only "Copy" buttons appear for each sync command
Clicking Copy shows the command in a modal for copying to your terminal
Copy icon appears next to npm run sync-server command to help you start the server

Security:

Server binds to localhost only (not accessible from network)
Optional token authentication via SYNC_TOKEN environment variable
Only whitelisted commands can be executed
CORS enabled for localhost:5173 (dev server)

Header sync buttons

Quick sync buttons in the dashboard header let you run npm run sync:all (dev and prod) with one click. These buttons automatically use the sync server when available, or show the command in a modal when the server is offline.

Dashboard features

Search

The search bar in the dashboard header searches:

Dashboard features and sections
Page titles
Post content

Results appear as you type. Click any result to navigate to that section or content.

Theme and font

Toggle between themes (dark, light, tan, cloud) and switch fonts (serif, sans, monospace) from the dashboard. Preferences persist across sessions.

Toast notifications

Success, error, info, and warning notifications appear in the top-right corner. They auto-dismiss after 4 seconds and are theme-aware.

When you run sync commands, output appears in a modal. You can:

View full command output
Copy command to clipboard
Close the modal

Mobile responsive

The dashboard works on mobile devices with:

Collapsible sidebar
Touch-friendly controls
Responsive tables and forms
Mobile-optimized layout

Best practices

Use the editor for quick edits and previews
Download markdown files for version control
Sync regularly to keep content up to date
Use the AI Agent for writing assistance
Check analytics to see what content performs well
Configure WorkOS authentication for production sites

Troubleshooting

Dashboard not loading:

Check that dashboard.enabled: true in siteConfig.ts
Verify Convex is running (npx convex dev)
Check browser console for errors

Sync commands failing:

Ensure you're in the project root directory
Check that Convex environment variables are set
Verify .env.local or .env.production.local exists

Authentication not working:

Verify WorkOS environment variables are set
Check that requireAuth: true in siteConfig.ts
See How to setup WorkOS for setup instructions

The dashboard makes managing your markdown blog easier. You can edit content, sync files, and configure settings all from one place.

10 KiB Raw Blame History