Markdown Document Converter

A TypeScript-based tool for converting Markdown files to HTML, PDF, or Word documents. Features plugin-based extensions and comprehensive logging via Winston.

Features

• Multi-Format Conversion: Transform Markdown files to HTML, PDF, or Word (docx)
• Comprehensive Logging: Track all operations via console and file logging
• Plugin Architecture: Extend functionality with pre- and post-conversion plugins
• Robust Error Handling: Detailed error reporting for efficient debugging

Installation

Install via npm:

npm install -g md-document-converter

Or clone and install manually:

git clone https://github.com/yourusername/md-document-converter.git
cd md-document-converter
npm install

CLI Usage

Convert documents using the command-line interface:

mdconvert <inputFile> [options]

Options

• -f, --format <format>: Output format (html, pdf, docx)
• -o, --output <outputPath>: Output file path
• -c, --css <cssFile>: CSS file for HTML/PDF styling
• -h, --help: Display help information

Example

Convert to PDF:

mdconvert input.md -f pdf -o output/document.pdf

Programmatic Usage

import { convertMarkdown } from './dist/converter';
import { ConversionOptions } from './dist/types';

const options: ConversionOptions = {
  outputFormat: 'pdf',
  outputPath: 'output/document.pdf',
  metadata: {
    title: 'Converted Document',
    author: 'John Doe'
  },
  cssFile: 'styles/custom.css',
  plugins: [
    {
      beforeConvert: async (content) => {
        return content.replace(/foo/g, 'bar');
      }
    }
  ]
};

convertMarkdown('input.md', options)
  .then((result) => console.log('Conversion succeeded:', result))
  .catch((error) => console.error('Conversion failed:', error));

Logging

The project utilizes Winston for comprehensive logging:

• Console Output: Real-time logging in the terminal
• File Logging: Persistent logs stored in logs/conversion.log
• Log Levels: Configurable levels for errors, warnings, and info messages

Example log entries:

2024-11-13T12:00:00 [ERROR]: FileReadError: Input file not found: input.md
2024-11-13T12:01:00 [INFO]: Conversion succeeded. Output saved at output/document.pdf

Error Handling

Custom error classes provide detailed error information:

• FileReadError: File access and reading issues
• ConversionError: Conversion process failures
• PluginError: Plugin execution problems

Example usage:

import { FileReadError } from './dist/types';

try {
  // File operations
} catch (error) {
  if (error instanceof FileReadError) {
    console.error('File read failed:', error.message);
  }
}

Plugin System

Extend functionality with custom plugins:

const customPlugin: ConverterPlugin = {
  beforeConvert: async (content, options) => {
    return content.replace(/foo/g, 'bar');
  },
  afterConvert: async (result) => {
    console.log('Post-conversion action:', result);
  }
};

Plugin Hooks

• beforeConvert(content, options): Pre-conversion content modification
• afterConvert(result): Post-conversion processing

Quick Start

Convert a Markdown file to PDF:

import { convertMarkdown } from './dist/converter';

convertMarkdown('input.md', { outputFormat: 'pdf' })
  .then((result) => console.log('Conversion successful:', result))
  .catch((error) => console.error('Error during conversion:', error));

Contributing

1. Fork the repository
2. Clone your fork:

git clone https://github.com/yourusername/md-document-converter.git

3. Create a feature branch:

git checkout -b feature/your-feature-name

4. Make your changes
5. Commit changes:

git commit -m "Add your commit message here"

6. Push to your fork:

git push origin feature/your-feature-name

7. Open a Pull Request

Please ensure your code follows our style guidelines and includes appropriate documentation.

License

MIT License