How to Install MarkDownHelpViewer Delphi component

Installation of Delphi component

If you are a Delphi Developer you can use a component to integrate the help System "embedded" in you application.

The components

There are two viewer components, with the same Markdown properties:

Component	Delphi versions	Rendering
TEdgeMarkdownViewer	Delphi 12 and 13	Microsoft Edge WebView2 (TEdgeBrowser): math formulas (KaTeX), mermaid diagrams, GitHub alerts
TMarkdownViewer	XE6 to Delphi 11 (optional from Delphi 12)	HTMLViewer: math formulas as images, no mermaid diagrams

The Markdown conversion is made by the TMarkdownToHTML engine of the Markdown Processor, so the two viewers have the same properties: ProcessorDialect (default mdGitHub), Extensions (the extensions of the dialect plus the legacy ones), AllowUnsafe, MathRendering (mmrMarkup for TEdgeMarkdownViewer, mmrCodeCogsImage for TMarkdownViewer), CssStyle, MarkdownContent, HtmlContent, FileName, ServerRoot, HelpKeyword/HelpContext (automatic loading of the help files), OnFileNameClicked, OnURLClicked.

TEdgeMarkdownViewer has also:

• DefFontName, DefFontSize, DefFontColor, DefBackground, DefHotSpotColor: the base style of the page (the same names of THTMLViewer);
• ScriptsFolder: the local folder of KaTeX and mermaid.js (katex\ with katex.min.css, katex.min.js, contrib\auto-render.min.js and fonts\, mermaid\mermaid.min.js). When it is empty the viewer looks for a Scripts folder next to the executable or in its parent folder (FindScriptsFolder), otherwise it loads the scripts from CDN; EffectiveScriptsFolder returns the folder actually used;
• UserDataFolder: the WebView2 data folder (default: %LOCALAPPDATA%\<application>\WebView2);
• EdgeAvailable (class function): True when WebView2Loader.dll and the WebView2 runtime are available;
• ExportToPDF, ExportToFileHTMLPage, CopyToClipboard, SelectAll, OnContentLoaded;
• SaveAsHTMLPage, DocumentFileName, OnSaveAs: the "Save as" of WebView2 (context menu, Ctrl+S) saves the full page with SaveAsHTMLPage, which proposes the name of DocumentFileName (set by LoadFromFile), or calls OnSaveAs when assigned, so that the application can use its own export (from Delphi 13; with Delphi 12 "Save as" is removed from the context menu). DocumentFileName is also the title of the page, the name proposed by the print dialog of WebView2: set it when the content is not loaded by LoadFromFile;
• PrintPage(APrinterName, ACopies): prints the page without dialogs on a printer (empty: the default one), with header and footer (date, title, file name of the document, page number), as the print preview of WebView2. For example, after the choice of the printer:

if PrintDialog.Execute then
  EdgeMarkdownViewer.PrintPage(Printer.Printers[Printer.PrinterIndex], PrintDialog.Copies);

The images, the videos and the links of the document are resolved as a browser does, relative to the folder of the document (FileName, or ServerRoot): write them with /, as explained in Local images, videos and links. A link to a local video opens the player of the system (TMarkdownViewer shows the videos as links); the unit MarkDownViewerCommon exposes the same rules to the applications: URLToLocalFileName (the local file of a URL) and OpenVideoFile.

Installation of Packages

To install the components, you need to clone the sources from the Markdown Help Viewer Github Project.

Open the correct group-project file for your Delphi version, located into Packages folder (for example: Packages\D13\MarkDownViewerGroup.groupproj), or run the build script of your version (for example: Packages\BuildAllPackagesD13.ps1).

Delphi 12 and 13: build the run-time packages:

• MarkdownProcessorXXX.bpl
• MarkDownViewerXXX.bpl (TEdgeMarkdownViewer: no dependency from HTMLViewer)

and install the design-time package:

• dclMarkDownViewerXXX.bpl

The component TEdgeMarkdownViewer is ready to use. If you still need the old TMarkdownViewer, build also the optional packages FrameViewerXXX.bpl and MarkDownViewerHTMLXXX.bpl and install dclMarkDownViewerHTMLXXX.bpl (they are not in the group project).

From XE6 to Delphi 11: build the run-time packages:

• FrameViewerXXX.bpl
• MarkdownProcessorXXX.bpl
• MarkDownViewerXXX.bpl

and install the design-time package:

• dclMarkDownViewerXXX.bpl

The component TMarkdownViewer is ready to use.

Remember also to add those Search Path:

• {MarkdownViewerInstallDir}\Source
• {MarkdownViewerInstallDir}\Source\Components
• {MarkdownViewerInstallDir}\Source\AppInterface
• {MarkdownViewerInstallDir}\Ext\HTMLViewer\Source (only for TMarkdownViewer)
• {MarkdownViewerInstallDir}\Ext\MarkdownProcessor\source

Deploy an application with TEdgeMarkdownViewer

TEdgeMarkdownViewer uses the Microsoft Edge WebView2 runtime through WebView2Loader.dll, which must be distributed together with your application, next to the executable and in the same 32 or 64 bit version: you can find it in the Bin32 and Bin64 folders of the project (from the Microsoft WebView2 SDK, see Setup\LICENSE-WebView2.txt). Check at runtime with TEdgeMarkdownViewer.EdgeAvailable that both the loader and the WebView2 runtime are available: the Demo shows how to choose the viewer by Delphi version and how to load the loader of the right platform with SetWebView2Path.

Math formulas (KaTeX) and mermaid diagrams are drawn by JavaScript libraries. To show them also without an Internet connection, distribute the Scripts folder of the project (KaTeX 0.16.11 and mermaid 11.17.2, both with the MIT license) next to your executable, or in its parent folder: TEdgeMarkdownViewer finds it automatically. Without it the libraries are loaded from the jsDelivr CDN (the same versions).

if you need package for other Delphi version not included (newer than XE6) please add a new Issue

Syntax Highlighting of Code Blocks

The viewer components show fenced code blocks with syntax highlighting based on the language declared after the opening fence (for example ```delphi or ```json), like on GitHub. Many languages are recognized and the colors follow the theme (light or dark), derived from the viewer background.

Enabling or disabling the support (compile-time)

The syntax highlighting is controlled at compile time by the include file MD_SYNTAX_HIGHLIGHTING compiler directive.

• enabled (default): code blocks are colored. To produce the colors the component uses the SynEdit highlighters, so the SynEdit source is required and linked into your application. Add \Ext\SynEdit\Source to your search path.
• disabled: The component then does not reference SynEdit at all and code blocks are shown as plain monospace text. This is the right choice for a documentation-only viewer that never displays source code, so you don't carry the SynEdit dependency.

This switch affects only the code-block coloring: all the other features of the component work the same way in both modes.