Bug, Feedback, and Crash Reporting Tool for Your Mobile App

CriticMarkup: Plain Text Syntax for Editorial Reviews



Gabe Weatherhead is a good friend who writes and makes great stuff. Together with Erik Hess (MacStories readers may remember his particular iPad workflow), he launched CriticMarkup, a new project I’ve helped testing for the past few weeks.

Essentially, CriticMarkup is a plain text syntax for marking up text in editorial reviews. For someone who writes in Markdown and works with a team on a daily basis, CriticMarkup is the missing piece of a puzzle that required using clunky software like Word for Mac to do any sort of change tracking or markup. CriticMarkup feels like an extension of Markdown in that it allows you, through a simple and easily understandable syntax, to insert additions, deletions, substitutions, comments, and highlights into plain text.

The CriticMarkup processor is compatible with Markdown, MultiMarkdown, HTML, and has been tested against LaTeX as well to avoid any possible conflicts. I know Gabe and Erik spent a great amount of time making the syntax both human and computer readable in a way that wouldn’t be difficult to read and process. I very much like the philosophy behind CriticMarkup’s syntax and its simplicity.

Critic Markup can be used in any writing environment without special applications or tool kits. While we have supplied processors and plugins that are compatible with popular apps, they are not required. Critic Markup should be readable inline and clearly indicate the intent of the editor and author.

Critic Markup may be used without a conversion to HTML. However, as with Markdown, HTML may be a desirable format for a more stylized presentation. We have several recommendations for how Critic Markup may be converted to HTML. The intent is to allow the HTML to be used without custom CSS. However, custom CSS may be used to enhance the review process.

Because it is plain text, CriticMarkup is application-agnostic: you can use the syntax in TextEdit and send a marked up file to someone else. However, to fully take advantage of CriticMarkup, Gabe and Erik have created a set of tools to integrate with apps that are commonly used by Markdown and plain text writers: BBEdit, TextExpander, SublimeText, Keyboard Maestro, and OS X Services are all supported in this first release. For instance, there are Keyboard Maestro macros to facilitate the process of inserting placeholders for additions and highlights, or a CLI tool that generates an HTML preview with three separate tabs for Markup (colored additions and deletions), Original, and Edited (marked up document with all changes accepted).

Personally, I’m a big fan of the SublimeText package that Gabe and Erik built to better integrate Sublime – which is my favorite text editor for Markdown on the Mac – with keyboard shortcuts to make working with CriticMarkup easier.

I know Gabe and Erik have solid plans for CriticMarkup in the future: they’re seeking feedback from the community, and they’re considering integrating CriticMarkup with more apps and writing tools. Like Markdown and MultiMarkdown, I believe the strength of a plain text syntax lies in the possibility of integrating it with other pieces of software, rather than confining it inside a proprietary application that will never make everyone happy.

For my own workflow, I’m considering how to best integrate CriticMarkup with Kaleidoscope (which already works with plain text but doesn’t have any sort of CriticMarkup-specific coloring) and various iOS apps I’m testing. Obviously, I think it’d be great to see developers natively integrating CriticMarkup into their apps to have GUI elements for actions like accepting changes or adding comments to plain text.

Last year, writing my Mountain Lion review required sending raw MultiMarkdown back and forth with our team and looking at the changes manually without having an immediate overview of what had been added or suggested. CriticMarkup is a great idea, and I recommend you check it out.

Unlock MacStories Extras

Club MacStories offers exclusive access to extra MacStories content, delivered every week; it’s also a way to support us directly.

Club MacStories will help you discover the best apps for your devices and get the most out of your iPhone, iPad, and Mac. It’ll also give you access to advanced iOS shortcuts, tips and tricks, and lots more.

Starting at $5/month, with an annual option available.

Join the Club.

A Club MacStories membership includes:

  • MacStories Weekly newsletter, delivered every week on Friday with app collections, tips, iOS workflows, and more;
  • MacStories Unplugged podcast, published monthly with discussions on what we’re working on and more;
  • Monthly Log newsletter, delivered once every month with behind-the-scenes stories, app notes, personal journals, and more;
  • Access to occasional giveaways, discounts, and free downloads.