@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

``bash


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

$3

`typescript
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";
`

$3

`typescript
// 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");
`

$3

`typescript
// 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
source={compiled.source}
components={customComponents}
syntaxHighlightingOptions={{
theme: 'github-light-default'
}}
/>
`

$3

`typescript
// 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();
`

$3

`typescript
// 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:

`json
{
"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

$3

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

$3

`bash


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
`

$3

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
`

$3

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

$3

- 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.