post_waver

PostWeaver is a Markdown-centric content distribution system that weaves a single piece of writing into a multi-platform publishing flow.

๐ŸŽฏ What is post_waver?

post_waver is a content management and distribution tool that helps you:

Designed for: Technical bloggers who want to maximize their content reach.

๐Ÿš€ Quick Start

Prerequisites

Installation

# Clone the repository
git clone https://github.com/Charliechen114514/post_waver.git
cd post_waver

# Install dependencies
pnpm install

# Configure environment variables
cat > .env << 'EOF'
# Database
DATABASE_URL="file:./packages/database/prisma/dev.db"

# API Configuration
API_PORT=3001
API_HOST=localhost

# Environment
NODE_ENV=development
EOF

# Initialize database (generate Prisma Client)
pnpm db:init

# Run database migrations (create database file)
pnpm db:migrate:prisma

Initialize Your Blog

post_waver requires a Hexo blog to sync content. The blog/ directory is not tracked by git - each user manages their own blog configuration.

You have several options:

Option 1: Use existing Hexo blog (Recommended)

# Create symlink to your existing blog
ln -s /path/to/your/hexo/blog ./blog

Option 2: Clone your private blog repository

# If you have your blog in a private repo
git clone git@github.com:username/my-private-blog.git blog

Option 3: Initialize new Hexo blog

# Install Hexo CLI
pnpm add -g hexo-cli

# Initialize blog
hexo init blog
cd blog
pnpm install

Optional: Set up version control for your blog

cd blog
git init
git remote add origin <your-private-repo-url>

# After syncing content with post_waver
cd ..
pnpm sync:blog  # Uses scripts/update-blog.sh to commit & push

Important: The blog/ directory is in .gitignore because it contains your personal blog configuration and should not be shared with the post_waver repository.

First Run

# Write a test article
echo "# Hello World" > content/posts/test.md

# Scan and index content
pnpm scan

# Sync to blog (if configured)
pnpm sync:blog

โšก Quick Build & Run

๐Ÿ“ฆ Build the Project

# First time setup - install dependencies
pnpm install

# Configure environment variables
cat > .env << 'EOF'
DATABASE_URL="file:./packages/database/prisma/dev.db"
API_PORT=3001
API_HOST=localhost
NODE_ENV=development
EOF

# Initialize database
pnpm db:init

# Run database migrations (create database file)
pnpm db:migrate:prisma

# Build all packages
pnpm build

Build Process:

๐Ÿš€ Start Development Servers

Full startup (build + start):

pnpm dev

Quick startup (skip build if already compiled):

pnpm start

Individual services:

pnpm dev:web    # Start only Web UI (port 5173)
pnpm dev:api    # Start API server + Web UI (port 3001 + 5173)

๐Ÿ“‹ Service URLs

After starting, you can access:

๐Ÿ”„ Development Workflow

Morning routine:

pnpm start    # Quick start, uses already compiled code

After code changes:

pnpm build    # Recompile modified packages
pnpm start    # Restart services

Full clean rebuild:

pnpm clean              # Remove all dist/ directories
pnpm install            # Reinstall dependencies
pnpm db:init            # Regenerate Prisma Client
pnpm db:migrate:prisma  # Recreate database if needed
pnpm build              # Rebuild all packages
pnpm start              # Start services

โš ๏ธ Common Issues

Module not found errors:

# Solution: Reinstall dependencies
rm -rf node_modules scripts/node_modules
pnpm install

Prisma errors:

# Solution: Regenerate Prisma Client
pnpm db:init

# If database file is missing, run migrations
pnpm db:migrate:prisma

Port already in use:

# Solution: Stop existing processes
lsof -ti :3001 | xargs kill -9    # Clear API port
lsof -ti :5173 | xargs kill -9    # Clear Web UI port

Build failures:

# Solution: Clean build
pnpm clean
pnpm build

๐Ÿ“ Project Structure

Package Overview

