When you open a document, Textmode detects the document type and automatically applies the appropriate syntax.
Textmode determines which syntax to apply based on the File Mapping rules defined in each syntax definition.
Textmode detects the appropriate syntax in the following order:
Filename:
Textmode first tries to determine the syntax from the entire filename. Filenames are case-sensitive.
.htaccess → Apache
Makefile → Makefile
File extension:
If no syntax is found from the filename, Textmode then tries to determine the syntax from the file extension. Extensions are case-insensitive.
For example:
.html → HTML
.hTmL → HTML
.py → Python
The #! header of the document:
If no syntax is found based on the file extension or filename, and the first line of the document starts with a #! (shebang) header, Textmode tries to determine the syntax from the interpreter specified in the header. The interpreter can be either the last path component following #! or the argument that follows the path when env is used.
For example:
#!/usr/bin/perl → Perl (interpreter: perl)
#!/usr/bin/env python3 → Python (interpreter: python3)
XML declaration:
If no corresponding syntax is found up to this point but the file content starts with an XML declaration, Textmode automatically applies the XML syntax.
For example:
<?xml version="1.0" encoding="utf-8"?> → XML
File type:
If no corresponding syntax is found up to this point but the document has a file type that macOS identifies as a kind of JSON, Textmode automatically applies the JSON syntax.
For example:
.geojson → JSON
None:
If no appropriate syntax can be found, the “None” syntax is applied.
If multiple syntaxes match at the same level, custom syntaxes take precedence over built-in syntaxes. If multiple matches still remain, Textmode uses the syntax that appears first at that priority.
To define rules for mapping files to a syntax, select File Mapping from the list on the left side of the syntax editor, then add file extensions, filenames, or interpreters to the lists on the right. See Define a syntax to learn how to open the syntax editor.
There are no conflicts among the built-in syntaxes. However, if you add custom syntaxes or modify built-in syntaxes, file mappings can conflict. You can check for mapping conflicts by choosing Show File Mapping Conflicts from the More menu in the available syntaxes list in Format settings. If the menu item is dimmed, there are no conflicts.
You can leave file mapping conflicts unresolved as long as documents open with the expected syntax. This doesn’t cause any issues.