Skip to content

Core Highlights

Jump to bottom
github-actions[bot] edited this page Jul 16, 2024 · 423 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).

    • delimiters
      (table)

      Highlights for all the delimiter types. These include:

      • --- - the weak delimiter
      • === - the strong delimiter
      • ___ - the horizontal rule
    • error
      (string)

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

      "+Error"
    • footnotes
      (table)

      Highlights for footnotes (^ My Footnote).

    • 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)
    • lists
      (table)

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

    • 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_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"
      • variable
        (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)
      • 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"
    • rendered
      (table)

      Rendered Latex, this will dictate the foreground color of latex images rendered via core.latex.renderer

      • latex
        (string)         
        "+Normal"
    • selection_window
      (table)

      Highlights displayed in Neorg selection window popups.

      • arrow
        (string)         
        "+@none"
      • heading
        (string)         
        "+@annotation"
      • key
        (string)         
        "+@module"
      • 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.

    • 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.

Dependencies

Required By

🌟 Neorg

Inbuilt modules:
Clone this wiki locally