RFC: Syntax Definition Format

Request for Comment: Interested in custom syntaxes in Drafts? Please read below. Would love feedback on the format before it is finalized.

Drafts’ editor supports multiple syntax highlighting options (Like Markdown, Taskpaper, etc.). Currently, only the syntaxes that ship with Drafts are available, but later this year we plan to make a feature available to allow users to create, install and share custom syntax definitions.

This will allow creation of additional options for popular formats not currently supported in Drafts, but also customization of and variations to common formats to support special features, or work with custom themes in different ways. And, yes, custom themes will come along with syntax definitions…details forthcoming.

I have published preliminary syntax definition documentation and would love it people interested in creating custom syntaxes would look it over, ask questions, make suggestions. If there are modifications or improvements needed to the format and related functionality, it will be a lot easier to make before finalizing a format.

Read: Preliminary Syntax Definition Format Documentation

If you have specific ideas for things you’d like to do with custom syntaxes, please bring them up as well. I’m interested to be sure as many options as possible can be supported by the format.

More docs on themes and how syntaxes and themes work together to create the final appearance of text in the editor will be forthcoming as well.


The spec looks great! Looking forward to implementing Fountain syntax for Drafts.


I’ve been waiting for this. Was so happy to hear on MPU that it was imminent. So far, I have two questions:

  1. Can you tell us which text editors’ syntax definition formats were your inspiration? I figure they will be the places to steal ideas. I see hints of TextMate and Sublime Text.
  2. Can you give us a link to the JavaScript definition? I’d like to see a example of a programming language.
1 Like

This is so so great! Love the idea of being able to create an org-mode and BibTex syntax


awesome! I like it, how do you plan to implement an “editor” for the syntax definitions? so can I create a syntax highlighting in drafts directly (with some support e.g. a button to add a pattern and so on) or will we just be able to import a new syntax highlighting?

  1. I looked at both these formats and there are some similarities, but much simplified. Drafts is a notes app, not a code editor, and I wanted to keep the syntax highlighting lightweight and performant…and also more approachable for creating simple variants which might be useful for niche cases in productivity.

  2. I updated the page with links to both JavaScript and Simple List example definition files.

1 Like

There is unlikely to be a syntax editor in the app. At least in the short term. It’s a configuration file, and is best edited in a dedicated editor.

thanks I think you’re right!

maybe somebody creates a syntax highlighting file for the configuration format of the syntax highlighting :smiley:

I’ve not studied the syntax but I have a question:

Could this be used to enforce conformance to a syntax? So, as soon as you type something wrong it highlights this wrong thing in red?

I don’t have any example, of course… :slight_smile:

