x/wiki
1
0
Fork 0
mirror of https://github.com/waynesutton/markdown-site.git synced 2026-01-11 20:08:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

npm package prd added

Browse Source
This commit is contained in:
Wayne Sutton
2026-01-11 00:23:04 -08:00
parent 55f4ada61a
commit 5b69546ca5
7 changed files with 217 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
AGENTS.md
View File

@@ -16,13 +16,13 @@ Your content is instantly available to browsers, LLMs, and AI agents.. Write mar
## Current Status
- **Site Name**: markdown
- **Site Name**: markdown sync
- **Site Title**: markdown sync framework
- **Site URL**: https://yoursite.example.com
- **Total Posts**: 19
- **Total Pages**: 4
- **Latest Post**: 2026-01-10
- **Last Updated**: 2026-01-10T23:49:21.881Z
- **Last Updated**: 2026-01-11T08:12:05.341Z
## Tech stack

2
CLAUDE.md
View File

@@ -5,7 +5,7 @@ Project instructions for Claude Code.
## Project context
<!-- Auto-updated by sync:discovery -->
<!-- Site: markdown | Posts: 19 | Pages: 4 | Updated: 2026-01-10T23:49:21.882Z -->
<!-- Site: markdown sync | Posts: 19 | Pages: 4 | Updated: 2026-01-11T08:12:05.342Z -->
Markdown sync framework. Write markdown in `content/`, run sync commands, content appears instantly via Convex real-time database. Built for developers and AI agents.

2
content/pages/home.md
View File

