README

Markdown to Word Converter (Delphi)

A Delphi-based tool that converts Markdown files to Microsoft Word documents (.doc/.docx) with advanced formatting support.

📋 Overview

This project consists of two main components:

1. MarkdownParser.pas - A comprehensive Markdown parser with support for most CommonMark features
2. markdown2doc.dpr - A command-line converter that transforms Markdown files into formatted Word documents

✨ Features

Supported Markdown Elements

• Headings (H1-H6)
• Text formatting: Bold, Italic, Strikethrough, Inline Code
• Blocks: Paragraphs, Blockquotes, Code Blocks (with language specification)
• Lists: Ordered and Unordered (with nested support)
• Tables (with alignment support: left, center, right)
• Horizontal Rules
• Links and Images (local images are embedded, badges are filtered out)
• Line Breaks

Word Document Features

• Proper heading styles (Heading 1-6)
• Table formatting with borders and shading
• Code blocks in monospace font
• Blockquotes with indentation and background shading
• List formatting (bullet points and numbered lists)
• Image embedding (excluding badge images)
• Hyperlink support

Notes:

• The program automatically detects available office suites
• If Word is unavailable, it falls back to LibreOffice/OpenOffice
• Output format is determined by file extension (.docx, .doc, .odt)

🚀 Installation & Requirements

Prerequisites

• Delphi XE2 or later (or Free Pascal/Lazarus with COM support)
• Microsoft Word 2010 or later (for Word automation)
• Windows OS (Word automation requires Windows)

Building from Source

1. Clone the repository
2. Open the project in Delphi/Free Pascal
3. Build the markdown2doc project
4. The executable will be created in the output directory

📖 Usage

Command Line

markdown2doc <input.md> <output.docx>

Examples

# Convert README.md to Word document
markdown2doc README.md documentation.docx

# Convert to .doc format
markdown2doc README.md documentation.doc

🔧 Technical Details

Parser Architecture

The Markdown parser follows a two-phase approach:

1. Block parsing - Identifies and processes structural elements (headings, lists, tables, etc.)
2. Inline parsing - Processes text-level formatting within blocks

Word Automation

The converter uses Microsoft Word's COM automation to create professionally formatted documents with:

• Proper style application
• Table formatting
• Image embedding
• Hyperlink management

File Path Resolution

• Relative image paths are resolved relative to the input Markdown file
• Absolute paths are used as-is
• Badge images (from shields.io) are automatically filtered out

📝 Supported Markdown Syntax

Headings

# Heading 1
## Heading 2
### Heading 3

Text Formatting

**bold text** or __bold text__
*italic text* or _italic text_
~~strikethrough text~~
`inline code`

Lists

- Unordered item 1
- Unordered item 2
  - Nested item

1. Ordered item 1
2. Ordered item 2
   1. Nested ordered

Code Blocks

```pascal
// Code with language specification
procedure Test;
begin
  Writeln('Hello');
end;
```

Tables

| Header 1 | Header 2 | Header 3 |
|----------|:--------:|---------:|
| Cell 1   | Center   | Right    |
| Cell 2   | Cell 3   | Cell 4   |

Blockquotes

> This is a blockquote
> with multiple lines

Links and Images

[Link text](https://example.com)
![Alt text](image.png)

Horizontal Rules

---
***
___

🏗️ Code Structure

MarkdownParser.pas

• TMarkdownElementType - Enumeration of supported element types
• TMarkdownElement - Base class for all document elements
• TMarkdownParser - Main parser class with methods for:
  • Block parsing (ParseBlockElement, ParseHeading, ParseTable, etc.)
  • Inline parsing (ParseInlineElements, ProcessInlineMarkup)
  • HTML conversion (ToHTML method)

markdown2doc Program

• TMarkdownToWordConverter - Main converter class
• Methods for each element type processing
• Word automation and formatting logic
• Path resolution and image filtering

⚙️ Configuration

The converter automatically:

• Uses the input file's directory as the base for relative image paths
• Filters out badge images (containing "badge" or "shields.io" in the path)
• Applies appropriate Word styles to different elements
• Formats tables with proper alignment and borders

🐛 Known Limitations

1. Word Requirement: Requires Microsoft Word installed on the system
2. Windows Only: COM automation is Windows-specific
3. Performance: Large documents may take time to process due to Word automation
4. Markdown Extensions: Some GitHub Flavored Markdown extensions are not supported
5. Image Formats: Only common image formats supported by Word can be embedded

🔄 Extending the Parser

To add new Markdown features:

1. Extend TMarkdownElementType with new element types
2. Add recognition methods in TMarkdownParser
3. Implement parsing logic in new ParseXXX methods
4. Add processing methods in TMarkdownToWordConverter
5. Update the ToHTML method if needed

Example for adding a new element:

// 1. Add to TMarkdownElementType
meNewElement = ...

// 2. Add recognition method
function IsNewElement(const Line: string): Boolean;

// 3. Implement parser
function ParseNewElement: TMarkdownElement;

// 4. Add Word processing
procedure ProcessNewElement(Element: TMarkdownElement; var Range: Variant);

📄 License

MIT License

Copyright (c) 2025 Aleksandr Vorobev aka CynicRus

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Note: This license applies to the code in this repository. The use of Microsoft Word via COM automation may be subject to Microsoft's licensing terms for your specific use case.

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests for:

• Bug fixes
• New Markdown features
• Performance improvements
• Additional documentation

🆘 Support

For issues and questions:

1. Check the known limitations section
2. Ensure Microsoft Word is properly installed
3. Verify image paths are correct
4. Test with simple Markdown files first

Note: This tool is particularly useful for technical documentation, README files, and converting Markdown-based documentation to shareable Word formats.