Skip to content

Core Highlights

Jump to bottom
github-actions[bot] edited this page Jun 5, 2023 · 427 revisions

core.highlights

No Colour Means no Productivity

Overview

core.highlights maps all possible highlight groups available throughout Neorg under a single tree of highlights: @neorg.*.

Configuration

  • dim (table)

    Handles the dimming of certain highlight groups.

    It sometimes is favourable to use an existing highlight group, but to dim or brighten it a little bit.

    To do so, you may use this table, which, similarly to the highlights table, will concatenate nested trees to form a highlight group name.

    The difference is, however, that the leaves of the tree are a table, not a single string. This table has three possible fields:

    • reference - which highlight to use as reference for the dimming.
    • percentage - by how much to darken the reference highlight. This value may be between -100 and 100, where negative percentages brighten the reference highlight, whereas positive values dim the highlight by the given percentage.
    • markup (table)
      • inline_comment (table)
        • percentage (number) 
          40
        • reference (string) 
          "Normal"
      • verbatim (table)
        • percentage (number) 
          20
        • reference (string) 
          "Normal"
    • tags (table)
      • ranged_verbatim (table)
        • code_block (table)
          • affect (string) 
            "background"
          • percentage (number) 
            15
          • reference (string) 
            "Normal"
  • highlights (table)

    The TS highlights for each Neorg type.

    The highlights table is a large collection of nested trees. At the leaves of each of these trees is the final highlight to apply to that tree. For example: "+@comment" tells Neorg to link to an existing highlight group @comment (denoted by the + prefix). When no prefix is found, the string is treated as arguments passed to :highlight, for example: gui=bold fg=#000000.

    Nested trees concatenate, thus:

    tags = {
ranged_verbatim = {
begin = "+@comment",
},
}

    matches the highlight group:

    @neorg.tags.ranged_verbatim.begin

    and converts into the following command:

    highlight! link @neorg.tags.ranged_verbatim.begin @comment
    • anchors (table)

      Highlights for the anchor syntax: [name]{location}.

      • declaration (table)
        • delimiter (string) 
          "+NonText"
      • definition (table)
        • delimiter (string) 
          "+NonText"
    • definitions (table)

      Highlights for definitions ($ Definition).

      • content (string) 
        "+@text.emphasis"
      • prefix (string) 
        "+@punctuation.delimiter"
      • suffix (string) 
        "+@punctuation.delimiter"
      • title (string) 
        "+@text.strong"
    • delimiters (table)

      Highlights for all the delimiter types. These include:

      • --- - the weak delimiter
      • === - the strong delimiter
      • ___ - the horizontal rule
      • horizontal_line (string) 
        "+@punctuation.delimiter"
      • strong (string) 
        "+@punctuation.delimiter"
      • weak (string) 
        "+@punctuation.delimiter"
    • error (string)

      In case of errors in the syntax tree, use the following highlight.

      "+@error"
    • footnotes (table)

      Highlights for footnotes (^ My Footnote).

      • content (string) 
        "+@text.emphasis"
      • prefix (string) 
        "+@punctuation.delimiter"
      • suffix (string) 
        "+@punctuation.delimiter"
      • title (string) 
        "+@text.strong"
    • headings (table)

      Highlights for each individual heading level.

      • 1 (table)
        • prefix (string) 
          "+@attribute"
        • title (string) 
          "+@attribute"
      • 2 (table)
        • prefix (string) 
          "+@label"
        • title (string) 
          "+@label"
      • 3 (table)
        • prefix (string) 
          "+@constant"
        • title (string) 
          "+@constant"
      • 4 (table)
        • prefix (string) 
          "+@string"
        • title (string) 
          "+@string"
      • 5 (table)
        • prefix (string) 
          "+@label"
        • title (string) 
          "+@label"
      • 6 (table)
        • prefix (string) 
          "+@constructor"
        • title (string) 
          "+@constructor"
    • links (table)
      • description (table)
        • delimiter (string) 
          "+NonText"
      • file (table)
        • delimiter (string) 
          "+NonText"
      • location (table)
        • definition (table)
          • prefix (string) 
            "+@neorg.definitions.prefix"
        • delimiter (string) 
          "+NonText"
        • external_file (table)
          • prefix (string) 
            "+@label"
        • footnote (table)
          • prefix (string) 
            "+@neorg.footnotes.prefix"
        • generic (table)
          • prefix (string) 
            "+@type"
        • heading (table)
          • 1 (table)
            • prefix (string) 
              "+@neorg.headings.1.prefix"
          • 2 (table)
            • prefix (string) 
              "+@neorg.headings.2.prefix"
          • 3 (table)
            • prefix (string) 
              "+@neorg.headings.3.prefix"
          • 4 (table)
            • prefix (string) 
              "+@neorg.headings.4.prefix"
          • 5 (table)
            • prefix (string) 
              "+@neorg.headings.5.prefix"
          • 6 (table)
            • prefix (string) 
              "+@neorg.headings.6.prefix"
        • marker (table)
          • prefix (string) 
            "+@neorg.markers.prefix"
        • url (string) 
          "+@text.uri"
    • lists (table)

      Highlights for all the possible levels of ordered and unordered lists.

      • ordered (table)
        • prefix (string) 
          "+@repeat"
      • unordered (table)
        • prefix (string) 
          "+@punctuation.delimiter"
    • markup (table)

      Highlights for inline markup.

      This is all the highlights like bold, italic and so on.

      • bold (table)
        • delimiter (string) 
          "+NonText"
      • free_form_delimiter (string) 
        "+NonText"
      • inline_comment (table)
        • delimiter (string) 
          "+NonText"
      • inline_macro (table)
        • delimiter (string) 
          "+NonText"
      • inline_math (table)
        • delimiter (string) 
          "+NonText"
      • italic (table)
        • delimiter (string) 
          "+NonText"
      • spoiler (table)
        • delimiter (string) 
          "+NonText"
      • strikethrough (table)
        • delimiter (string) 
          "+NonText"
      • subscript (table)
        • delimiter (string) 
          "+NonText"
      • superscript (table)
        • delimiter (string) 
          "+NonText"
      • underline (table)
        • delimiter (string) 
          "+NonText"
      • verbatim (table)
        • delimiter (string) 
          "+NonText"
    • modifiers (table)

      Inline modifiers.

      This includes:

      • ~ - the trailing modifier
      • All link characters ({, }, [, ], <, >)
      • The escape character (\)
      • escape (string) 
        "+@type"
      • link (string) 
        "+NonText"
    • quotes (table)

      Highlights for all the possible levels of quotes.

      • 1 (table)
        • content (string) 
          "+@punctuation.delimiter"
        • prefix (string) 
          "+@punctuation.delimiter"
      • 2 (table)
        • content (string) 
          "+Blue"
        • prefix (string) 
          "+Blue"
      • 3 (table)
        • content (string) 
          "+Yellow"
        • prefix (string) 
          "+Yellow"
      • 4 (table)
        • content (string) 
          "+Red"
        • prefix (string) 
          "+Red"
      • 5 (table)
        • content (string) 
          "+Green"
        • prefix (string) 
          "+Green"
      • 6 (table)
        • content (string) 
          "+Brown"
        • prefix (string) 
          "+Brown"
    • selection_window (table)

      Highlights displayed in Neorg selection window popups.

      • arrow (string) 
        "+@none"
      • heading (string) 
        "+@annotation"
      • key (string) 
        "+@namespace"
      • keyname (string) 
        "+@constant"
      • nestedkeyname (string) 
        "+@string"
    • tags (table)

      Highlights displayed in all sorts of tag types.

      These include: @, ., |, #, + and =.

      • carryover (table)

        Highlights for the carryover (#, +) tags.

        • begin (string) 
          "+@label"
        • name (table)
          • delimiter (string) 
            "+@none"
          • word (string) 
            "+@label"
        • parameters (string) 
          "+@string"
      • comment (table)

        Highlights for the content of any tag named comment.

        Most prominent use case is for the #comment carryover tag.

        • content (string) 
          "+@comment"
      • ranged_verbatim (table)

        Highlights for the @ verbatim tags.

        • begin (string) 
          "+@keyword"
        • document_meta (table)
          • array (table)
            • bracket (string) 
              "+@punctuation.bracket"
            • value (string) 
              "+@none"
          • authors (string) 
            "+@annotation"
          • categories (string) 
            "+@keyword"
          • created (string) 
            "+@float"
          • description (string) 
            "+@label"
          • key (string) 
            "+@field"
          • number (string) 
            "+@number"
          • object (table)
            • bracket (string) 
              "+@punctuation.bracket"
          • title (string) 
            "+@text.title"
          • trailing (string) 
            "+@repeat"
          • updated (string) 
            "+@float"
          • value (string) 
            "+@string"
          • version (string) 
            "+@float"
        • end (string) 
          "+@keyword"
        • name (table)
          • delimiter (string) 
            "+@none"
          • word (string) 
            "+@keyword"
        • parameters (string) 
          "+@type"
    • todo_items (table)

      Highlights for TODO items.

      This strictly covers the ( ) component of any detached modifier. In other words, these highlights only bother with highlighting the brackets and the content within, but not the object containing the TODO item itself.

      • cancelled (string) 
        "+NonText"
      • done (string) 
        "+@string"
      • on_hold (string) 
        "+@text.note"
      • pending (string) 
        "+@namespace"
      • recurring (string) 
        "+@repeat"
      • uncertain (string) 
        "+@boolean"
      • undone (string) 
        "+@punctuation.delimiter"
      • urgent (string) 
        "+@text.danger"

Required Modules

Required By

🌟 Neorg

Inbuilt modules:
Clone this wiki locally