Package Purpose Language Description
@content-hub/core Content parsing TypeScript Markdown parsing, frontmatter, scanning
@content-hub/linker Content relationships TypeScript/Python Related posts, prev/next calculation
@content-hub/transformer Platform conversion TypeScript Platform-specific transformations
@content-hub/adapter Platform APIs TypeScript Platform API adapters
@content-hub/database Data persistence TypeScript/Prisma SQLite database, ORM
@content-hub/config Configuration TypeScript Config management
@content-hub/engine Publishing engine TypeScript API server, workflows
@content-hub/web-ui Web interface TypeScript/React User interface
@content-hub/converter-web Converter tool TypeScript/React Standalone converter

Directory Structure

post_waver/
โ”œโ”€โ”€ packages/              # Monorepo packages
โ”‚   โ”œโ”€โ”€ core/             # Core functionality
โ”‚   โ”œโ”€โ”€ linker/           # Content relationships
โ”‚   โ”œโ”€โ”€ transformer/      # Platform transformations
โ”‚   โ”œโ”€โ”€ adapter/          # Platform APIs
โ”‚   โ”œโ”€โ”€ database/         # Database layer
โ”‚   โ”œโ”€โ”€ config/           # Configuration
โ”‚   โ”œโ”€โ”€ engine/           # Publishing engine & API
โ”‚   โ”œโ”€โ”€ web-ui/           # Web interface
โ”‚   โ””โ”€โ”€ converter-web/    # Standalone converter
โ”œโ”€โ”€ content/              # Your markdown articles
โ”œโ”€โ”€ scripts/              # Utility scripts
โ”œโ”€โ”€ docs/                 # Documentation
โ”œโ”€โ”€ test/                 # Tests and fixtures
โ””โ”€โ”€ blog/                 # Hexo blog (not tracked)

๐Ÿ› ๏ธ Available Commands

๐Ÿš€ Quick Start Commands

pnpm dev              # Build all + Start API & Web UI
pnpm start            # Start API & Web UI (skip build)
pnpm dev:web          # Start Web UI only
pnpm dev:api          # Start API server + Web UI

๐Ÿ”ง Build Commands

pnpm build            # Build all packages
pnpm clean            # Remove all dist/ directories
pnpm typecheck        # Type check without building

๐Ÿ“ Content Management

pnpm scan             # Scan and index content
pnpm scan:drafts      # Scan including drafts
pnpm inject:links     # Inject related article links
pnpm sync:blog        # Sync content to Hexo blog

๐Ÿงช Quality & Testing

pnpm lint             # Lint code
pnpm lint:fix         # Fix linting issues
pnpm test             # Run tests

๐Ÿ—„๏ธ Database Commands

pnpm db:init            # Initialize database (generate Prisma Client)
pnpm db:migrate:prisma  # Run database migrations
pnpm db:studio          # Open Prisma Studio (database GUI)
pnpm db:reset           # Reset database (โš ๏ธ deletes all data)
pnpm post:status        # Check post status in database

๐Ÿ—๏ธ Architecture

PostWaver uses a modular monorepo architecture:

  1. Content Layer (core, linker): Parse and analyze markdown content
  2. Transformation Layer (transformer, adapter): Convert for different platforms
  3. Data Layer (database, config): Manage persistence and configuration
  4. Application Layer (engine, web-ui): Provide publishing workflow and UI

Learn more: Architecture Documentation

๐Ÿ‘ฅ For Developers

Interested in contributing or extending PostWaver?

Quick Developer Setup

# Clone and install
git clone https://github.com/Charliechen114514/post_waver.git
cd post_waver
pnpm install

# Configure environment
cat > .env << 'EOF'
DATABASE_URL="file:./packages/database/prisma/dev.db"
API_PORT=3001
API_HOST=localhost
NODE_ENV=development
EOF

# Initialize database
pnpm db:init
pnpm db:migrate:prisma

# Build all packages
pnpm build

# Run tests
pnpm test

# Start development servers
pnpm dev

๐Ÿ“š Documentation

User Documentation

Developer Documentation

Platform Guides

๐Ÿค Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

License: MIT

This site is open source. Improve this page.