The complete Writely blog platform. Everything you need to build, deploy, and manage beautiful blogs with React, MDX, and powerful themes.
npm install @writely/writelyThe 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.
- 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
``bashInstall the complete platform
npm install @writely/writely
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/@writelyInstall dependencies
pnpm installBuild the package
pnpm buildRun 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 devScripts
-
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 dependenciesArchitecture
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 configurationRe-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`- 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
MIT License - see LICENSE for details.