@writely/mdx

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

Features

• 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

Installation

# Install the MDX package
npm install @writely/mdx

# Install with peer dependencies
npm install @writely/mdx next-mdx-remote-client shiki rehype-katex remark-katex

API

Core Processing Functions

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

Advanced Processing

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);

Syntax Highlighting Configuration

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,
});

Type Definitions

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

MDX Processing Options

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;
}

Syntax Highlighting Configuration

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";
}

Supported Languages

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

Available Themes

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

Prerequisites

• Node.js 18.0.0 or higher
• TypeScript 5.3.0 or higher
• React 18.0.0 or higher

Setup

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

# 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 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 dependencies

Architecture

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

Core Components

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: git checkout -b feature/new-mdx-feature
3. Make Changes: Implement new functionality with proper TypeScript types
4. Add Tests: Include unit tests for new processing functions and plugins
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 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

License

MIT License - see LICENSE for details.