Skip to content

Core Highlights

Jump to bottom
github-actions[bot] edited this page May 31, 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).

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

      • ordered (table)
        • 1 (table)
          • content (string) 
            "+@none"
          • prefix (string) 
            "+@repeat"
        • 2 (table)
          • content (string) 
            "+@none"
          • prefix (string) 
            "+@repeat"
        • 3 (table)
          • content (string) 
            "+@none"
          • prefix (string) 
            "+@repeat"
        • 4 (table)
          • content (string) 
            "+@none"
          • prefix (string) 
            "+@repeat"
        • 5 (table)
          • content (string) 
            "+@none"
          • prefix (string) 
            "+@repeat"
        • 6 (table)
          • content (string) 
            "+@none"
          • prefix (string) 
            "+@repeat"
      • unordered (table)
    • 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"
      • trailing (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"
    • 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)
          • authors (string) 
            "+@annotation"
          • categories (string) 
            "+@keyword"
          • created (string) 
            "+@float"
          • description (string) 
            "+@label"
          • key (string) 
            "+@field"
          • number (string) 
            "+@number"
          • object (table)
          • title (string) 
            "[email protected]"
          • 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 (table)
        • content (string) 
          "+@none"
      • done (table)
        • content (string) 
          "+@none"
      • on_hold (table)
        • content (string) 
          "+@none"
      • pending (table)
        • content (string) 
          "+@none"
      • recurring (table)
        • content (string) 
          "+@none"
      • uncertain (table)
        • content (string) 
          "+@none"
      • undone (table)
        • content (string) 
          "+@none"
      • urgent (table)
        • content (string) 
          "+@none"
  • todo_items_match_color (string)

    How to change the colour of TODO items depending on their state.

    This can be one of four values: false, "all", "except_undone" and "cancelled".

    • When set to false the content of TODO items will not be coloured in any special way.
    • When set to "all" the content of TODO items will directly reflect the colour of the item's TODO box.
    • When set to "except_undone", will have the same behaviour as "all" but will exclude undone TODO items.
    • When set to "cancelled" will only highlight the content of TODO items for cancelled tasks.
    "cancelled"

Required Modules

Required By

🌟 Neorg

Inbuilt modules:

Clone this wiki locally