markdownforge

MarkdownForge

A powerful Node.js CLI tool for forging professional documents from Markdown files to DOCX and PDF formats with full Mermaid diagram support and admonitions. Designed for seamless npx usage without installation.

npm version License: MIT Node.js CI

Features

Quick Start

# Forge a Markdown file to both PDF and DOCX
npx markdownforge document.md

# Forge to PDF only
npx markdownforge document.md --format pdf

# Forge with custom output directory
npx markdownforge document.md --output ./exports

# Forge with GitHub theme
npx markdownforge document.md --theme github --verbose

Installation

No installation required! Just use npx:

npx markdownforge your-document.md

Global Installation

npm install -g markdownforge
markdownforge your-document.md

Local Installation

npm install markdownforge
npx markdownforge your-document.md

Prerequisites

The tool will automatically check for dependencies and provide installation instructions if needed.

Usage

Basic Usage

npx markdownforge <input-file> [options]

Options

Option Short Description Default
--format -f Output formats: pdf, docx, or pdf,docx pdf,docx
--output -o Output directory ./output
--name -n Base name for output files Input filename
--theme -t Theme: default, github, academic default
--diagram-format   Diagram format: png, svg png
--verbose -v Enable verbose logging false
--help -h Show help information  
--version -V Show version number  

Examples

# Basic forging
npx markdownforge README.md

# PDF only with custom name
npx markdownforge docs/guide.md --format pdf --name user-guide

# Academic theme with verbose output
npx markdownforge thesis.md --theme academic --verbose

# Custom output directory
npx markdownforge report.md --output ./exports --name final-report

Mermaid Diagram Support

The tool automatically detects and renders Mermaid diagrams in your Markdown files:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Supported diagram types:

Admonition Support

FileConverter CLI supports styled admonitions (callout boxes) for highlighting important information:

!!! warning "Custom Title"
    This is a warning admonition with a custom title.

!!! note
    This is a note admonition with the default "Note" title.

Supported Admonition Types

Type Icon Use Case
warning ⚠️ Warnings and cautions
note 📝 Important notes
info ℹ️ Additional information
tip 💡 Helpful tips and suggestions
success ✅ Success messages
error ❌ Error messages
danger 🚨 Critical warnings

Admonition Syntax

!!! type "Optional Custom Title"
    Content goes here with 4-space indentation.
    
    Multiple paragraphs are supported.
    
    You can use **bold**, *italic*, and `code` formatting.

Admonitions are rendered with:

See examples/admonitions-demo.md for comprehensive examples.

Configuration

MarkdownForge supports extensive configuration for customizing conversion settings. Create a configuration file in your project root using any of these formats:

Basic Configuration

{
  "format": ["pdf", "docx"],
  "output": "./output",
  "theme": "default",
  "diagramFormat": "png",
  "verbose": false
}

Advanced DOCX Formatting

Customize DOCX output with detailed formatting options:

{
  "docx": {
    "formatting": {
      "headingSpacing": {
        "before": 400,
        "after": 200
      },
      "paragraphSpacing": {
        "before": 0,
        "after": 150
      },
      "sectionSpacing": {
        "before": 300,
        "after": 200
      },
      "fontSize": 22,
      "headingFontSizes": {
        "h1": 32,
        "h2": 28,
        "h3": 24,
        "h4": 22,
        "h5": 20,
        "h6": 18
      },
      "colors": {
        "headings": "2E74B5",
        "text": "000000",
        "code": "D73A49"
      },
      "alignment": {
        "paragraphs": "justified",
        "headings": "left"
      }
    }
  }
}

PDF Configuration

{
  "pdf": {
    "format": "A4",
    "margin": {
      "top": "1in",
      "right": "1in",
      "bottom": "1in",
      "left": "1in"
    },
    "displayHeaderFooter": false,
    "printBackground": true
  }
}

Mermaid Diagram Configuration

{
  "mermaid": {
    "theme": "default",
    "backgroundColor": "white",
    "width": 800,
    "height": 600
  }
}

