Skip to content

Config

Jump to bottom
Chris edited this page Mar 29, 2025 · 8 revisions

Dynamic Syntax Highlighting via *.syntax.yaml in config/

If you want to add a new syntax highlighter configuration for a language that we do not support, yet. You can add a *.syntax.yaml file in the config/ directory. You will not have to re-build nor re-install the software to use it. As long as you are running the software from the root directory, it will dynamically load the new files or edition into the editor.

The *.syntax.yaml files defines syntax highlighting rules for a specific file type. You can add any regular expression (Regex) to any existing file to help use extend the current syntax highlioghting.

Warning

Only one file per languages as adding a second file for a language will overwrite the next matching.

Below is a generic explanation of the structure to help future contributors understand and extend it.

File Extensions

extensions: [ext1, ext2, ext3]
  • Purpose: Specifies the file extensions this syntax highlighting applies to.
  • How to Extend: Add additional extensions to the list if needed.

Note

You can have multiple file extensions in the same YAML file, but all the configuration from that file will be applied to every file in the extension list. This is useful if the languages have the same syntax highlight patterns.

Syntax Categories

Each category defines under keywords has a specific type of syntax element (e.g., keywords, comments, strings) and how it should be highlighted.

Example Structure:

categoryName:
  - regex: "your-regex-pattern" # (required)
    color: "#RRGGBB"            # Hexadecimal color code for the matched text (required)
    bold: true                  # Optional: Makes the text bold
    italic: true                # Optional: Makes the text italicized

One category can have multiple regular expressions defined. As long as you maintain the same structure (regex, color), it will be fine (see existing file for example).

Common Categories

Below are common categories you might encounter or want to add:

  1. Keywords

    • Purpose: Matches reserved words or special terms.
    • How to Extend: Add new terms to the regex pattern or create additional entries for different keyword groups.

  2. Comments

    • Purpose: Matches single-line or multi-line comments.
    • How to Extend: Add support for different comment styles (e.g.,/, /* ... */, #).

  3. Strings

    • Purpose: Matches text enclosed in quotes.
    • How to Extend: Add support for different string formats (e.g., single quotes, raw strings).

  4. Numbers

    • Purpose: Matches numeric literals.
    • How to Extend: Add support for different number formats (e.g., integers, floats, hexadecimals).

  5. Functions or Identifiers

    • Purpose: Matches function names, variable names, or other identifiers.
    • How to Extend: Adjust the regex to include or exclude specific patterns.

  6. Qualified Names

    • Purpose: Matches names with qualifiers (e.g., namespaces, modules).
    • How to Extend: Add support for additional qualifiers or nested structures.

General Guidelines for Contributors

  • Follow the Structure: Each syntax category should have a consistent structure with regex, color, and optional attributes like bold or italic.
  • Use Meaningful Colors: Choose colors that are visually distinct and align with common syntax highlighting themes.
  • Test Changes: Verify your changes by testing them on various files to ensure the regex patterns work as expected.
  • Document Additions: Add comments to explain complex regex patterns or new categories for future maintainability.

If you need hexadecimal code color, we are using this website https://colorcodes.io/ for the current one used.

Clone this wiki locally