… Well a simple one would be where you type something and fail to close a bracket before end of line. (REXX would be an example of that - and I’m always miscounting brackets.

(See what I did there?) :slight_smile:

“Enforce” syntax? No. Probably possible to write patterns that would highlight unbalanced brackets, yes…but not really what this is optimized for.

Hi @agiletortoise, great draft.
I am looking forward to use asciidoc(tor) in drafts.

JSON is a good choice but has two limitations:

  • (Minor) Last elements are not allowed to have a Komma
  • (Major) no comments supported (like //)

Microsoft simply ignored both in their Visual Studio Code settings , creating a really stable user experience.

If you could support one or both of that features , it really would be great


1 Like

OK. Thanks. I was just wondering. And bracket matching will be an interesting exercise. I might do it with an action anyway.

Great news! I have looking for this since I tried Drafts for the first time!

I opened the app, checked TaskPaper and thought: “It would be so awesome if instead of TaskPaper this were Org-mode”. And here we are!

There are countless tools to manipulate Org-Mode files and even a basic syntax file for editors like Sublime Text: https://github.com/danielmagnussons/orgmode and TextMate/Textastic.

There is also a formal Syntax definition available, but trying to implement everything would be too much! https://orgmode.org/worg/dev/org-syntax.html

Do you plan to offer any kind of beta testing period to test this feature? I could give it a try to build a minimalistic syntax highlight for the most common 10-15 features in Org-mode (TODO status, schedule, timers, etc).


Looks promising. A thought: perhaps the Task Mark Definitions concept could be expanded to the general case, allowing for more functionality. It seems like it’s two things:

  1. Runs of text which can be interacted with;
  2. Run contents being automatically cycled between several options when interacted with.

The current RFC makes the assumption that you’d just want both of those together, because that’s useful for text-based checkmark todo lists, and that’s fine. But I can think of a number of situations where you’d want to decouple the text-cycling from the generic idea of an interaction (click/tap) hook.

For example, consider how wiki-like apps (such as VoodooPad on the Mac) work: they auto-link PhrasesLikeThis to pages with the same title, creating them if necessary. This RFC almost allows that:

  • It supports highlighting custom runs of text based on patterns.
  • It supports making some of those runs interactable (clickable/tappable).
  • It does not support the custom click-handler you’d need for a given run-definition.

I appreciate that this would mean adding an optional JS handler file to a given syntax-definition, as well as the JSON file itself, but just literally that one thing would massively expand what Drafts can do. It could conceptually be as simple as one additional field in the JSON definition for a given run/pattern, mentioning a JS handler to be called — if available — when such a run was clicked/tapped.

The task management text-swapping behaviour is just a specific implementation of that idea, and could be defaulted to if the relevant fields were present, and the notional handler field was not present.

You could do so much with the idea of a custom click/tap-handler for a given run/pattern of text. Pop-up syntax definitions, wiki functionality, and a thousand other things. Again, I appreciate it’s an expansion a little bit beyond the core concept, but it’s a pretty modest one given the potential it could unlock.

I‘m grateful for the continued active development of Drafts, and its extensibility and customisability. It’s become the BBEdit of my full-time iPad workflow, a worthy replacement for Editorial, and an app I’m glad to support via subscription. Thank you.

1 Like

Definitely interesting ideas. Not likely to make it in the initial release of these features, but worth keeping on the list to consider down the road.

Hopefully, this is the right thread to for asking this question. I’m an amateur when it comes to this sort of thing, but I’m trying to learn. I would love to make/modify a syntax to change the colors displayed in Drafts for MultiMarkdown documents.

I prefer plain text as a backend but sometimes I need colors and font weights to change for information to stand out. For example, I want the block quotes to highlight or change color like they do in Sublime Text’s MarkdownEditing package (or other Markdown apps).

Is there a site anyone recommends to learn how to translate what a line of code like this means? Is there a glossary? Would this be the same time commitment of learning a language like JSON or Python?

"match": "^(#+) ([^\\n]+?)(\\1?)$",

I have no clue what these are referencing, but I would love to learn how to break them down character-by-character to understand their meaning.

1 Like

Creating custom syntax definitions will not require coding, per se, but mostly a good understanding of Regular Expressions, which is how text is matched for rendering in different styles.

Syntaxes define what parts of the text should have styles applied, but you may only need to create custom themes to apply colors, per your example. To put it rather simplified, the syntax definition says “Hey, this bit of text is a markdown quote!”, and the theme says, “Markdown quotes should be italic and red”.

More details will be forthcoming as this feature gets ready to roll out.


I notice the « allowCreate=true » in the open draft url scheme. Is this implemented yet ? The url scheme page does not mention it.

Not a tutorial but a full blown web app with generator and analyzer.

I often use it to decode or fail proof regular expressions

Nice! Looking forward to this feature.

I want to implement WhatsApp formatting syntax. Here in Brazil WhatsApp is the messaging app, and, as part of my job, I use it a ton to create informative texts.

Maybe, if possible, I’ll try my hand at automating splitting the draft into multiple messages, which also has a use case in WhatsApp’s stories, which allegedly support up to 700 characters per story, but it’s somewhat buggy, sometimes accepting much less than that.