PEG Markdown Highlight

This is a syntax highlighter for the Markdown language, designed to be integrated into GUI text editor programs. It uses a recursive-descent parser for interpreting the input (instead of e.g. regular expressions), and this parser is based on the PEG grammar from John MacFarlane's peg-markdown project.

PEG Markdown Highlight…

• is written in ANSI/ISO C89 with GNU extensions
• has no external dependencies
• is re-entrant
• is probably slower than many simpler (but less correct) highlighting mechanisms but faster than most Markdown compilers
• works (at least) on OS X, Linux and Windows
• is used in shipping software (Mou, MacDown, LightPaper, Erato, CuteMarkEd)
• is dual-licensed under the MIT and GPL2+ licenses.

Doxygen-generated documentation is available.

The source code repository contains examples on how to use this highlighter in Cocoa, GTK+ and Qt GUI applications. The GTK+ and Qt examples are not very polished but the Cocoa support classes are more robust and could probably be used without modification in many cases. A parser for stylesheets is also included so that applications using this highlighter could benefit from a common style definition syntax.

The readme file contains more information.

Why This is Useful

Existing syntax highlighting solutions in (programming) editors are too simple to be able to handle the context sensitivity of the Markdown language, and the fact that it is not well defined. They usually work well for simple cases but fail for many nontrivial inputs that existing Markdown compilers handle correctly. This project is an attempt to bring Markdown syntax highlighting to the same level of “correctness” as the existing compilers.

Quick Code Examples

Here are some quick, simple examples of what it might look like to use this highlighter in your project.

Using the Cocoa highlighter classes to highlight an NSTextView with default settings:

#import "HGMarkdownHighlighter.h"
@interface MyClass : NSObject {
    HGMarkdownHighlighter *highlighter;
}

- (void) awakeFromNib {
    highlighter = [[HGMarkdownHighlighter alloc]
                   initWithTextView:myTextView];
    [highlighter activate];
}

Manually highlighting a TextWidget in some hypothetical GUI framework:

#include "pmh_parser.h"
void highlight(TextWidget *textWidget)
{
    pmh_element **results;
    pmh_markdown_to_elements(textWidget->containedText, pmh_EXT_NONE, &results);
    
    for (int i = 0; i < pmh_NUM_LANG_TYPES; i++) {
        TextStyle style;
        switch (i) {
            case pmh_EMPH: style = ItalicStyle; break;
            case pmh_STRONG: style = BoldStyle; break;
            case pmh_H1: style = LargeFontStyle; break;
            default: style = FunkyStyle; break;
        }
        pmh_element *element_cursor = results[i];
        while (element_cursor != NULL) {
            textWidget->setStyleForSpan(element_cursor->pos,
                                        element_cursor->end,
                                        style);
            element_cursor = element_cursor->next;
        }
    }

    pmh_free_elements(results);
}

Example Program

QarkDown is a simple Markdown editor written in Qt (which means it works on OS X, Linux and Windows). It uses this syntax highlighter and works as a simple hands-on demonstration of its capabilities.

At present time no pre-packaged versions of QarkDown are available but you can build it from sources.

Further Information and Background

I wrote a report about this project as part of my Computer Science Master's studies. It contains, among other things, an evaluation of some existing Markdown compilers (and rationale for the decision to go with peg-markdown) as well as discussion about the design and implementation of the highlighter. It is available as a PDF document:

Adapting a Markdown Compiler's Parser for Syntax Highlighting (1.7 MB PDF)