Define a syntax in CotEditor on Mac

Use the syntax editor in CotEditor to customize built-in syntaxes or create your own.

Open the syntax editor

Go to the CotEditor app on your Mac.
Choose CotEditor > Settings, then click Format.
Do any of the following:
- Customize an existing syntax: Select the syntax you want to customize in the “available syntaxes” list, then double-click the syntax name or click the Edit button.
- Define a new syntax: Click the Add button below the “available syntaxes” list.

Your changes to a built-in syntax are saved as a user customization, and you can restore the original definition whenever needed.

Edit a syntax definition

In the syntax editor, you can configure the following aspects of a syntax definition:

Name: Set the name of the syntax.
Kind: Specify whether the syntax is intended for coding or general-purpose use. This option affects the editor’s font and behavior set in Mode settings.
File Mapping: Define what kind of files use this syntax.
Delimiters: Define comment delimiters, indentation block delimiters, and delimiter escape style.
Outline: Define how outline items are extracted and formatted.
Completion: Define completion candidates.
Syntax highlighting: Define the highlighting rules for each syntax element.
Information: Edit metadata for the syntax definition.
Validation: Check for issues such as invalid regular expressions, duplicate entries, or invalid comment delimiters in the definition.

Syntax parsing methods

CotEditor uses one of two content-parsing methods for syntax highlighting and outline extraction, depending on the syntax:

Parsing method	Description
Regular-expression-based	This method uses keyword and regular-expression pattern matching. In this method, settings in the Delimiters pane are also used to highlight comments, strings, and characters. Because it is defined as a set of matching patterns rather than a full grammar, it is easy to define and customize.
Tree-sitter-based	Tree-sitter is a parser that builds a full syntax tree from source code. Because it understands a language's grammar, it can handle complex constructs such as deeply nested blocks, context-dependent keywords, and multi-line expressions more accurately than regular expressions alone.

Tree-sitter-based parsing is available for about 20 built-in syntaxes, including Swift, Python, JavaScript, HTML, and CSS. Because tree-sitter-based highlighting and outline rules are managed by the app, you cannot customize them or add tree-sitter support for additional syntaxes. By contrast, regular-expression-based syntaxes can be customized in the syntax editor: you can adjust the highlighting rules and outline extraction patterns for each syntax, or create entirely new syntax definitions from scratch.

Note: For performance reasons, the Markdown syntax uses tree-sitter only for outline extraction. Its syntax highlighting remains regular-expression-based.

Export a custom syntax

Go to the CotEditor app on your Mac.
Choose CotEditor > Settings, then click Format.
Select the syntax to export in the “available syntaxes” list.
Do one of the following:
- Click or open the contextual menu for the selected item, then choose Export.
- Click or open the contextual menu for the selected item, choose Share, then choose how to share it.
- Drag the selected item into the Finder.

Note: Only custom syntaxes can be exported. Original built-in syntaxes can’t be exported.

Tip: You can export all custom syntaxes at once as a CotEditor Settings Archive. For details, see Export and import settings.

Import a custom syntax

Go to the CotEditor app on your Mac.
Choose CotEditor > Settings, then click Format.
Do one of the following:
- Click , choose Import, then choose a CotEditor syntax file (.cotsyntax format) to import.
- Drag the CotEditor syntax file (.cotsyntax format) into the “available syntaxes” list.

A CotEditor syntax file is a package file with the .cotsyntax extension.

The Import command can also convert and import legacy YAML-based syntax definitions used before CotEditor 7.0.