@@ -9,7 +9,7 @@ textAlign: "left"
The open-source markdown publishing framework for developers and AI agents to ship **[docs](/docs)**, or **[blogs](/blog)** or **[websites](/)** that's always in sync.
**[Fork it](https://github.com/waynesutton/markdown-site)** or npm <span class="copy-command">npx create-markdown-sync my-site</span>, customize it, ship it.
**[Fork it](https://github.com/waynesutton/markdown-site)** or **<span class="copy-command">npx create-markdown-sync my-site</span>**, customize it, ship it.
<!-- This is a comments
Your content is instantly available to browsers, LLMs, and AI

209
prds/npm-package-maintenance.md Normal file
View File

@@ -0,0 +1,209 @@
# NPM Package Maintenance Guide
This document explains how to keep the `create-markdown-sync` npm package updated with the main markdown-sync app.
## Overview
The CLI package lives in `packages/create-markdown-sync/` and clones from `github:waynesutton/markdown-site`. When the main app changes, the CLI may need updates to stay compatible.
## Package Location
```
packages/
create-markdown-sync/
package.json # Version and dependencies
tsconfig.json # TypeScript config
src/
index.ts # CLI entry point
wizard.ts # Interactive prompts
clone.ts # Template cloning
configure.ts # Site configuration
install.ts # Dependency installation
convex-setup.ts # Convex setup
utils.ts # Helper utilities
dist/ # Built JavaScript (gitignored)
```
## When to Update the CLI
Update the CLI package when:
1. **New configuration options** - Added to `fork-config.json.example` or `siteConfig.ts`
2. **New wizard prompts needed** - New features require user input during setup
3. **Template structure changes** - Files moved, renamed, or removed
4. **Convex setup changes** - Auth config, environment variables, or setup flow
5. **Bug fixes** - Issues discovered during user testing
## Commands
### Development
```bash
cd packages/create-markdown-sync
# Install dependencies
npm install
# Build TypeScript
npm run build
# Watch mode for development
npm run dev
# Test locally via npm link
npm link
npx create-markdown-sync test-project
```
### Publishing
```bash
cd packages/create-markdown-sync
# Bump version (choose one)
npm version patch # 0.1.0 -> 0.1.1 (bug fixes)
npm version minor # 0.1.0 -> 0.2.0 (new features)
npm version major # 0.1.0 -> 1.0.0 (breaking changes)
# Publish to npm
npm publish --access public
# Verify publication
npm view create-markdown-sync
```
## Checklist: Before Publishing
1. **Push main app changes to GitHub first**
- The CLI clones from `github:waynesutton/markdown-site`
- Template fixes must be in the remote repo
2. **Test the full flow**
```bash
rm -rf test-project
npx create-markdown-sync test-project
cd test-project
npx convex dev
npm run sync
npm run dev
```
3. **Verify wizard prompts match fork-config.json.example**
- New options should have corresponding prompts
- Defaults should match the example file
4. **Update version number**
- Use semantic versioning
- Update `VERSION` constant in `src/index.ts` if displayed
5. **Build successfully**
```bash
npm run build
# Should complete with no TypeScript errors
```
## Sync Points
These files in the CLI should stay in sync with the main app:
| CLI File | Syncs With | Purpose |
|----------|------------|---------|
| `wizard.ts` | `fork-config.json.example` | All config options have prompts |
| `configure.ts` | `scripts/configure-fork.ts` | Same transformation logic |
| `configure.ts` | `siteConfig.ts` | Template fixes for known issues |
| `convex-setup.ts` | `convex/auth.config.ts` | Auth setup flow |
| `utils.ts` | Success message links | Docs URLs are current |
## Adding New Configuration Options
When a new option is added to `fork-config.json.example`:
1. **Add prompt to wizard.ts**
```typescript
// In the appropriate section
const newOption = await prompts({
type: 'confirm',
name: 'newOption',
message: 'Enable new feature?',
initial: false,
});
```
2. **Add to WizardAnswers type**
```typescript
export interface WizardAnswers {
// ... existing fields
newOption: boolean;
}
```
3. **Add to buildForkConfig in configure.ts**
```typescript
function buildForkConfig(answers: WizardAnswers) {
return {
// ... existing fields
newOption: answers.newOption,
};
}
```
4. **Test the flow**
```bash
npm run build
npm link
npx create-markdown-sync test-project
```
## Handling Breaking Changes
When the main app has breaking changes:
1. **Update CLI to handle both old and new**
- Check for file existence before modifying
- Use try/catch for optional operations
2. **Bump major version if CLI behavior changes**
```bash
npm version major
```
3. **Update README with migration notes**
4. **Consider backward compatibility period**
- Keep old logic for 1-2 releases
- Add deprecation warnings
## Troubleshooting
### "Template cloned but configuration failed"
The template likely has syntax errors or missing files. Check:
- `siteConfig.ts` for embedded quotes or syntax issues
- `fork-config.json.example` for valid JSON
### "Convex setup blocked by WorkOS"
The CLI should disable auth by default. Check:
- `configure.ts` `disableAuthConfig()` function
- `convex/auth.config.ts` in the template
### "TypeScript build errors"
Usually caused by:
- Missing type definitions
- Spread operator ordering (put spread first, then defaults)
- Import path issues (.js extensions required for ESM)
## Version History
| Version | Changes |
|---------|---------|
| 0.1.0 | Initial release with 13-section wizard |
## Resources
- npm package: https://www.npmjs.com/package/create-markdown-sync
- Template repo: https://github.com/waynesutton/markdown-site
- Docs: https://www.markdown.fast/docs
- Deployment: https://www.markdown.fast/docs-deployment
- WorkOS setup: https://www.markdown.fast/how-to-setup-workos

4
public/llms.txt
View File

@@ -1,11 +1,11 @@
# llms.txt - Information for AI assistants and LLMs
# Learn more: https://llmstxt.org/
# Last updated: 2026-01-10T23:49:21.883Z
# Last updated: 2026-01-11T08:12:05.343Z
> Your content is instantly available to browsers, LLMs, and AI agents.
# Site Information
- Name: markdown
- Name: markdown sync
- URL: https://yoursite.example.com
- 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

2
public/raw/home-intro.md
View File

@@ -7,7 +7,7 @@ Date: 2026-01-11
The open-source markdown publishing framework for developers and AI agents to ship **[docs](/docs)**, or **[blogs](/blog)** or **[websites](/)** that's always in sync.
**[Fork it](https://github.com/waynesutton/markdown-site)** or npm <span class="copy-command">npx create-markdown-sync my-site</span>, customize it, ship it.
**[Fork it](https://github.com/waynesutton/markdown-site)** or **<span class="copy-command">npx create-markdown-sync my-site</span>**, customize it, ship it.
<!-- This is a comments
Your content is instantly available to browsers, LLMs, and AI

2
public/raw/index.md
View File

@@ -2,7 +2,7 @@
The open-source markdown publishing framework for developers and AI agents to ship **[docs](/docs)**, or **[blogs](/blog)** or **[websites](/)** that's always in sync.
**[Fork it](https://github.com/waynesutton/markdown-site)** or npm <span class="copy-command">npx create-markdown-sync my-site</span>, customize it, ship it.
**[Fork it](https://github.com/waynesutton/markdown-site)** or **<span class="copy-command">npx create-markdown-sync my-site</span>**, customize it, ship it.
<!-- This is a comments
Your content is instantly available to browsers, LLMs, and AI