{"id":19579500,"url":"https://github.com/kde/syntax-highlighting","last_synced_at":"2025-07-05T22:40:54.292Z","repository":{"id":10981419,"uuid":"67701919","full_name":"KDE/syntax-highlighting","owner":"KDE","description":"Syntax highlighting Engine for Structured Text and Code.","archived":false,"fork":false,"pushed_at":"2025-07-04T16:34:52.000Z","size":98263,"stargazers_count":154,"open_issues_count":0,"forks_count":68,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-04T17:41:10.153Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://invent.kde.org/frameworks/syntax-highlighting","language":"HTML","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KDE.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/CC0-1.0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"kde","custom":"https://kde.org/community/donations/"}},"created_at":"2016-09-08T12:39:19.000Z","updated_at":"2025-07-04T16:34:55.000Z","dependencies_parsed_at":"2024-03-17T03:55:55.958Z","dependency_job_id":"13be87d7-6ad5-4426-9b9f-4dd75021f6ba","html_url":"https://github.com/KDE/syntax-highlighting","commit_stats":null,"previous_names":[],"tags_count":225,"template":false,"template_full_name":null,"purl":"pkg:github/KDE/syntax-highlighting","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDE%2Fsyntax-highlighting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDE%2Fsyntax-highlighting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDE%2Fsyntax-highlighting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDE%2Fsyntax-highlighting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KDE","download_url":"https://codeload.github.com/KDE/syntax-highlighting/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KDE%2Fsyntax-highlighting/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263818954,"owners_count":23516092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T07:17:23.391Z","updated_at":"2025-07-05T22:40:54.255Z","avatar_url":"https://github.com/KDE.png","language":"HTML","funding_links":["https://github.com/sponsors/kde","https://kde.org/community/donations/"],"categories":[],"sub_categories":[],"readme":"# Syntax Highlighting\n\nSyntax highlighting engine for Kate syntax definitions\n\n## Table of contents\n\n1. [Introduction](#introduction)\n2. [Out of scope](#out-of-scope)\n3. [Syntax definition files](#syntax-definition-files)\n4. [Color theme files](#color-theme-files)\n5. [Build it](#build-it)\n6. [How to contribute](#how-to-contribute)\n   * [Licensing](#licensing)\n   * [Tips for contributing to syntax definition files](#tips-for-contributing-to-syntax-definition-files)\n   * [Adding unit tests for a syntax definition](#adding-unit-tests-for-a-syntax-definition)\n7. [Report bug or help to fix them](#report-bug-or-help-to-fix-them)\n8. [Updating the syntax \u0026 themes pages of the kate-editor.org website](#updating-the-kate-editororgsyntax-website)\n\n## Introduction\n\nThis is a stand-alone implementation of the Kate syntax highlighting engine.\nIt's meant as a building block for text editors as well as for simple highlighted\ntext rendering (e.g. as HTML), supporting both integration with a custom editor\nas well as a ready-to-use QSyntaxHighlighter sub-class.\n\nBesides a C++ API, a [QML API](@ref qml_api) is also provided.\n\n## Out of scope\n\nTo not turn this into yet another text editor, the following things are considered\nout of scope:\n\n* code folding, beyond providing folding range information\n* auto completion\n* spell checking\n* user interface for configuration\n* management of text buffers or documents\n\nIf you need any of this, check out [KTextEditor](https://api.kde.org/frameworks/ktexteditor/html/).\n\n## Syntax definition files\n\nThis library uses Kate syntax definition files for the actual highlighting,\nthe file format is documented [here](https://docs.kde.org/?application=katepart\u0026branch=stable5\u0026path=highlight.html).\n\nMore than 300 syntax definition files are included, that are located\nin **data/syntax/** and have the **.xml** extension. Some files are\ngenerated at compile time, all xml files are available\n[here](https://kate-editor.org/syntax/). Additional ones are\npicked up from the file system if present, so you can easily extend this\nby application-specific syntax definitions for example.\n\nTo install or test a syntax definition file locally, place it in\n**org.kde.syntax-highlighting/syntax/**, which is located in your user directory.\nUsually it is:\n\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eFor local user\u003c/td\u003e\n        \u003ctd\u003e$HOME/.local/share/org.kde.syntax-highlighting/syntax/\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eFor Flatpak packages\u003c/td\u003e\n        \u003ctd\u003e$HOME/.var/app/\u003cem\u003epackage-name\u003c/em\u003e/data/org.kde.syntax-highlighting/syntax/\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eFor Snap packages\u003c/a\u003e\u003c/td\u003e\n        \u003ctd\u003e$HOME/snap/\u003cem\u003epackage-name\u003c/em\u003e/current/.local/share/org.kde.syntax-highlighting/syntax/\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eOn Windows®\u003c/td\u003e\n        \u003ctd\u003e\u0026#37;USERPROFILE\u0026#37;\u0026#92;AppData\u0026#92;Local\u0026#92;org.kde.syntax-highlighting\u0026#92;syntax\u0026#92;\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eOn macOS®\u003c/td\u003e\n        \u003ctd\u003e$HOME/Library/Application Support/org.kde.syntax-highlighting/syntax/\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\nFor more details, see [\"The Highlight Definition XML Format\" (Working with Syntax Highlighting, KDE Documentation)](https://docs.kde.org/?application=katepart\u0026branch=stable5\u0026path=highlight.html#katehighlight-xml-format).\n\nAlso, in **data/schema/** there is a script to validate the syntax definition XML\nfiles. Use the command `validatehl.sh mySyntax.xml`.\n\n## Color theme files\n\nThis library includes the color themes, which are documented\n[here](https://docs.kde.org/?application=katepart\u0026branch=stable5\u0026path=color-themes.html).\n\nThe color theme files use the JSON format and are located in **data/themes/**\nwith the **.theme** extension.\nAdditional ones are also picked up from the file system if present,\nin the **org.kde.syntax-highlighting/themes/** folder of your user directory,\nallowing you to easily add custom color theme files. This location is the same\nas shown in the table of the [previous section](#syntax-definition-files),\nreplacing the **syntax** folder with **themes**.\nFor more details, see [\"The Color Themes JSON Format\" (Working with Color Themes, KDE Documentation)](https://docs.kde.org/?application=katepart\u0026branch=stable5\u0026path=color-themes.html#color-themes-json).\n\nThe [KTextEditor](https://api.kde.org/frameworks/ktexteditor/html/) library\n(used by Kate, Kile and KDevelop, for example) provides a\n[user interface](https://docs.kde.org/?application=katepart\u0026branch=stable5\u0026path=color-themes.html#color-themes-gui)\nfor editing and creating KSyntaxHighlighting color themes, including\na tool for exporting and importing the JSON theme files.\n\nNote that in KDE text editors, the KSyntaxHighlighting color themes are used\n[since KDE Frameworks 5.75](https://kate-editor.org/post/2020/2020-09-13-kate-color-themes-5.75/),\nreleased on October 10, 2020. Previously, Kate's color schemes\n(KConfig based schema config) were used and are now deprecated.\nThe tool **utils/schema-converter/** and the script **utils/kateschema_to_theme_converter.py**\nconvert the old Kate schemas to KSyntaxHighlighting themes.\n\nAlso see [\"Submit a KSyntaxHighlighting Color Theme\" (Kate Editor Website)](https://kate-editor.org/post/2020/2020-09-18-submit-a-ksyntaxhighlighting-color-theme/).\n\n## Build it\n\n1. Create and change into a build directory. Usually, a folder called **build**\n   is created inside the **syntax-highlighting** source directory.\n\n   ```bash\n   mkdir \u003cbuild-directory\u003e\n   cd \u003cbuild-directory\u003e\n   ```\n\n2. Run the configure process with *cmake* and compile:\n\n   ```bash\n   cmake \u003csource-directory\u003e\n   make\n   ```\n\n   For example:\n\n   ```bash\n   git clone git@invent.kde.org:frameworks/syntax-highlighting.git\n   mkdir ./syntax-highlighting/build\n   cd ./syntax-highlighting/build\n   cmake ../\n   make\n   ```\n\n   For more details see [\"Building Kate from Sources on Linux\" (Kate Editor Website)](https://kate-editor.org/build-it/).\n\n   **NOTE:** If running *cmake* shows an error related to your version of KDE\n   Frameworks, you edit the **CMakeLists.txt** file in the line\n   `find_package(ECM 5.XX.X ...)`.\n\n3. To run tests:\n\n   ```bash\n   make test\n   ```\n\n   The tests are located in the **autotests** directory.\n   This command can be used to check changes to units test after modifying some\n   syntax definition file. To add a unit test or update the references, see the\n   section [\"Adding unit tests for a syntax definition\"](#adding-unit-tests-for-a-syntax-definition).\n\n## How to contribute\n\nKDE uses a GitLab instance at **invent.kde.org** for code review. The official\nrepository of the KSyntaxHighlighting framework is [here](https://invent.kde.org/frameworks/syntax-highlighting).\n\nAll the necessary information to send contributions is [here](https://community.kde.org/Infrastructure/GitLab).\n\n### Licensing\n\nContributions to KSyntaxHighlighting shall be licensed under [MIT](LICENSES/MIT.txt).\n\nAll files shall contain a proper \"SPDX-License-Identifier: MIT\" identifier inside a header like:\n\n```cpp\n/*\n    SPDX-FileCopyrightText: 2020 Christoph Cullmann \u003ccullmann@kde.org\u003e\n\n    SPDX-License-Identifier: MIT\n*/\n```\n\n### Tips for contributing to syntax definition files\n\n* If you are modifying an existing syntax definition XML file, you must increase\n  the version number of the language.\n\n* Do not use hard-coded colors, as they may not look good or be illegible in some color\n  themes. Prefer to use the default color styles.\n\n  For more information, see:\n\n    * [Available Default Styles (Working with Syntax Highlighting, KDE Documentation)](https://docs.kde.org/?application=katepart\u0026branch=stable5\u0026path=highlight.html#kate-highlight-default-styles)\n    * [Kate Part (KF5): New Default Styles for better Color Schemes (Kate Editor Website)](https://kate-editor.org/2014/03/07/kate-part-kf5-new-default-styles-for-better-color-schemes/)\n\n* While writing syntax, you can use `ksyntaxhighlighter6` (previously named `kate-syntax-highlighter`) to display the style or others informations associated with each part of text. For example `ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp`.\n\n  On Linux and Unix systems, you can isolate the syntax files to be modified by using the `XDG_DATA_DIRS`\n  environment variable to point to a folder containing `org.kde.syntax-highlighting/syntax/`\n  in which you will put all the files required for a syntax:\n\n  `XDG_DATA_DIRS=mydir ksyntaxhighlighter6 ...`.\n\n* Add test files, these are found in **autotests/input/**.\n  If you are going to add a new syntax XML file, create a new test file; if you\n  are going to modify a XML file, adds examples to existing test files.\n\n  Then, it is necessary to generate and update the files in **autotests/folding/**,\n  **autotests/html/** and **autotests/reference/**, which must be included in the\n  patches. Instructions are [below](#adding-unit-tests-for-a-syntax-definition).\n\n### Adding unit tests for a syntax definition\n\n1. Add an input file into the **autotests/input/** folder, lets call it\n   **test.\u0026lt;language-extension\u0026gt;**.\n\n2. If the file extension is not sufficient to trigger the right syntax definition, you can add an\n   second file **testname.\u0026lt;language-extension\u0026gt;.syntax** that contains the syntax definition name\n   to enforce the use of the right extension.\n\n3. Do `make \u0026\u0026 make test`.\n\n   Note that after adding or modifying something in\n   **\u0026lt;source-directory\u0026gt;/autotests/input/**, an error will be showed when\n   running `make test`, because the references in the source directory do not\n   match the ones now generated.\n\n4. Inspect the outputs found in your binary directory **autotests/folding.out/**,\n   **autotests/html.output/** and **autotests/output/**.\n\n5. If OK, run in the binary folder `./autotests/update-reference-data.sh`\n   to copy the results to the right location.\n   That script updates the references in the source directory in\n   **autotest/folding/**, **autotest/html/** and **autotest/reference/**.\n\n6. Add the result references after the copying to the git.\n\n## Report bug or help to fix them\n\nKDE uses Bugzilla to management of bugs at **bugs.kde.org**. You can see the bugs\nreported of **frameworks-syntax-highlighting** [here](https://bugs.kde.org/describecomponents.cgi?product=frameworks-syntax-highlighting).\n\nAlso, you can report a bug [here](https://bugs.kde.org/enter_bug.cgi?product=frameworks-syntax-highlighting).\n\nHowever, some users often report bugs related to syntax highlighting in\n[kate/syntax](https://bugs.kde.org/buglist.cgi?component=syntax\u0026product=kate\u0026resolution=---)\nand [kile/editor](https://bugs.kde.org/buglist.cgi?component=editor\u0026product=kile\u0026resolution=---).\n\n## Updating the syntax \u0026 themes pages of the kate-editor.org website\n\nTo update the [kate-editor.org/syntax](https://kate-editor.org/syntax/) and\n[kate-editor.org/themes](https://kate-editor.org/themes/) websites\nincluding the update site \u0026 all linked examples/files,\nplease run after successful **build** \u0026 **test** the following make target:\n\n```bash\nmake update_kate_editor_org\n```\n\nThis will clone the [kate-editor.org git](https://invent.kde.org/websites/kate-editor-org)\nfrom *invent.kde.org* into **kate-editor-org** inside the build directory and update the needed things.\n\nYou can afterwards step into **kate-editor-org** and commit \u0026 push the change after review.\n\nThe [kate-editor.org](https://kate-editor.org) webserver will update itself periodically from the repository on *invent.kde.org*.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkde%2Fsyntax-highlighting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkde%2Fsyntax-highlighting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkde%2Fsyntax-highlighting/lists"}