Advanced MDX processing with syntax highlighting, math support, and React Server Components. Transform markdown into beautiful, interactive content with 200+ languages and 50+ themes.
npm install @writely/mdxAdvanced MDX processing and rendering library for the Writely blog platform. Provides comprehensive MDX processing with syntax highlighting, math rendering, and React Server Components support with 200+ programming languages and 50+ themes.
- Advanced MDX Processing: Comprehensive MDX processing with frontmatter parsing and validation
- Syntax Highlighting: 200+ programming languages with 50+ themes powered by Shiki
- Math Rendering: Mathematical expressions with KaTeX support
- React Server Components: Full RSC support with optimized rendering
- GitHub Flavored Markdown: Complete GFM support with tables, strikethrough, and more
- Smart Typography: Intelligent typography improvements with remark-smartypants
- Performance Optimized: Caching, streaming, and efficient processing
- TypeScript First: Full TypeScript support with comprehensive type definitions
- Custom Components: Flexible component injection for custom MDX elements
- Theme Support: Light/dark mode syntax highlighting with CSS variables
- Error Handling: Robust error handling with helpful error messages
- File Processing: Batch processing of multiple MDX files with progress tracking
``bashInstall the MDX package
npm install @writely/mdx
API
$3
typescript
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'
}
});
// Serialize MDX for React Server Components
const rscResult = await rscSerialize({
source: mdxContent,
parseFrontmatter: true,
syntaxHighlightingOptions: {
theme: 'github-light-default'
}
});
// Render MDX in React Server Components
components={customComponents}
syntaxHighlightingOptions={{
theme: 'github-light-default'
}}
/>
`$3
typescript
import {
processMDXFiles,
AdvancedMDXProcessor,
getMDXPaths,
getMDXByPath,
getMDXByTag,
getMDXByDate,
} from "@writely/mdx";// Process multiple MDX files
const files = [
{ content: "# Post 1", path: "/posts/post-1.mdx" },
{ content: "# Post 2", path: "/posts/post-2.mdx" },
];
const processedFiles = await processMDXFiles(files, {
syntaxHighlighting: {
theme: "github-light-default",
},
});
// Use advanced processor for complex workflows
const processor = new AdvancedMDXProcessor({
theme: "github-light-default",
});
const result = await processor.processFile(content);
const batchResults = await processor.processFiles(files);
// Query MDX files
const paths = getMDXPaths(files);
const post = getMDXByPath(files, "/posts/post-1.mdx");
const taggedPosts = getMDXByTag(files, "javascript");
const recentPosts = getMDXByDate(files);
`$3
typescript
import { createSyntaxHighlightingConfig } from "@writely/mdx";// Create syntax highlighting configuration
const syntaxConfig = createSyntaxHighlightingConfig(
"github-light-default", // theme
"system", // code styling: 'dark' | 'system'
);
// Use with processing functions
const result = await processMDXContent(content, {
syntaxHighlighting: syntaxConfig,
});
`$3
typescript
import type {
MDXDocument,
MDXDocumentFrontmatter,
ProcessedMDXContent,
SyntaxHighlightingConfig,
SupportedLanguage,
ShikiTheme,
} from "@writely/mdx";// MDX document structure
const document: MDXDocument = {
content: "# My Post\n\nContent here...",
frontmatter: {
title: "My Post",
date: "2024-01-01",
tags: ["blog", "mdx"],
},
path: "/posts/my-post.mdx",
};
// Syntax highlighting configuration
const highlighting: SyntaxHighlightingConfig = {
theme: "github-light-default",
themes: {
light: "github-light-default",
dark: "github-dark-default",
},
codeStyling: "system",
};
`Configuration
$3
typescript
interface MDXProcessingConfig {
/* MDX compilation options /
mdxOptions?: SerializeOptions["mdxOptions"];
/* Scope variables for MDX /
scope?: SerializeOptions["scope"];
/* Whether to parse frontmatter /
parseFrontmatter?: SerializeOptions["parseFrontmatter"];
/* Syntax highlighting configuration /
syntaxHighlighting?: SyntaxHighlightingConfig;
}
`$3
typescript
interface SyntaxHighlightingConfig {
/* Single theme for both light and dark modes /
theme?: ShikiTheme;
/* Separate themes for light and dark modes /
themes?: {
light: ShikiTheme;
dark: ShikiTheme;
};
/* Code styling preference /
codeStyling?: "dark" | "system";
}
`$3
The package supports 200+ programming languages including:
- Web Technologies: HTML, CSS, JavaScript, TypeScript, JSX, TSX, Vue, Svelte
- Programming Languages: Python, Java, C++, C#, Rust, Go, Ruby, PHP, Swift
- Scripting Languages: Bash, PowerShell, Lua, Perl, Python
- Data Formats: JSON, YAML, TOML, XML, CSV, GraphQL
- Configuration: Docker, Nginx, Git, Markdown, MDX
- Database: SQL, MongoDB, Redis, Prisma
- Build Tools: Webpack, Vite, Make, CMake, Maven
- Cloud: Kubernetes, Terraform, AWS, Azure, GCP
$3
50+ syntax highlighting themes including:
- GitHub: github-light, github-dark, github-dark-dimmed
- Material: material-theme, material-theme-darker, material-theme-ocean
- Dracula: dracula, dracula-soft
- Catppuccin: catppuccin-latte, catppuccin-frappe, catppuccin-mocha
- Gruvbox: gruvbox-light-medium, gruvbox-dark-medium
- Rose Pine: rose-pine, rose-pine-dawn, rose-pine-moon
- Kanagawa: kanagawa-wave, kanagawa-dragon, kanagawa-lotus
- Popular: night-owl, nord, one-dark-pro, tokyo-night, synthwave-84
Development
$3
- Node.js 18.0.0 or higher
- TypeScript 5.3.0 or higher
- React 18.0.0 or higher
$3
bash
Clone the repository
git clone https://github.com/WritelyBlog/writely.git
cd writely/packages/@writely/mdxInstall dependencies
pnpm installBuild the package
pnpm buildRun in development mode
pnpm dev
`$3
1. Install Dependencies:
2. Build Package:
3. Run Tests:
4. Lint Code:
5. Watch Mode: Scripts
-
- Build the MDX 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 MDX package is structured for modularity, performance, and extensibility:
`
src/
├── index.ts # Main exports and processing functions
├── client/ # Client-side MDX components
│ ├── index.ts # Client exports
│ ├── default.tsx # Default MDX renderer
│ └── rsc.tsx # React Server Components renderer
├── server/ # Server-side MDX processing
│ └── index.ts # Serialization and evaluation functions
├── plugins/ # Rehype and remark plugins
│ ├── index.ts # Plugin exports
│ └── rehype/ # Rehype plugins
│ ├── index.ts # Rehype plugin exports
│ ├── rehypeSyntaxHighlighting.ts # Syntax highlighting plugin
│ ├── shiki-constants.ts # Shiki constants and configurations
│ └── utils.ts # Plugin utilities
└── types/ # TypeScript type definitions
└── index.ts # Comprehensive type definitions
$3
Processing Engine: Advanced MDX processing with frontmatter parsing and validation.
Syntax Highlighting: Shiki-powered syntax highlighting with 200+ languages and 50+ themes.
Math Rendering: KaTeX integration for mathematical expressions and equations.
React Integration: Full support for React Server Components and client-side rendering.
Plugin System: Modular rehype and remark plugin architecture for extensibility.
Type Safety: Comprehensive TypeScript definitions for all functionality.
Performance Optimization: Caching, streaming, and efficient processing for large files.
Error Handling: Robust error handling with helpful error messages and recovery.
Theme Support: Light/dark mode syntax highlighting with CSS variable integration.
File Processing: Batch processing capabilities with progress tracking and error recovery.
Contributing
1. Fork Repository: Create a fork of the main repository
2. Create Feature Branch:
- Follow TypeScript best practices with strict type checking
- Implement comprehensive error handling with helpful error messages
- Add unit tests for all new processing functions and plugins
- Maintain backward compatibility for existing APIs
- Use consistent naming conventions for functions and types
- Follow the established code style and architecture patterns
- Ensure all plugins have proper error handling and performance optimization
MIT License - see LICENSE for details.