x/wiki
1
0
Fork 0
mirror of https://github.com/waynesutton/markdown-site.git synced 2026-01-12 04:09:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

update: added agentmail to readme, updated home links

Browse Source
This commit is contained in:
Wayne Sutton
2025-12-27 16:03:18 -08:00
parent a87db9d171
commit 47934cd382
23 changed files with 115 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
AGENTS.md
View File

@@ -19,10 +19,10 @@ Your content is instantly available to browsers, LLMs, and AI agents.. Write mar
- **Site Name**: markdown
- **Site Title**: markdown sync framework
- **Site URL**: https://markdown.fast
- **Total Posts**: 12
- **Total Pages**: 4
- **Latest Post**: 2025-12-25
- **Last Updated**: 2025-12-27T06:13:31.118Z
- **Total Posts**: 14
- **Total Pages**: 5
- **Latest Post**: 2025-12-27
- **Last Updated**: 2025-12-27T23:32:52.395Z
## Tech stack

13
README.md
View File

@@ -110,6 +110,19 @@ Follow the step-by-step guide in `FORK_CONFIG.md` to update each file manually.
- Run `npm run import <url>` to scrape and create draft posts locally
- Then sync to dev or prod with `npm run sync` or `npm run sync:prod`
### Newsletter and Email
The framework includes AgentMail integration for newsletter subscriptions and contact forms. Features include:
- Newsletter subscriptions and sending
- Contact forms on any post or page
- Automated weekly digests
- Developer notifications
- Admin UI for subscriber management
- CLI tools for sending newsletters and stats
See the [AgentMail setup guide](https://www.markdown.fast/blog/how-to-use-agentmail) for configuration instructions.
## Getting Started
### Prerequisites

2
content/blog/about-this-blog.md
View File

@@ -3,7 +3,7 @@ title: "About This Markdown Framework"
description: "How this open source framework works with Convex for real-time sync and Netlify for deployment."
date: "2025-12-14"
slug: "about-this-blog"
published: true
published: false
tags: ["convex", "netlify", "open-source", "markdown", "ai", "llm"]
readTime: "4 min read"
featured: false

2
content/blog/git-commit-message-best-practices.md
View File

@@ -1,7 +1,7 @@
---
title: "Git commit message best practices"
description: "A guide to writing clear, consistent commit messages that help your team understand changes and generate better changelogs."
date: "2025-01-17"
date: "2025-12-14"
slug: "git-commit-message-best-practices"
published: true
tags: ["git", "development", "best-practices", "workflow"]

27
content/blog/how-to-use-agentmail.md
View File

@@ -4,6 +4,7 @@ description: "Complete guide to setting up AgentMail for newsletters and contact
date: "2025-12-27"
slug: "how-to-use-agentmail"
published: true
image: images/agentmail-blog.png
tags: ["agentmail", "newsletter", "email", "setup"]
---
@@ -35,11 +36,11 @@ In the AgentMail dashboard, navigate to API settings and copy your API key. You'
In your Convex dashboard, go to Settings > Environment Variables and add:
| Variable | Description | Required |
|----------|-------------|----------|
| `AGENTMAIL_API_KEY` | Your AgentMail API key | Yes |
| `AGENTMAIL_INBOX` | Your inbox address (e.g., `markdown@agentmail.to`) | Yes |
| `AGENTMAIL_CONTACT_EMAIL` | Contact form recipient (defaults to inbox if not set) | No |
| Variable | Description | Required |
| ------------------------- | ----------------------------------------------------- | -------- |
| `AGENTMAIL_API_KEY` | Your AgentMail API key | Yes |
| `AGENTMAIL_INBOX` | Your inbox address (e.g., `markdown@agentmail.to`) | Yes |
| `AGENTMAIL_CONTACT_EMAIL` | Contact form recipient (defaults to inbox if not set) | No |
**Important:** Never hardcode email addresses in your code. Always use environment variables.
@@ -152,8 +153,8 @@ Submissions are stored in Convex and sent via AgentMail to your configured recip
### Frontmatter options
| Field | Type | Description |
|-------|------|-------------|
| Field | Type | Description |
| ------------- | ------- | ------------------------------------- |
| `contactForm` | boolean | Enable contact form on this post/page |
## Frontmatter options
@@ -165,7 +166,7 @@ Control newsletter signup display per post/page:
```markdown
---
title: "My Post"
newsletter: true # Show signup (default: follows siteConfig)
newsletter: true # Show signup (default: follows siteConfig)
---
```
@@ -174,7 +175,7 @@ Or hide it:
```markdown
---
title: "My Post"
newsletter: false # Hide signup even if enabled globally
newsletter: false # Hide signup even if enabled globally
---
```
@@ -195,10 +196,10 @@ All AgentMail features require these Convex environment variables:
## CLI commands
| Command | Description |
|---------|-------------|
| `npm run newsletter:send <slug>` | Send a blog post to all subscribers |
| `npm run newsletter:send:stats` | Send weekly stats summary to your inbox |
| Command | Description |
| -------------------------------- | --------------------------------------- |
| `npm run newsletter:send <slug>` | Send a blog post to all subscribers |
| `npm run newsletter:send:stats` | Send weekly stats summary to your inbox |
## Troubleshooting

3
content/blog/how-to-use-firecrawl.md
View File

@@ -1,9 +1,10 @@
---
title: "How to use Firecrawl"
description: "Import external articles as markdown posts using Firecrawl. Get your API key and configure environment variables for local imports and AI chat."
date: "2025-01-20"
date: "2025-12-20"
slug: "how-to-use-firecrawl"
published: true
image: images/firecrwall-blog.png
tags: ["tutorial", "firecrawl", "import"]
---

10
content/pages/contact.md
View File

@@ -9,10 +9,8 @@ order: 4
You found the contact page. Nice
## Contact form demo
This form does not work in production and AgentMail to send emails. See <a href="/how-to-use-agentmail"> How to use AgentMail with Markdown Sync for details.>
<!-- contactform -->
## The technical way
This site runs on Convex, which means every page view is a live subscription to the database. You are not reading cached HTML. You are reading data that synced moments ago.
If you want to reach out, here is an idea: fork this repo, add a contact form, wire it to a Convex mutation, and deploy. Your message will hit the database in under 100ms. No email server required.

25
content/pages/newsletter.md
View File

@@ -4,12 +4,29 @@ slug: newsletter
published: true
order: 15
showInNav: true
newsletter: true
newsletter: false
---
# Newsletter
# Newsletter Demo Page
Stay updated with the latest posts and updates from the markdown sync framework.
This is a demo newsletter page available at `/newsletter`. The newsletter feature uses AgentMail for email infrastructure.
<!-- newsletter -->
## About AgentMail
This newsletter integration is powered by AgentMail, which provides email infrastructure for the markdown blog framework.
AgentMail Newsletter integration features:
- Newsletter subscriptions and sending
- Contact forms on any post or page
- Automated weekly digests
- Developer notifications
- Admin UI for subscriber management
- CLI tools for sending newsletters and stats
For complete setup instructions and detailed documentation, see the [How to use AgentMail with Markdown Sync](/blog/how-to-use-agentmail) guide.
## What you will get
@@ -19,7 +36,7 @@ When you subscribe, you will receive:
- Updates about new features and improvements
- Tips and tricks for getting the most out of markdown sync
## Subscribe
## Subscribe Demo
Use the form below to subscribe to our newsletter. We respect your privacy and you can unsubscribe at any time.

BIN
public/images/agentmail-blog.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 392 KiB

BIN
public/images/firecrwall-blog.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 396 KiB

6
public/llms.txt
View File

@@ -1,6 +1,6 @@
# llms.txt - Information for AI assistants and LLMs
# Learn more: https://llmstxt.org/
# Last updated: 2025-12-27T06:13:31.119Z
# Last updated: 2025-12-27T23:32:52.396Z
> Your content is instantly available to browsers, LLMs, and AI agents.
@@ -9,8 +9,8 @@
- URL: https://markdown.fast
- Description: Your content is instantly available to browsers, LLMs, and AI agents. Write markdown, sync from the terminal. Your content is instantly available to browsers, LLMs, and AI agents. Built on Convex and Netlify.
- Topics: Markdown, Convex, React, TypeScript, Netlify, Open Source, AI, LLM, AEO, GEO
- Total Posts: 12
- Latest Post: 2025-12-25
- Total Posts: 14
- Latest Post: 2025-12-27
- GitHub: https://github.com/waynesutton/markdown-site
# API Endpoints

117
public/raw/about-this-blog.md
View File

@@ -1,117 +0,0 @@
# About This Markdown Framework
> How this open source framework works with Convex for real-time sync and Netlify for deployment.
---
Type: post
Date: 2025-12-14
Reading time: 4 min read
Tags: convex, netlify, open-source, markdown, ai, llm
---
# About This Markdown Framework
An open-source publishing framework built for AI agents and developers to ship websites, docs, or blogs.. Write markdown, sync from the terminal. Your content is instantly available to browsers, LLMs, and AI agents. Built on Convex and Netlify.
## How It Works
The architecture is straightforward:
1. **Markdown files** live in `content/blog/`
2. **Convex** stores posts in a real-time database
3. **React** renders the frontend
4. **Netlify** handles deployment and edge functions
When you add a new markdown file and run the sync script, your post appears instantly. No rebuild required.
## The Stack
| Layer | Technology |
| -------- | ------------------------- |
| Frontend | React + TypeScript |
| Backend | Convex |
| Styling | CSS (no framework) |
| Hosting | Netlify |
| Content | Markdown with frontmatter |
## Why Convex?
Convex provides real-time sync out of the box. When you update a post, every connected browser sees the change immediately.
```typescript
// Fetching posts is one line
const posts = useQuery(api.posts.getAllPosts);
```
No REST endpoints. No cache invalidation. No WebSocket setup. The data stays in sync automatically.
## Why Markdown?
Markdown files in your repo are simpler than a CMS:
- Version controlled in git (commit, diff, roll back)
- Edit with any text editor
- AI agents can create and modify posts
- No separate login or admin panel
## Features
This site includes:
- **Real-time updates** via Convex subscriptions
- **Static pages** for About, Projects, Contact (optional)
- **RSS feeds** at `/rss.xml` and `/rss-full.xml`
- **Sitemap** at `/sitemap.xml`
- **JSON API** at `/api/posts` and `/api/post?slug=xxx`
- **Theme switching** between dark, light, tan, and cloud
- **SEO optimization** with meta tags and structured data
- **AI discovery** via `llms.txt`
## Fork and Deploy
The setup takes about 10 minutes:
1. Fork the repo
2. Run `npx convex dev` to set up your backend
3. Run `npm run sync` to upload posts (development) or `npm run sync:prod` (production)
4. Deploy to Netlify
**Development vs Production:** Use `npm run sync` when testing locally against your dev Convex deployment. Use `npm run sync:prod` when deploying content to your live production site.
**Sync commands:**
**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
**Import external content:** Run `npm run import <url>` to scrape and create local markdown drafts. Then sync to dev or prod. There is no separate import command for production because import creates local files only.
Read the [setup guide](/setup-guide) for detailed steps.
## Customization
Edit `src/pages/Home.tsx` to change:
- Site name and description
- Featured posts
- Footer links
Edit `src/styles/global.css` to change:
- Colors and typography
- Theme variables
- Layout spacing
## Links
- [Convex Documentation](https://docs.convex.dev)
- [Netlify Documentation](https://docs.netlify.com)
- [Setup Guide](/setup-guide)

2
public/raw/about.md
View File

@@ -2,7 +2,7 @@
---
Type: page
Date: 2025-12-27
Date: 2025-12-28
---
An open-source publishing framework built for AI agents and developers to ship websites, docs, or blogs.. Write markdown, sync from the terminal. Your content is instantly available to browsers, LLMs, and AI agents. Built on Convex and Netlify.

2
public/raw/changelog.md
View File

@@ -2,7 +2,7 @@
---
Type: page
Date: 2025-12-27
Date: 2025-12-28
---
All notable changes to this project.

10
public/raw/contact.md
View File

@@ -2,15 +2,13 @@
---
Type: page
Date: 2025-12-27
Date: 2025-12-28
---
You found the contact page. Nice
<!-- contactform -->
## Contact form demo
## The technical way
This form does not work in production and AgentMail to send emails. See <a href="/how-to-use-agentmail"> How to use AgentMail with Markdown Sync for details.>
This site runs on Convex, which means every page view is a live subscription to the database. You are not reading cached HTML. You are reading data that synced moments ago.
If you want to reach out, here is an idea: fork this repo, add a contact form, wire it to a Convex mutation, and deploy. Your message will hit the database in under 100ms. No email server required.
<!-- contactform -->

2
public/raw/docs.md
View File

@@ -2,7 +2,7 @@
---
Type: page
Date: 2025-12-27
Date: 2025-12-28
---
## Getting Started

2
public/raw/git-commit-message-best-practices.md
View File

@@ -4,7 +4,7 @@
---
Type: post
Date: 2025-01-17
Date: 2025-12-14
Reading time: 5 min read
Tags: git, development, best-practices, workflow
---

26
public/raw/how-to-use-agentmail.md
View File

@@ -37,11 +37,11 @@ In the AgentMail dashboard, navigate to API settings and copy your API key. You'
In your Convex dashboard, go to Settings > Environment Variables and add:
| Variable | Description | Required |
|----------|-------------|----------|
| `AGENTMAIL_API_KEY` | Your AgentMail API key | Yes |
| `AGENTMAIL_INBOX` | Your inbox address (e.g., `markdown@agentmail.to`) | Yes |
| `AGENTMAIL_CONTACT_EMAIL` | Contact form recipient (defaults to inbox if not set) | No |
| Variable | Description | Required |
| ------------------------- | ----------------------------------------------------- | -------- |
| `AGENTMAIL_API_KEY` | Your AgentMail API key | Yes |
| `AGENTMAIL_INBOX` | Your inbox address (e.g., `markdown@agentmail.to`) | Yes |
| `AGENTMAIL_CONTACT_EMAIL` | Contact form recipient (defaults to inbox if not set) | No |
**Important:** Never hardcode email addresses in your code. Always use environment variables.
@@ -154,8 +154,8 @@ Submissions are stored in Convex and sent via AgentMail to your configured recip
### Frontmatter options
| Field | Type | Description |
|-------|------|-------------|
| Field | Type | Description |
| ------------- | ------- | ------------------------------------- |
| `contactForm` | boolean | Enable contact form on this post/page |
## Frontmatter options
@@ -167,7 +167,7 @@ Control newsletter signup display per post/page:
```markdown
---
title: "My Post"
newsletter: true # Show signup (default: follows siteConfig)
newsletter: true # Show signup (default: follows siteConfig)
---
```
@@ -176,7 +176,7 @@ Or hide it:
```markdown
---
title: "My Post"
newsletter: false # Hide signup even if enabled globally
newsletter: false # Hide signup even if enabled globally
---
```
@@ -197,10 +197,10 @@ All AgentMail features require these Convex environment variables:
## CLI commands
| Command | Description |
|---------|-------------|
| `npm run newsletter:send <slug>` | Send a blog post to all subscribers |
| `npm run newsletter:send:stats` | Send weekly stats summary to your inbox |
| Command | Description |
| -------------------------------- | --------------------------------------- |
| `npm run newsletter:send <slug>` | Send a blog post to all subscribers |
| `npm run newsletter:send:stats` | Send weekly stats summary to your inbox |
## Troubleshooting

2
public/raw/how-to-use-firecrawl.md
View File

@@ -4,7 +4,7 @@
---
Type: post
Date: 2025-01-20
Date: 2025-12-20
Reading time: 2 min read
Tags: tutorial, firecrawl, import
---

14
public/raw/index.md
View File

@@ -2,7 +2,7 @@
This is the homepage index of all published content.
## Blog Posts (14)
## Blog Posts (13)
- **[How to use AgentMail with Markdown Sync](/raw/how-to-use-agentmail.md)** - Complete guide to setting up AgentMail for newsletters and contact forms in your markdown blog
- Date: 2025-12-27 | Reading time: 5 min read | Tags: agentmail, newsletter, email, setup
@@ -14,12 +14,14 @@ This is the homepage index of all published content.
- Date: 2025-12-21 | Reading time: 5 min read | Tags: features, stats, convex, updates, analytics
- **[Configure your fork in one command](/raw/fork-configuration-guide.md)** - Two options to set up your forked markdown framework: automated JSON config with npm run configure, or step-by-step manual guide.
- Date: 2025-12-20 | Reading time: 4 min read | Tags: configuration, setup, fork, tutorial
- **[How to use Firecrawl](/raw/how-to-use-firecrawl.md)** - Import external articles as markdown posts using Firecrawl. Get your API key and configure environment variables for local imports and AI chat.
- Date: 2025-12-20 | Reading time: 2 min read | Tags: tutorial, firecrawl, import
- **[v1.18.0 release: 12 versions of shipping](/raw/raw-markdown-and-copy-improvements.md)** - Everything new from v1.7 to v1.18.0. Automated fork setup, GitHub contributions graph, write page, mobile menu, aggregates, and more.
- Date: 2025-12-20 | Reading time: 8 min read | Tags: release, features, updates, developer-tools
- **[New features: search, featured section, and logo gallery](/raw/new-features-search-featured-logos.md)** - Three updates that make your markdown framework more useful: Command+K search, frontmatter-controlled featured items, and a scrolling logo gallery.
- Date: 2025-12-17 | Reading time: 4 min read | Tags: features, search, convex, updates
- **[About This Markdown Framework](/raw/about-this-blog.md)** - How this open source framework works with Convex for real-time sync and Netlify for deployment.
- Date: 2025-12-14 | Reading time: 4 min read | Tags: convex, netlify, open-source, markdown, ai, llm
- **[Git commit message best practices](/raw/git-commit-message-best-practices.md)** - A guide to writing clear, consistent commit messages that help your team understand changes and generate better changelogs.
- Date: 2025-12-14 | Reading time: 5 min read | Tags: git, development, best-practices, workflow
- **[How to Publish a Blog Post](/raw/how-to-publish.md)** - A quick guide to writing and publishing markdown posts using Cursor after your framework is set up.
- Date: 2025-12-14 | Reading time: 3 min read | Tags: tutorial, markdown, cursor, IDE, publishing
- **[Writing Markdown with Code Examples](/raw/markdown-with-code-examples.md)** - A complete reference for writing markdown with links, code blocks, images, tables, and formatting. Copy examples directly into your posts.
@@ -28,10 +30,6 @@ This is the homepage index of all published content.
- Date: 2025-12-14 | Reading time: 8 min read | Tags: convex, netlify, tutorial, deployment
- **[Using Images in Blog Posts](/raw/using-images-in-posts.md)** - Learn how to add header images, inline images, and Open Graph images to your markdown posts.
- Date: 2025-12-14 | Reading time: 4 min read | Tags: images, tutorial, markdown, open-graph
- **[How to use Firecrawl](/raw/how-to-use-firecrawl.md)** - Import external articles as markdown posts using Firecrawl. Get your API key and configure environment variables for local imports and AI chat.
- Date: 2025-01-20 | Reading time: 2 min read | Tags: tutorial, firecrawl, import
- **[Git commit message best practices](/raw/git-commit-message-best-practices.md)** - A guide to writing clear, consistent commit messages that help your team understand changes and generate better changelogs.
- Date: 2025-01-17 | Reading time: 5 min read | Tags: git, development, best-practices, workflow
## Pages (6)
@@ -44,6 +42,6 @@ This is the homepage index of all published content.
---
**Total Content:** 14 posts, 6 pages
**Total Content:** 13 posts, 6 pages
All content is available as raw markdown files at `/raw/{slug}.md`

25
public/raw/newsletter.md
View File

@@ -2,12 +2,29 @@
---
Type: page
Date: 2025-12-27
Date: 2025-12-28
---
# Newsletter
# Newsletter Demo Page
Stay updated with the latest posts and updates from the markdown sync framework.
This is a demo newsletter page available at `/newsletter`. The newsletter feature uses AgentMail for email infrastructure.
<!-- newsletter -->
## About AgentMail
This newsletter integration is powered by AgentMail, which provides email infrastructure for the markdown blog framework.
AgentMail Newsletter integration features:
- Newsletter subscriptions and sending
- Contact forms on any post or page
- Automated weekly digests
- Developer notifications
- Admin UI for subscriber management
- CLI tools for sending newsletters and stats
For complete setup instructions and detailed documentation, see the [How to use AgentMail with Markdown Sync](/blog/how-to-use-agentmail) guide.
## What you will get
@@ -17,7 +34,7 @@ When you subscribe, you will receive:
- Updates about new features and improvements
- Tips and tricks for getting the most out of markdown sync
## Subscribe
## Subscribe Demo
Use the form below to subscribe to our newsletter. We respect your privacy and you can unsubscribe at any time.

2
public/raw/projects.md
View File

@@ -2,7 +2,7 @@
---
Type: page
Date: 2025-12-27
Date: 2025-12-28
---
This markdown framework is open source and built to be extended. Here is what ships out of the box.

4
src/config/siteConfig.ts
View File

@@ -317,7 +317,7 @@ export const siteConfig: SiteConfig = {
},
{
src: "/images/logos/firecrawl.svg",
href: "https://firecrawl.dev/?utm_source=markdownfast",
href: "https://www.markdown.fast/how-to-use-firecrawl",
},
{
src: "/images/logos/markdown.svg",
@@ -329,7 +329,7 @@ export const siteConfig: SiteConfig = {
},
{
src: "/images/logos/agentmail.svg",
href: "https://agentmail.to/utm_source=markdownfast",
href: "https://www.markdown.fast/how-to-use-agentmail/",
},
{
src: "/images/logos/mcp.svg",