Excel to Markdown Conversion

17 Jun 202612 minutes to read

Markdown is a lightweight markup language that adds formatting elements to plain text documents. The .NET Excel (XlsIO) library supports the conversion of Excel to Markdown document and vice versa, which mostly follows the CommonMark specification and GitHub-flavored syntax.

Assemblies and NuGet packages required

Refer to the following links for assemblies and NuGet packages required based on platforms to convert an Excel document to Markdown using the .NET Excel Library (XlsIO).

• Excel to Markdown conversion assemblies
• Excel to Markdown conversion NuGet packages

Convert Excel to Markdown document

Convert an existing Excel file to Markdown using the .NET Excel (XlsIO) library.

The following code example shows how to convert an Excel document to a Markdown file.

C# [Cross-platform]

using (ExcelEngine excelEngine = new ExcelEngine())
{
    IApplication application = excelEngine.Excel;
    application.DefaultVersion = ExcelVersion.Xlsx;

    IWorkbook workbook = application.Workbooks.Open(@"Data/Markdown.xlsx");

    using (FileStream fileStream = new FileStream(@"Output/ExcelToMarkdown.md", FileMode.Create, FileAccess.Write))
    {
        workbook.SaveAs(fileStream, ExcelSaveType.Markdown);
    }
}

C# [Windows-specific]

using (ExcelEngine excelEngine = new ExcelEngine())
{
    IApplication application = excelEngine.Excel;
    application.DefaultVersion = ExcelVersion.Xlsx;

    IWorkbook workbook = application.Workbooks.Open(@"Data/Markdown.xlsx");

    workbook.SaveAs("ExcelToMarkdown.md");
}

VB.NET [Windows-specific]

Using excelEngine As New ExcelEngine()
    Dim application As IApplication = excelEngine.Excel
    application.DefaultVersion = ExcelVersion.Xlsx

    Dim workbook As IWorkbook = application.Workbooks.Open("Markdown.xlsx")

    Using fileStream As New FileStream("ExcelToMarkdown.md", FileMode.Create, FileAccess.Write)
        workbook.SaveAs(fileStream, ExcelSaveType.Markdown)
    End Using
End Using

You can download a complete working sample from this GitHub page.

Customize image saving

Customize the image path

XlsIO provides an ImageNodeVisited event, which is used to customize the image path in the output Markdown file and save images externally while converting an Excel document to a Markdown file.

The following code example illustrates how to save image files during Excel to Markdown Conversion.

C# [Cross-platform]

using (ExcelEngine excelEngine = new ExcelEngine())
{
    IApplication application = excelEngine.Excel;

    IWorkbook workbook = application.Workbooks.Open(@"Data/Markdown.xlsx");

    MarkdownExportOptions exportOptions = new MarkdownExportOptions();
    exportOptions.SaveOptions.ImageNodeVisited += MdExportSettings_ImageNodeVisited;

    using (FileStream fileStream = new FileStream(@"ExcelToMarkdown.md", FileMode.Create, FileAccess.Write))
    {
        workbook.SaveAs(fileStream, exportOptions);
    }
}

C# [Windows-specific]

using (ExcelEngine excelEngine = new ExcelEngine())
{
    IApplication application = excelEngine.Excel;

    IWorkbook workbook = application.Workbooks.Open(@"Data/Markdown.xlsx");

    MarkdownExportOptions exportOptions = new MarkdownExportOptions();
    exportOptions.SaveOptions.ImageNodeVisited += MdExportSettings_ImageNodeVisited;

    workbook.SaveAs("ExcelToMarkdown.md", exportOptions);
}

VB.NET [Windows-specific]

Using excelEngine As New ExcelEngine()
    Dim application As IApplication = excelEngine.Excel

    Dim workbook As IWorkbook = application.Workbooks.Open("Markdown.xlsx")

    ' Configure Markdown export options
    Dim exportOptions As New MarkdownExportOptions()
    AddHandler exportOptions.SaveOptions.ImageNodeVisited, AddressOf MdExportSettings_ImageNodeVisited

    ' Save as Markdown file
    Using fileStream As New FileStream("Output.md", FileMode.Create, FileAccess.Write)
        workbook.SaveAs(fileStream, exportOptions)
    End Using
End Using

The following code examples show the event handler to customize the image path and save the image in an external folder.

C# [Cross-platform]

private static void MdExportSettings_ImageNodeVisited(object sender, SaveImageNodeVisitedEventArgs args)
{
    string imagepath = @"D:\Temp\Image1.png";
    //Save the image stream as a file. 
    using (FileStream fileStreamOutput = File.Create(imagepath))
        args.ImageStream.CopyTo(fileStreamOutput);
    //Set the image URI to be used in the output markdown.
    args.Uri = imagepath;
}

C# [Windows-specific]

private static void MdExportSettings_ImageNodeVisited(object sender, SaveImageNodeVisitedEventArgs args)
{
    string imagepath = @"D:\Temp\Image1.png";
    //Save the image stream as a file. 
    using (FileStream fileStreamOutput = File.Create(imagepath))
        args.ImageStream.CopyTo(fileStreamOutput);
    //Set the image URI to be used in the output markdown.
    args.Uri = imagepath;
}

VB.NET [Windows-specific]

