Concealer

core.concealer

Display Markup as Icons, not Text

The concealer module converts verbose markup elements into beautified icons for your viewing pleasure.

Overview

"Concealing" is the process of hiding away from plain sight. When writing raw Norg, long strings like ***** Hello or $$ Definition can be distracting and sometimes unpleasant when sifting through large notes.

To reduce the amount of cognitive load required to "parse" Norg documents with your own eyes, this module masks, or sometimes completely hides many categories of markup.

The concealer depends on Nerd Fonts >=v3.0.1 to be installed on your system.

Configuration

• folds

  (boolean)

  If true, Neorg will enable folding by default for .norg documents. You may use the inbuilt Neovim folding options like foldnestmax, foldlevelstart and others to then tune the behaviour to your liking.

  Set to false if you do not want Neorg setting anything.

  true

• icon_preset

  (string)

  Which icon preset to use.

  The currently available icon presets are:

  • "basic" - use a mixture of icons (includes cute flower icons!)
  • "diamond" - use diamond shapes for headings
  • "varied" - use a mix of round and diamond shapes for headings; no cute flower icons though :(

  "basic"

• icons

  (table)

  Configuration for icons.

  This table contains the full configuration set for each icon, including its query (where to be placed), render functions (how to be placed) and characters to use.

  For most use cases, the only values that you should be changing is the icon/icons field. icon is a string, while icons is a table of strings for multilevel elements like headings, lists, and quotes.

  To disable part of the config, replace the table with false, or prepend false and to it. For example: done = false or done = false and { ... }.

  • code_block

    (table)

    Options that control the behaviour of code block dimming (placing a darker background behind @code tags).

    • conceal

      (boolean)

      If true will conceal (hide) the @code and @end portion of the code block.

      false

    • content_only

      (boolean)

      If true will only dim the content of the code block (without the @code and @end lines), not the entirety of the code block itself.

      true

    • highlight

      (string)

      
      

      "@neorg.tags.ranged_verbatim.code_block"

    • insert_enabled

      (boolean)

      
      

      true

    • nodes

      (list)

      
      

      • (string)

        
        

        "ranged_verbatim_tag"

    • padding

      (table)

      Additional padding to apply to either the left or the right. Making these values negative is considered undefined behaviour (it is likely to work, but it's not officially supported).

      • left

        (number)

        
        

        0

      • right

        (number)

        
        

        0

    • render

      (function)

      
      

      module.public.icon_renderers.render_code_block

    • width

      (string)

      The width to use for code block backgrounds.

      When set to fullwidth (the default), will create a background that spans the width of the buffer.

      When set to content, will only span as far as the longest line within the code block.

      "fullwidth"

  • definition

    (table)

    
    

    • multi_prefix

      (table)

      
      

      • icon

        (string)

        
        

        "⋙ "

      • nodes

        (list)

        
        

        • (string)

          
          

          "multi_definition_prefix"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • multi_suffix

      (table)

      
      

      • icon

        (string)

        
        

        "⋘ "

      • nodes

        (list)

        
        

        • (string)

          
          

          "multi_definition_suffix"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • single

      (table)

      
      

      • icon

        (string)

        
        

        "≡"

      • nodes

        (table)

        
        

        • (string)

          
          

          "single_definition_prefix"

        • concealed

          (list)

          
          

          • (string)

            
            

            "link_target_definition"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

  • delimiter

    (table)

    
    

    • horizontal_line

      (table)

      
      

      • highlight

        (string)

        
        

        "@neorg.delimiters.horizontal_line"

      • icon

        (string)

        
        

        "─"

      • left

        (string)

        The starting position of horizontal lines:

        • "window": the horizontal line starts from the first column, reaching the left of the window
        • "here": the horizontal line starts from the node column

        "here"

      • nodes

        (list)

        
        

        • (string)

          
          

          "horizontal_line"

      • render

        (function)

        
        

        module.public.icon_renderers.render_horizontal_line

      • right

        (string)

        The ending position of horizontal lines:

        • "window": the horizontal line ends at the last column, reaching the right of the window
        • "textwidth": the horizontal line ends at column textwidth or 79 when it's set to zero

        "window"

    • strong

      (table)

      
      

      • highlight

        (string)

        
        

        "@neorg.delimiters.strong"

      • icon

        (string)

        
        

        "⟪"

      • nodes

        (list)

        
        

        • (string)

          
          

          "strong_paragraph_delimiter"

      • render

        (function)

        
        

        module.public.icon_renderers.fill_text

    • weak

      (table)

      
      

      • highlight

        (string)

        
        

        "@neorg.delimiters.weak"

      • icon

        (string)

        
        

        "⟨"

      • nodes

        (list)

        
        

        • (string)

          
          

          "weak_paragraph_delimiter"

      • render

        (function)

        
        

        module.public.icon_renderers.fill_text

  • footnote

    (table)

    
    

    • multi_prefix

      (table)

      
      

      • icon

        (string)

        
        

        "⁑ "

      • nodes

        (list)

        
        

        • (string)

          
          

          "multi_footnote_prefix"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • multi_suffix

      (table)

      
      

      • icon

        (string)

        
        

        "⁑ "

      • nodes

        (list)

        
        

        • (string)

          
          

          "multi_footnote_suffix"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • single

      (table)

      
      

      • icon

        (string)

        
        

        "⁎"

      • nodes

        (table)

        
        

        • (string)

          
          

          "single_footnote_prefix"

        • concealed

          (list)

          
          

          • (string)

            
            

            "link_target_footnote"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

  • heading

    (table)

    
    

    • highlights

      (list)

      
      

      • (string)

        
        

        "@neorg.headings.1.prefix"

      • (string)

        
        

        "@neorg.headings.2.prefix"

      • (string)

        
        

        "@neorg.headings.3.prefix"

      • (string)

        
        

        "@neorg.headings.4.prefix"

      • (string)

        
        

        "@neorg.headings.5.prefix"

      • (string)

        
        

        "@neorg.headings.6.prefix"

    • icons

      (list)

      
      

      • (string)

        
        

        "◉"

      • (string)

        
        

        "◎"

      • (string)

        
        

        "○"

      • (string)

        
        

        "✺"

      • (string)

        
        

        "▶"

      • (string)

        
        

        "⤷"

    • nodes

      (table)

      
      

      • (string)

        
        

        "heading1_prefix"

      • (string)

        
        

        "heading2_prefix"

      • (string)

        
        

        "heading3_prefix"

      • (string)

        
        

        "heading4_prefix"

      • (string)

        
        

        "heading5_prefix"

      • (string)

        
        

        "heading6_prefix"

      • concealed

        (list)

        
        

        • (string)

          
          

          "link_target_heading1"

        • (string)

          
          

          "link_target_heading2"

        • (string)

          
          

          "link_target_heading3"

        • (string)

          
          

          "link_target_heading4"

        • (string)

          
          

          "link_target_heading5"

        • (string)

          
          

          "link_target_heading6"

    • render

      (function)

      
      

      module.public.icon_renderers.multilevel_on_right

  • list

    (table)

    
    

    • icons

      (list)

      
      

      • (string)

        
        

        "•"

    • nodes

      (list)

      
      

      • (string)

        
        

        "unordered_list1_prefix"

      • (string)

        
        

        "unordered_list2_prefix"

      • (string)

        
        

        "unordered_list3_prefix"

      • (string)

        
        

        "unordered_list4_prefix"

      • (string)

        
        

        "unordered_list5_prefix"

      • (string)

        
        

        "unordered_list6_prefix"

    • render

      (function)

      
      

      module.public.icon_renderers.multilevel_on_right

  • markup

    (table)

    
    

    • spoiler

      (table)

      
      

      • highlight

        (string)

        
        

        "@neorg.markup.spoiler"

      • icon

        (string)

        
        

        "•"

      • nodes

        (list)

        
        

        • (string)

          
          

          "spoiler"

      • render

        (function)

        
        

        module.public.icon_renderers.fill_multiline_chop2

  • ordered

    (table)

    
    

    • formatters

      (list)

      A list of lua patterns specifying how to format each nesting level of an ordered list.

      %s is substituted with the string returned by the generator.

      • (string)

        
        

        "%s."

      • (string)

        
        

        "%s."

      • (string)

        
        

        "%s."

      • (string)

        
        

        "(%s)"

    • generators

      (list)

      A list of icon generators.

      Icon generators live in the icon_generators namespace. They create a unique ID for each index in the list. This can be as simple as 1, 2, 3, 4... or A, B, C, D..., but one could opt for more complex generators.

      • (function)

        
        

        module.public.icon_generators.numeric

      • (function)

        
        

        module.public.icon_generators.alphanumeric_uppercase

      • (function)

        
        

        module.public.icon_generators.alphanumeric_lowercase

      • (function)

        
        

        module.public.icon_generators.numeric

    • icons

      (list)

      
      

      (not has_anticonceal) and { "⒈", "A", "a", "⑴", "Ⓐ", "ⓐ" } or nil

    • nodes

      (list)

      
      

      • (string)

        
        

        "ordered_list1_prefix"

      • (string)

        
        

        "ordered_list2_prefix"

      • (string)

        
        

        "ordered_list3_prefix"

      • (string)

        
        

        "ordered_list4_prefix"

      • (string)

        
        

        "ordered_list5_prefix"

      • (string)

        
        

        "ordered_list6_prefix"

    • render

      (function)

      
      

      has_anticonceal and module.public.icon_renderers.multilevel_ordered_inline_on_right�                or module.public.icon_renderers.multilevel_ordered_on_right

  • quote

    (table)

    
    

    • highlights

      (list)

      
      

      • (string)

        
        

        "@neorg.quotes.1.prefix"

      • (string)

        
        

        "@neorg.quotes.2.prefix"

      • (string)

        
        

        "@neorg.quotes.3.prefix"

      • (string)

        
        

        "@neorg.quotes.4.prefix"

      • (string)

        
        

        "@neorg.quotes.5.prefix"

      • (string)

        
        

        "@neorg.quotes.6.prefix"

    • icons

      (list)

      
      

      • (string)

        
        

        "│"

    • nodes

      (list)

      
      

      • (string)

        
        

        "quote1_prefix"

      • (string)

        
        

        "quote2_prefix"

      • (string)

        
        

        "quote3_prefix"

      • (string)

        
        

        "quote4_prefix"

      • (string)

        
        

        "quote5_prefix"

      • (string)

        
        

        "quote6_prefix"

    • render

      (function)

      
      

      module.public.icon_renderers.multilevel_copied

  • todo

    (table)

    
    

    • cancelled

      (table)

      
      

      • icon

        (string)

        
        

        ""

      • nodes

        (list)

        
        

        • (string)

          
          

          "todo_item_cancelled"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • done

      (table)

      
      

      • icon

        (string)

        
        

        "󰄬"

      • nodes

        (list)

        
        

        • (string)

          
          

          "todo_item_done"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • on_hold

      (table)

      
      

      • icon

        (string)

        
        

        ""

      • nodes

        (list)

        
        

        • (string)

          
          

          "todo_item_on_hold"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • pending

      (table)

      
      

      • icon

        (string)

        
        

        "󰥔"

      • nodes

        (list)

        
        

        • (string)

          
          

          "todo_item_pending"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • recurring

      (table)

      
      

      • icon

        (string)

        
        

        "↺"

      • nodes

        (list)

        
        

        • (string)

          
          

          "todo_item_recurring"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • uncertain

      (table)

      
      

      • icon

        (string)

        
        

        ""

      • nodes

        (list)

        
        

        • (string)

          
          

          "todo_item_uncertain"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • undone

      (table)

      
      

      • icon

        (string)

        
        

        "×"

      • nodes

        (list)

        
        

        • (string)

          
          

          "todo_item_undone"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

    • urgent

      (table)

      
      

      • icon

        (string)

        
        

        "⚠"

      • nodes

        (list)

        
        

        • (string)

          
          

          "todo_item_urgent"

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

• init_open_folds

  (string)

  When set to auto, Neorg will open all folds when opening new documents if foldlevel is 0. When set to always, Neorg will always open all folds when opening new documents. When set to never, Neorg will not do anything.

  "auto"

Required Modules

• core.autocommands - Handles the creation and management of Neovim's autocommands.
• core.integrations.treesitter - A module designed to integrate Treesitter into Neorg.