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

feat: add discovery files sync commands and update documentation

Browse Source
This commit is contained in:
Wayne Sutton
2025-12-24 23:16:34 -08:00
parent 1ac6b9fc84
commit 03ff3eb844
28 changed files with 2345 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
public/llms.txt
View File

@@ -1,13 +1,17 @@
# llms.txt - Information for AI assistants and LLMs
# Learn more: https://llmstxt.org/
# Last updated: 2025-12-25T06:55:43.147Z
> An open-source publishing framework for AI agents and developers. Write markdown, sync from the terminal.
> Your content is instantly available to browsers, LLMs, and AI agents.
# Site Information
- Name: markdown sync framework
- Name: markdown
- URL: https://markdown.fast
- Description: An open-source publishing framework for AI agents and developers. Write markdown, sync from the terminal. Your content is instantly available to browsers, LLMs, and AI agents. Built on Convex and Netlify.
- 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: 11
- Latest Post: 2025-12-21
- GitHub: https://github.com/waynesutton/markdown-site
# API Endpoints

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

@@ -78,6 +78,18 @@ The setup takes about 10 minutes:
**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.

14
public/raw/about.md
View File

@@ -2,7 +2,7 @@
---
Type: page
Date: 2025-12-24
Date: 2025-12-25
---
An open-source publishing framework for AI agents and developers. Write markdown, sync from the terminal. Your content is instantly available to browsers, LLMs, and AI agents. Built on Convex and Netlify.
@@ -13,6 +13,18 @@ An open-source publishing framework for AI agents and developers. Write markdown
**CLI publishing workflow.** Write markdown locally, then run `npm run sync` (dev) or `npm run sync:prod` (production). Content appears instantly via Convex real-time sync. Images require git commit and push since they are served as static files from Netlify.
**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
**Version controlled.** Markdown source files live in your repo alongside code. Commit changes, review diffs, roll back like any codebase. The sync command pushes content to the database.
```bash

48
public/raw/changelog.md
View File

@@ -2,11 +2,57 @@
---
Type: page
Date: 2025-12-24
Date: 2025-12-25
---
All notable changes to this project.
## v1.27.0
Released December 24, 2025
**Homepage post limit and optional read more link**
- Configurable post limit for homepage via `siteConfig.postsDisplay.homePostsLimit`
- Default limit set to 10 most recent posts
- Set to `undefined` to show all posts (no limit)
- Optional "read more" link below limited post list
- Configurable via `siteConfig.postsDisplay.homePostsReadMore`
- Customizable link text and destination URL
- Only appears when posts are limited and there are more posts than the limit
- Default links to `/blog` page
- Can be disabled by setting `enabled: false`
Updated files: `src/config/siteConfig.ts`, `src/pages/Home.tsx`, `src/styles/global.css`
## v1.26.0
Released December 24, 2025
**Tag pages, related posts, and AI service links re-enabled**
- Tag pages at `/tags/[tag]` route
- Dynamic tag archive pages showing all posts with a specific tag
- View mode toggle (list/cards) with localStorage persistence
- Mobile responsive layout matching existing blog page design
- Sitemap updated to include all tag pages dynamically
- Related posts component for blog post footers
- Shows up to 3 related posts based on shared tags
- Sorted by relevance (number of shared tags) then by date
- Only displays on blog posts (not static pages)
- Improved tag links in post footers
- Tags now link to `/tags/[tag]` archive pages
- Visual styling consistent with existing theme
- Open in AI service links re-enabled in CopyPageDropdown
- Uses GitHub raw URLs instead of Netlify paths (bypasses edge function issues)
- ChatGPT, Claude, and Perplexity links with universal prompt
- "Requires git push" hint for users (npm sync alone doesn't update GitHub)
- Visual divider separating AI options from other menu items
Updated files: `src/config/siteConfig.ts`, `convex/schema.ts`, `convex/posts.ts`, `convex/http.ts`, `src/pages/TagPage.tsx`, `src/pages/Post.tsx`, `src/components/CopyPageDropdown.tsx`, `src/styles/global.css`, `src/App.tsx`
Documentation updated: `content/pages/docs.md`, `content/blog/setup-guide.md`
## v1.25.2
Released December 24, 2025

2
public/raw/contact.md
View File

@@ -2,7 +2,7 @@
---
Type: page
Date: 2025-12-24
Date: 2025-12-25
---
You found the contact page. Nice

46
public/raw/docs.md
View File

@@ -2,13 +2,25 @@
---
Type: page
Date: 2025-12-24
Date: 2025-12-25
---
Reference documentation for setting up, customizing, and deploying this markdown framework.
**How publishing works:** Write posts in markdown, run `npm run sync` for development or `npm run sync:prod` for production, and they appear on your live site immediately. No rebuild or redeploy needed. Convex handles real-time data sync, so connected browsers update automatically.
**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
## Quick start
```bash
@@ -213,12 +225,24 @@ To add a custom frontmatter field, update these files:
### Syncing content
**Development:**
```bash
# Development
npm run sync
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
**Production:**
```bash
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 everything together:**
```bash
npm run sync:all # Development: content + discovery
npm run sync:all:prod # Production: content + discovery
```
### When to sync vs deploy
@@ -228,6 +252,7 @@ npm run sync:prod
| Blog posts in `content/blog/` | `npm run sync` | Instant (no rebuild) |
| Pages in `content/pages/` | `npm run sync` | Instant (no rebuild) |
| Featured items (via frontmatter) | `npm run sync` | Instant (no rebuild) |
| Site config changes | `npm run sync:discovery` | Updates discovery files |
| Import external URL | `npm run import` then sync | Instant (no rebuild) |
| Images in `public/images/` | Git commit + push | Requires rebuild |
| `siteConfig` in `Home.tsx` | Redeploy | Requires rebuild |
@@ -407,7 +432,7 @@ excerpt: "Short description for card view."
image: "/images/thumbnail.png"
```
Then run `npm run sync`. No redeploy needed.
Then run `npm run sync` or `npm run sync:all`. No redeploy needed.
| Field | Description |
| --------------- | -------------------------------------------- |
@@ -640,7 +665,7 @@ Mobile sizes defined in `@media (max-width: 768px)` block.
2. Push to GitHub
3. Wait for Netlify to rebuild
The `npm run sync` command only syncs markdown text content. Images are deployed when Netlify builds your site.
The `npm run sync` command only syncs markdown text content. Images are deployed when Netlify builds your site. Use `npm run sync:discovery` to update discovery files (AGENTS.md, llms.txt) when site configuration changes.
**Logo options:**
@@ -691,8 +716,9 @@ Each post and page includes a share dropdown with options:
| What you want | Command needed |
| ------------------------------------ | ------------------------------ |
| Content visible on your site | `npm run sync` or `sync:prod` |
| Discovery files updated | `npm run sync:discovery` or `sync:discovery:prod` |
| AI links (ChatGPT/Claude/Perplexity) | `git push` to GitHub |
| Both | `npm run sync` then `git push` |
| Both content and discovery | `npm run sync:all` or `sync:all:prod` |
**Download as SKILL.md:** Downloads the content formatted as an Anthropic Agent Skills file with metadata, triggers, and instructions sections.
@@ -726,7 +752,7 @@ All stats update automatically via Convex subscriptions.
## Raw markdown files
When you run `npm run sync` (development) or `npm run sync:prod` (production), static `.md` files are generated in `public/raw/` for each published post and page.
When you run `npm run sync` (development) or `npm run sync:prod` (production), static `.md` files are generated in `public/raw/` for each published post and page. Use `npm run sync:all` or `npm run sync:all:prod` to sync content and update discovery files together.
**Access pattern:** `/raw/{slug}.md`
@@ -800,6 +826,7 @@ The import command creates local markdown files only. It does not interact with
- `npm run sync` to push to development
- `npm run sync:prod` to push to production
- Use `npm run sync:all` or `npm run sync:all:prod` to sync content and update discovery files together
There is no `npm run import:prod` because import creates local files and sync handles the target environment.
@@ -881,6 +908,7 @@ export default defineSchema({
- 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**

30
public/raw/happy-holidays-2025.md Normal file
View File

@@ -0,0 +1,30 @@
# Happy holidays and thank you
> A quick note of thanks for stars, forks, and feedback. More AI-first publishing features coming in 2026.
---
Type: post
Date: 2025-12-25
Reading time: 2 min read
Tags: updates, community, ai
---
# Happy holidays and thank you
Thank you for using this markdown framework. Your stars, forks, and feedback help make it better.
## Feedback and feature requests
Found a bug? Have an idea? Open an issue on [GitHub](https://github.com/waynesutton/markdown-site). Issues help prioritize what to build next.
## What's coming
More AI-first publishing features are on the way. The changelog at [/changelog](/changelog) tracks all updates. Check it regularly for new releases.
Recent additions include tag pages, related posts, and improved AI service integrations. The roadmap focuses on making content creation faster and more accessible to AI agents.
## Keep building
Write markdown. Sync from the terminal. Your content appears instantly. That's the goal.
Happy holidays.

6
public/raw/index.md
View File

@@ -2,8 +2,10 @@
This is the homepage index of all published content.
## Blog Posts (11)
## Blog Posts (12)
- **[Happy holidays and thank you](/raw/happy-holidays-2025.md)** - A quick note of thanks for stars, forks, and feedback. More AI-first publishing features coming in 2026.
- Date: 2025-12-25 | Reading time: 2 min read | Tags: updates, community, ai
- **[Netlify edge functions blocking AI crawlers from static files](/raw/netlify-edge-excludedpath-ai-crawlers.md)** - Why excludedPath in netlify.toml isn't preventing edge functions from intercepting /raw/* requests, and how ChatGPT and Perplexity get blocked while Claude works.
- Date: 2025-12-21 | Reading time: 5 min read | Tags: netlify, edge-functions, ai, troubleshooting, help
- **[Visitor tracking and stats improvements](/raw/visitor-tracking-and-stats-improvements.md)** - Real-time visitor map, write conflict prevention, GitHub Stars integration, and better AI prompts. Updates from v1.18.1 to v1.20.2.
@@ -37,6 +39,6 @@ This is the homepage index of all published content.
---
**Total Content:** 11 posts, 5 pages
**Total Content:** 12 posts, 5 pages
All content is available as raw markdown files at `/raw/{slug}.md`

2
public/raw/projects.md
View File

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

32
public/raw/setup-guide.md
View File

@@ -180,8 +180,18 @@ export default defineSchema({
Blog posts live in `content/blog/` as markdown files. Sync them to Convex:
**Development:**
```bash
npm run sync
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:**
```bash
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
```
This reads all markdown files, parses the frontmatter, and uploads them to your Convex database.
@@ -385,16 +395,17 @@ This image appears when sharing on social media. Recommended: 1200x630 pixels.
2. Push to GitHub
3. Wait for Netlify to rebuild
The `npm run sync` command only syncs markdown text content. Images are deployed when Netlify builds your site.
The `npm run sync` command only syncs markdown text content. Images are deployed when Netlify builds your site. Use `npm run sync:discovery` to update discovery files (AGENTS.md, llms.txt) when site configuration changes.
### Sync After Adding Posts
After adding or editing posts, sync to Convex.
**Development sync:**
```bash
npm run sync
npm run sync # Sync markdown content
npm run sync:discovery # Update discovery files
npm run sync:all # Sync everything together
```
**Production sync:**
@@ -408,9 +419,10 @@ VITE_CONVEX_URL=https://your-prod-deployment.convex.cloud
Get your production URL from the [Convex Dashboard](https://dashboard.convex.dev) by selecting your project and switching to the Production deployment.
Then sync:
```bash
npm run sync:prod
npm run sync:prod # Sync markdown content
npm run sync:discovery:prod # Update discovery files
npm run sync:all:prod # Sync everything together
```
### Environment Files
@@ -429,6 +441,7 @@ Both files are gitignored. Each developer creates their own local environment fi
| Blog posts in `content/blog/` | `npm run sync` | Instant (no rebuild) |
| Pages in `content/pages/` | `npm run sync` | Instant (no rebuild) |
| Featured items (via frontmatter) | `npm run sync` | Instant (no rebuild) |
| Site config changes | `npm run sync:discovery` | Updates discovery files |
| Import external URL | `npm run import` then sync | Instant (no rebuild) |
| Images in `public/images/` | Git commit + push | Requires rebuild |
| `siteConfig` in `Home.tsx` | Redeploy | Requires rebuild |
@@ -1074,8 +1087,9 @@ Each post and page includes a share dropdown with options for AI tools:
| What you want | Command needed |
| ------------------------------------ | ------------------------------ |
| Content visible on your site | `npm run sync` or `sync:prod` |
| Discovery files updated | `npm run sync:discovery` or `sync:discovery:prod` |
| AI links (ChatGPT/Claude/Perplexity) | `git push` to GitHub |
| Both | `npm run sync` then `git push` |
| Both content and discovery | `npm run sync:all` or `sync:all:prod` |
**Download as SKILL.md** formats the content as an Anthropic Agent Skills file with metadata, triggers, and instructions sections.
@@ -1125,6 +1139,7 @@ The import script will:
- Run `npm run sync` to push to development
- Run `npm run sync:prod` to push to production
- Use `npm run sync:all` or `npm run sync:all:prod` to sync content and update discovery files together
Imported posts are created as drafts (`published: false`). Review, edit, set `published: true`, then sync to your target environment.
@@ -1135,7 +1150,8 @@ Imported posts are created as drafts (`published: false`). Review, edit, set `pu
1. Check that `published: true` in frontmatter
2. Run `npm run sync` to sync posts to development
3. Run `npm run sync:prod` to sync posts to production
4. Verify posts exist in Convex dashboard
4. Use `npm run sync:all` or `npm run sync:all:prod` to sync content and update discovery files together
5. Verify posts exist in Convex dashboard
### RSS/Sitemap not working