Private Sub MdExportSettings_ImageNodeVisited(sender As Object, args As SaveImageNodeVisitedEventArgs)
    Dim imagePath As String = "D:\Temp\Image1.png"
    ' Save the image stream as a file
    Using fileStreamOutput As FileStream = File.Create(imagePath)
        args.ImageStream.CopyTo(fileStreamOutput)
    End Using
    ' Set the image URI to be used in the output markdown
    args.Uri = imagePath
End Sub

You can download a complete working sample from this GitHub page.

Markdown Export Options

PreserveEmptyRow

This property ensures that blank rows in the Excel worksheet are retained in the Markdown output, preserving layout and spacing.

C# [Cross-platform]

// Preserve empty rows during export
MarkdownExportOptions exportOptions = new MarkdownExportOptions();
exportOptions.PreserveEmptyRow = true;

C# [Windows-specific]

// Preserve empty rows during export
MarkdownExportOptions exportOptions = new MarkdownExportOptions();
exportOptions.PreserveEmptyRow = true;

VB.NET [Windows-specific]

' Preserve empty rows during export
Dim exportOptions As New MarkdownExportOptions()
exportOptions.PreserveEmptyRow = True

UseDisplayText

This property exports the formatted display text of cells (e.g., dates or formatted numbers) instead of raw values, making the Markdown output more user‑friendly.

C# [Cross-platform]

// Export formatted display text
MarkdownExportOptions exportOptions = new MarkdownExportOptions();
exportOptions.UseDisplayText = true;

C# [Windows-specific]

// Export formatted display text
MarkdownExportOptions exportOptions = new MarkdownExportOptions();
exportOptions.UseDisplayText = true;

VB.NET [Windows-specific]

' Export formatted display text
Dim exportOptions As New MarkdownExportOptions()
exportOptions.UseDisplayText = True

Markdown save options

The following code examples shows how to save the sheet as markdown file by providing file path directly.

C# [Cross-platform]

IWorksheet worksheet = workbook.Worksheets[0];
MarkdownExportOptions exportOptions = new MarkdownExportOptions();
exportOptions.UseDisplayText = true;

worksheet.SaveAs("Output/ExcelToMarkdown.md", exportOptions);

C# [Windows-specific]

IWorksheet worksheet = workbook.Worksheets[0];
MarkdownExportOptions exportOptions = new MarkdownExportOptions();
exportOptions.UseDisplayText = true;

worksheet.SaveAs("Output/ExcelToMarkdown.md", exportOptions);

VB.NET [Windows-specific]

Dim worksheet As IWorksheet = workbook.Worksheets(0)
Dim exportOptions As New MarkdownExportOptions()
exportOptions.UseDisplayText = True

worksheet.SaveAs("Output/ExcelToMarkdown.md", exportOptions)

The following code examples shows how to save the sheet as markdown file by providing file stream.

C# [Cross-platform]

IWorksheet worksheet = workbook.Worksheets[0];
MarkdownExportOptions exportOptions = new MarkdownExportOptions();
exportOptions.UseDisplayText = true;

FileStream fileStream = new FileStream("Output/ExcelToMarkdown.md", FileMode.Create, FileAccess.Write);
worksheet.SaveAs(fileStream, exportOptions);

C# [Windows-specific]

IWorksheet worksheet = workbook.Worksheets[0];
MarkdownExportOptions exportOptions = new MarkdownExportOptions();
exportOptions.UseDisplayText = true;

FileStream fileStream = new FileStream("Output/ExcelToMarkdown.md", FileMode.Create, FileAccess.Write);
worksheet.SaveAs(fileStream, exportOptions);

VB.NET [Windows-specific]

Dim worksheet As IWorksheet = workbook.Worksheets(0)
Dim exportOptions As New MarkdownExportOptions()
exportOptions.UseDisplayText = True

Dim fileStream As New FileStream("Output/ExcelToMarkdown.md", FileMode.Create, FileAccess.Write)
worksheet.SaveAs(fileStream, exportOptions)

Get MarkdownDocument object

The following code examples shows how to get the MarkdownDocument object from the worksheet using GetMarkdownDocument method.

C# [Cross-platform]

IWorkbook workbook = application.Workbooks.Open("Data/Markdown.xlsx");
IWorksheet worksheet = workbook.Worksheets[0];

MarkdownDocument markdownDocument = worksheet.GetMarkdownDocument();

C# [Windows-specific]

IWorkbook workbook = application.Workbooks.Open("Data/Markdown.xlsx");
IWorksheet worksheet = workbook.Worksheets[0];

MarkdownDocument markdownDocument = worksheet.GetMarkdownDocument();

VB.NET [Windows-specific]

Dim workbook As IWorkbook = application.Workbooks.Open("Data/Markdown.xlsx")
Dim worksheet As IWorksheet = workbook.Worksheets(0)

Dim markdownDocument As MarkdownDocument = worksheet.GetMarkdownDocument()

The following code examples shows how to get the MarkdownDocument object from the workbook using GetMarkdownDocument method.

C# [Cross-platform]

IWorkbook workbook = application.Workbooks.Open("Data/Markdown.xlsx");

 MarkdownDocument markdownDocument = workbook.GetMarkdownDocument();

C# [Windows-specific]

IWorkbook workbook = application.Workbooks.Open("Data/Markdown.xlsx");

 MarkdownDocument markdownDocument = workbook.GetMarkdownDocument();

VB.NET [Windows-specific]

Dim workbook As IWorkbook = application.Workbooks.Open("Data/Markdown.xlsx")

Dim markdownDocument As MarkdownDocument = workbook.GetMarkdownDocument()