Configuration Options

Option Type Default Description
format Array ["pdf", "docx"] Output formats
output String "./output" Output directory
theme String "default" Document theme
diagramFormat String "png" Diagram output format
verbose Boolean false Enable verbose logging

DOCX Formatting Options

Option Type Default Description
headingSpacing.before Number 400 Space before headings (twips)
headingSpacing.after Number 200 Space after headings (twips)
paragraphSpacing.before Number 0 Space before paragraphs (twips)
paragraphSpacing.after Number 150 Space after paragraphs (twips)
sectionSpacing.before Number 300 Space before sections (twips)
sectionSpacing.after Number 200 Space after sections (twips)
fontSize Number 22 Default font size (half-points)
headingFontSizes.h1-h6 Number Various Heading font sizes (half-points)
colors.headings String "2E74B5" Heading color (hex)
colors.text String "000000" Text color (hex)
colors.code String "D73A49" Code color (hex)
alignment.paragraphs String "justified" Paragraph alignment: left, center, right, justified
alignment.headings String "left" Heading alignment: left, center, right, justified

Note: Spacing values are in twips (1/20th of a point). Font sizes are in half-points (22 = 11pt).

Example Configuration File

Copy the example configuration and customize as needed:

cp .markdownforgerc.example .markdownforgerc

Environment Variables

# Disable anonymous usage analytics
export MARKDOWNFORGE_ANALYTICS=false

# Custom temporary directory
export MARKDOWNFORGE_TEMP_DIR=/custom/temp/path

Themes

Available Themes

Theme Description Best For
default Clean, professional styling General documents
github GitHub-flavored styling Technical documentation
academic Academic paper formatting Research papers, reports

Custom Themes

You can create custom themes by providing CSS files:

npx markdownforge document.md --theme ./custom-theme.css

API Usage

You can also use MarkdownForge programmatically:

const { DocumentProcessor } = require('markdownforge');

const processor = new DocumentProcessor({
  format: ['pdf', 'docx'],
  theme: 'github',
  verbose: true
});

async function forge() {
  try {
    const result = await processor.processDocument('./input.md');
    console.log('Forging completed:', result.outputs);
  } catch (error) {
    console.error('Forging failed:', error.message);
  }
}

forge();

Architecture

MarkdownForge is built with a modular architecture:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   CLI Interface │────│ Document         │────│ Output          │
│                 │    │ Processor        │    │ Manager         │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                    ┌───────────┼───────────┐
                    │           │           │
            ┌───────▼────┐ ┌────▼────┐ ┌───▼──────┐
            │  Mermaid   │ │  DOCX   │ │   PDF    │
            │  Renderer  │ │Converter│ │Converter │
            └────────────┘ └─────────┘ └──────────┘

For detailed architecture documentation, see docs/architecture.md.

Performance

Benchmarks

Document Size Processing Time Memory Usage
Small (< 1MB) < 5 seconds < 100MB
Medium (1-10MB) < 30 seconds < 200MB
Large (> 10MB) < 2 minutes < 500MB

Optimization Features

Troubleshooting

Common Issues

Pandoc Not Found

Error: Pandoc not found. Please install Pandoc to enable DOCX conversion.

Solution: Install Pandoc from pandoc.org

Puppeteer Launch Failed

Error: Failed to launch Chrome browser

Solution: Install Chrome dependencies:

Permission Denied

Error: EACCES: permission denied, mkdir './output'

Solution: Check directory permissions or use a different output directory

Debug Mode

Enable verbose logging for detailed troubleshooting:

npx markdownforge document.md --verbose

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/rauofthameem/markdownforge.git
cd markdownforge

# Install dependencies
npm install

# Run tests
npm test

# Run in development mode
npm start -- your-test-file.md

Testing

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Run tests in watch mode
npm run test:watch

Roadmap

License

MIT License - see the LICENSE file for details.

Support

Acknowledgments

Made with ❤️ for forging beautiful documents

NPM

This site is open source. Improve this page.