This Week's Sponsor:


Ensure that if a device isn’t secure it can’t access your apps.  It’s Device Trust for Okta.

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 More with Club MacStories

Founded in 2015, Club MacStories has delivered exclusive content every week for over six years.

In that time, members have enjoyed nearly 400 weekly and monthly newsletters packed with more of your favorite MacStories writing as well as Club-only podcasts, eBooks, discounts on apps, icons, and services. Join today, and you’ll get everything new that we publish every week, plus access to our entire archive of back issues and downloadable perks.

The Club expanded in 2021 with Club MacStories+ and Club Premier. Club MacStories+ members enjoy even more exclusive stories, a vibrant Discord community, a rotating roster of app discounts, and more. And, with Club Premier, you get everything we offer at every Club level plus an extended, ad-free version of our podcast AppStories that is delivered early each week in high-bitrate audio.

Choose the Club plan that’s right for you:

  • Club MacStories: Weekly and monthly newsletters via email and the web that are brimming with app collections, tips, automation workflows, longform writing, a Club-only podcast, periodic giveaways, and more;
  • Club MacStories+: Everything that Club MacStories offers, plus exclusive content like Federico’s Automation Academy and John’s Macintosh Desktop Experience, a powerful web app for searching and exploring over 6 years of content and creating custom RSS feeds of Club content, an active Discord community, and a rotating collection of discounts, and more;
  • Club Premier: Everything in from our other plans and AppStories+, an extended version of our flagship podcast that’s delivered early, ad-free, and in high-bitrate audio.