This is documentation for as yet unreleased features and is subject to change. Custom syntax definitions are not currently available in Drafts, but will be coming later this year. This documentation is provided to request feedback from parties interested in creating custom syntax definitions.
- What is Developer Mode?
- Enabling Developer Mode PRO
- Developer Workflow
Developer mode is an option in Draft settings that enabled access to file-based custom syntax and theme definitions. When enabled, custom syntax definitions stored in
iCloud Drive/Drafts/Library/Syntaxes, and custom themes stored in
iCloud Drive/Drafts/Library/Themes become available for selection in Editor Preferences.
These file-based syntaxes and themes should only be used for developement purposes. When you have finished a syntax or theme you wish to use in the app, it should be imported into Drafts, so it will sync to all your devices, and load in a performant manner.
Enabling Developer Mode PRO
To enable developer mode, turn on the option in Drafts Preferences. Generally speaking, it’s best to leave the option off if you are not actively working on developing or maintaining custom syntax or theme definitions.
Once enabled, you can make custom syntax and theme definitions available to test in Drafts by placing them in the following folders:
These files should be in JSON format, saved with UTF-8 encoding. The preferred file extensions are
.draftsSyntax for syntaxes, and
.draftsTheme for themes, but
.json files are fine while in development as well.
Drafts does not contain its own JSON editor, edit in your favorite JSON editing tool. Although you can edit JSON files in any text editor, because of the heavy reliance on regular expressions, and the need for properly escaping values, a dedicated JSON editor is helpful. A couple I have used and enjoy:
Generally speaking, the recommended workflow for developing a custom syntax is as below. These steps apply on both iOS and macOS.
- Enable Developer Mode
- In Drafts, choose an existing built-in or custom syntax that most closely matches the syntax you wish to develop. Select this syntax in editor preferences, and export is as a file using the availble share options. Save this file in
iCloud Drive/Drafts/Library/Syntaxes(you may have to create this folder).
- Open your new syntax file in an external JSON editor, make your modifications, and save the file.
- In Drafts, create a testing draft with sample text for your syntax, and select your new file-based syntax as the syntax assigned to the draft.
- As you iterate and make changes to your syntax, save the file, and reload it in Drafts by either selecting a different draft and returning to your testing draft, or re-assigning the syntax to force it to reload from file.
- When you are happy with your syntax, import it into Drafts as a custom syntax using the “Import” options in editor preferences.
- The imported custom syntax can be used in regular production mode.
- Disable Developer Mode.