Markdown Processor

A Markdown Processor library for Delphi, to process and convert Markdown content to HTML.

The library is the engine that powers the preview of all the Markdown Tools (the Editor, the Shell Extensions Preview panel and the Help Viewer): it takes Markdown text and produces the corresponding HTML, ready to be rendered in an HTML viewer or saved to disk.

It is a pure Delphi library, compatible from Delphi XE3 up to the latest version, and it is also available as a standalone GitHub project: EtheaDev/MarkdownProcessor.

Supported Dialects

The processor implements three different Markdown dialects, selectable at creation time:

Dialect	Description
DaringFireball	The original Markdown specification by John Gruber.
CommonMark	An almost complete implementation of the CommonMark standard.
TxtMark	An enhanced dialect with additional extensions.

In the Markdown Text Editor and in the Preview Settings of the Shell Extensions, the dialect can be chosen from the Markdown processor options in the Settings dialog.

Using the Library

The whole processing is exposed through a single class, TMarkdownProcessor, created via the CreateDialect factory method.

uses
  MarkdownProcessor, MarkdownUtils;

var
  md: TMarkdownProcessor;
  html: string;
begin
  // Create the processor for the desired dialect
  md := TMarkdownProcessor.CreateDialect(mdDaringFireball);
  try
    // When AllowUnsafe = true the processor keeps scripts and raw HTML:
    // enable it only with trusted content.
    md.AllowUnsafe := False;

    // Convert a markdown string to HTML
    html := md.Process(markdownText);
  finally
    md.Free;
  end;
end;

The available dialect values are defined by the TMarkdownProcessorDialect enumeration:

TMarkdownProcessorDialect = (mdDaringFireball, mdCommonMark, mdTxtMark);

Processing a file directly

TMarkdownProcessor also offers a convenience method to read a Markdown file and return its HTML in one call, with an optional encoding:

html := md.ProcessFile('Readme.md', TEncoding.UTF8);

The Public API

Member	Description
class function CreateDialect(dialect: TMarkdownProcessorDialect): TMarkdownProcessor	Creates a processor instance for the requested dialect.
function Process(const ASource: string): string	Converts a Markdown string to HTML.
function ProcessFile(const AFileName: TFileName; const AEncoding: TEncoding = nil): string	Loads a Markdown file and returns its HTML.
property AllowUnsafe: Boolean	When True, raw HTML and scripts in the source are preserved; keep it False for untrusted content.
property Config: TConfiguration	Advanced configuration of the processor (dialect-specific options).

The MarkDownToHTML.exe Utility

The project also ships a small command-line utility, MarkDownToHTML.exe, that converts a Markdown file to an HTML file, with options to choose the stylesheet and the dialect. It is handy for batch conversions or to integrate Markdown-to-HTML generation into a build pipeline.

Security Note

By default the processor runs in a safe mode (AllowUnsafe = False), stripping potentially dangerous content such as embedded scripts. Set AllowUnsafe := True only when you fully trust the source of the Markdown content.

Credits

The library is a Delphi port and evolution of:

• FPC-markdown by Miguel A. Risco-Castillo
• Delphi-markdown by Grahame Grieve (Health Intersections Pty Ltd)

The command-line utility was inspired by a presentation by Marco Breveglieri at the Italian Delphi Day 2020.

License

Licensed under the Apache License, Version 2.0.