@writely/writely

The complete Writely blog platform. Everything you need to build, deploy, and manage beautiful blogs with React, MDX, and powerful themes. This package provides unified access to all Writely functionality through a single import.

Features

• Unified API: Single package providing access to all Writely functionality
• Core Schemas: Comprehensive Zod schemas for blog configuration and validation
• Theme System: 6 beautiful, customizable themes with responsive layouts
• MDX Processing: Advanced MDX processing with syntax highlighting and math rendering
• Development Server: Next.js-based preview server with hot reload and file watching
• CLI Tools: Command-line interface for development, building, and deployment
• Type Safety: Full TypeScript support with generated types and runtime validation
• Performance Optimized: Tree-shaking, efficient bundling, and static generation
• SEO Ready: Built-in SEO features, meta tag management, and sitemap generation
• Extensible: Modular architecture allowing custom themes and components

Installation

# Install the complete platform
npm install @writely/writely

# Or install individual packages for specific functionality
npm install @writely/core @writely/mdx @writely/preview @writely/cli

API

Main Exports

import {
  // Core schemas and themes
  BlogConfig,
  BlogConfigSchema,
  ThemeName,
  getTheme,

  // MDX processing
  processMDXContent,
  serialize,
  rscSerialize,
  MDXRemote,

  // Preview server
  startPreview,
  PreviewServer,
  StaticSiteGenerator,

  // CLI program
  program,
} from "@writely/writely";

Core Package Access

// Direct access to core functionality
import {
  BlogConfig,
  ThemeName,
  getTheme,
  SEOMetaTags,
  MDXFrontmatter,
} from "@writely/core";

// Blog configuration with full type safety
const config: BlogConfig = {
  title: "My Blog",
  description: "A beautiful blog built with Writely",
  author: "Your Name",
  url: "https://myblog.com",
  theme: "nova",
  seo: {
    metatags: {
      description: "My blog description",
      keywords: "blog, writely, mdx",
    },
  },
};

// Validate configuration
const validatedConfig = BlogConfigSchema.parse(config);

// Get theme component
const ThemeComponent = getTheme("nova");

MDX Package Access

// Direct access to MDX functionality
import {
  processMDXContent,
  serialize,
  rscSerialize,
  MDXRemote
} from '@writely/mdx';

// Process MDX content with syntax highlighting
const result = await processMDXContent(content, {
  syntaxHighlighting: {
    theme: 'github-light-default',
    themes: {
      light: 'github-light-default',
      dark: 'github-dark-default'
    }
  }
});

// Serialize MDX for client-side rendering
const compiled = await serialize({
  source: mdxContent,
  parseFrontmatter: true,
  syntaxHighlightingOptions: {
    theme: 'github-light-default'
  }
});

// Render MDX in React Server Components
<MDXRemote
  source={compiled.source}
  components={customComponents}
  syntaxHighlightingOptions={{
    theme: 'github-light-default'
  }}
/>

Preview Package Access

// Direct access to preview functionality
import {
  startPreview,
  PreviewServer,
  StaticSiteGenerator,
} from "@writely/preview";

// Start development server
const server = await startPreview({
  config: blogConfig,
  port: 3000,
  host: "localhost",
  open: true,
});

// Use PreviewServer class for more control
const previewServer = new PreviewServer({
  config: blogConfig,
  port: 3000,
});
await previewServer.start();

// Generate static site
const generator = new StaticSiteGenerator(blogConfig, mdxFiles, "./dist");
await generator.generate();

CLI Package Access

// Direct access to CLI functionality
import { program } from "@writely/cli";

// Access the CLI program
program.parse(process.argv);

// Available commands:
// writely dev - Start development server
// writely build - Build for production
// writely validate - Validate blog configuration
// writely broken-links - Check for broken internal links
// writely init - Initialize new blog project
// writely new-post - Create new blog post

Configuration

The main package uses the same configuration structure as individual packages:

