Getting Started with Custom Syntaxes

If you are interested in creating custom syntaxes highlighting definitions for Drafts, this forum category has been created as a place to get help and ask questions.

The syntaxes article in the User Guide is the best starting point to understand what syntax definitions are, what they are for, and how to go about creating them:

Once you get through that, export several of the built-in syntaxes as files, and open them in a JSON-friendly editor. We have also created samples for some specific techniques, and popular requested syntaxes, like AsciiDoc and Fountain. These can be found in the syntaxes are of the Directory.


Is there a practical way of working on a custom theme from my phone? I’d use Drafts heavily on my phone, and I’d rather not have to unlimber the laptop every time I want to tweak something.

I’ve tried saving to the iCloud directory as instructed in the documentation. That works. But the. I can’t open it in, say, Jayson. Not sure what I’m doing wrong.

Save the file in iCloud Drive/Library/Syntaxes and rename it with a .json extension. Drafts will still recognize it in developer mode, and Jayson will see it to open as well.

1 Like

I have it in iCloud Drive/Drafts/Library/Syntaxes With a .JSON extension, and it shows up in the Drafts syntaxes pane under the built-in ones. But in Jayson, it is grayed out and can’t be opened.

However, I can navigate to the file in Files and use the share sheet to Open as JSON, which does open the file in Jayson as expected.

Presumably I’m doing something wrong with where I’m saving the file, or how I’m using Jayson?

I’m betting that file actually has a .draftsSyntax file extension and is called MultiMarkdown_mod.json.draftsSyntax. Hence Jayson’s file browser wouldn’t recognise it as JSON, but the icon would show as “SYNTAX” with a Drafts logo.

Here’s the Jayson file browser looking in the Drafts syntax directory where I have placed an original Demo syntax file, and it renamed to have a JSON extension instead. You can see Jayson will allow me to open the JSON file, but not the Drafts Syntax file.

1 Like

You must be right. When I look at the file in the Files app, it doesn’t show a .drafts extension, but it does identify it as a Drafts syntax file, not an ordinary JSON file.

So any ideas for a solution? I’d prefer a way to export from Drafts, edit in Jayson (or another app, if necessary) and reimport to Drafts, all on my phone, without having to use my computer.

If I find myself doing that on i*OS, I use a shortcut I created to create a duplicate with the desired file name, and then I manually delete the original.

Here’s a link to it in case it helps.

Share the file to the Shortcut via the share sheet, modify the existing name when presented, then choose where to save in the file browser. The original file remains, so just decide if you want to delete it or not at that point. Often I leave it as a backup for this like this until I am ready to replace it.

Thank you!! But more evidence that file management on iOS is more or less broken. I constantly marvel at people who can use iOS as their primary platform.

Just in case it is of any use to people, I’ve now added an action to the ThoughtAsylum - Power User action group. It’s called TAD-Toggle Drafts Syntax File, and will display a list of JSON and Drafts Syntax files in the Syntaxes directory. Selecting one will toggle its file extension to the other.


1 Like

Wow, thanks!

I assume there’s a reason @agiletortoise didn’t just require a .json file in the proper directory

File extensions are the basis of the file type registration system on iOS and Mac. Even though the internal content of the file may be JSON, it’s important to have type (.draftsSyntax) that is registered as owned by Drafts, and if you are distributing a syntax file to other others, that provides a file they can just open and install in Drafts without worrying about what type of file it is.

If you send people a .json file they would try to open it and it would most likely end up in a text editor by default. Conversely, there may be a variety of .json files from other sources that are not Drafts syntaxes and that you might want to open in Drafts to edit…so how would Drafts know you are trying to import a syntax?

Aha — that makes sense. It’s much more convenient to be able to open the file and have iOS know that it belongs to Drafts.

I was thinking Drafts would know what to do with a JSON file in the Themes and Syntax subdirectories of its Library directory. Any other JSON files get opened like a text file. But that wouldn’t solve the problem on iOS and macOS opening Drafts JSON files with default apps.

Thank you!