{
  "title": "My Blog",
  "description": "A beautiful blog built with Writely",
  "author": "Your Name",
  "url": "https://myblog.com",
  "language": "en",
  "theme": "nova",
  "seo": {
    "metatags": {
      "description": "My blog description",
      "keywords": "blog, writely, mdx"
    },
    "openGraph": {
      "type": "website",
      "siteName": "My Blog"
    }
  },
  "content": {
    "postsPerPage": 10,
    "defaultLayout": "post",
    "defaultAuthor": "Your Name",
    "defaultTags": ["blog", "writely"]
  },
  "social": {
    "twitter": "@yourusername",
    "github": "yourusername",
    "linkedin": "yourusername"
  },
  "navigation": [
    { "title": "Home", "href": "/" },
    { "title": "About", "href": "/about" },
    { "title": "Blog", "href": "/blog" }
  ]
}

Development

Prerequisites

• Node.js 18.0.0 or higher
• TypeScript 5.3.0 or higher
• pnpm (recommended) or npm

Setup

# Clone the repository
git clone https://github.com/WritelyBlog/writely.git
cd writely/packages/@writely

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run in development mode
pnpm dev

Development Workflow

1. Install Dependencies: pnpm install
2. Build Package: pnpm build
3. Run Tests: pnpm test
4. Lint Code: pnpm lint
5. Watch Mode: pnpm dev

Scripts

• pnpm build - Build the main package with TypeScript compilation
• pnpm dev - Watch mode for development with hot reload
• pnpm lint - Run ESLint with TypeScript support
• pnpm clean - Clean build artifacts and temporary files
• pnpm test - Run unit and integration tests
• pnpm type-check - Run TypeScript type checking
• pnpm format - Format code with Prettier
• pnpm validate - Validate package configuration and dependencies

Architecture

The main package is structured as a unified entry point that re-exports functionality from all sub-packages:

src/
├── index.ts              # Main entry point with re-exports
└── package.json          # Package configuration

# Re-exports from sub-packages:
├── core/                 # Core schemas, themes, utilities
│   ├── schemas/         # Zod schemas for validation
│   ├── themes/          # Theme components and layouts
│   ├── styles/          # Global CSS and design system
│   └── lib/             # Utility functions
├── mdx/                 # MDX processing and rendering
│   ├── client/          # Client-side MDX components
│   ├── server/          # Server-side MDX processing
│   ├── plugins/         # Rehype and remark plugins
│   └── types/           # TypeScript type definitions
├── preview/             # Development server and preview
│   ├── app/             # Next.js app directory
│   └── src/             # Preview server implementation
└── cli/                 # Command-line interface
    └── src/             # CLI commands and utilities

Core Components

Unified Exports: Single import providing access to all Writely functionality.

Type Safety: Full TypeScript support with generated types from Zod schemas.

Modular Architecture: Each sub-package can be used independently or through the main package.

Performance Optimized: Tree-shaking ensures only used functionality is included in bundles.

Runtime Validation: Comprehensive validation using Zod schemas for all configuration and content.

Theme System: 6 professionally designed themes with consistent API and customization options.

MDX Processing: Advanced MDX processing with syntax highlighting, math rendering, and React Server Components support.

Development Tools: Complete development environment with hot reload, file watching, and static generation.

Contributing

1. Fork Repository: Create a fork of the main repository
2. Create Feature Branch: git checkout -b feature/new-feature
3. Make Changes: Implement new functionality with proper TypeScript types
4. Add Tests: Include unit tests for new functionality
5. Update Documentation: Update README and API documentation
6. Run Validation: Ensure all tests pass and code is properly formatted
7. Submit Pull Request: Create detailed pull request with description

Development Guidelines

• Follow TypeScript best practices with strict type checking
• Implement comprehensive error handling with helpful error messages
• Add unit tests for all new functionality
• Maintain backward compatibility for existing APIs
• Use consistent logging and output formatting
• Follow the established code style and architecture patterns
• Ensure all sub-packages are properly integrated and tested

License

MIT License - see LICENSE for details.