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.

This module respects :h conceallevel and :h concealcursor. Setting the wrong values for these options can make it look like this module isn't working.

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

    • spell_check

      (boolean)

      If false will disable spell check on code blocks when 'spell' option is switched on.

      true

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

      • numeric_superscript

        (boolean)

        When set to true, footnote link with numeric title will be concealed to superscripts.

        true

      • render

        (function)

        
        

        module.public.icon_renderers.on_left

      • render_concealed

        (function)

        
        

        module.public.icon_renderers.footnote_concealed

      • title_highlight

        (string)

        
        

        "@neorg.footnotes.title"

  • 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(false)

  • 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(false)

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

    
    

    • icons

      (list)

      
      

      • (string)

        
        

        "1."

      • (string)

        
        

        "A."

      • (string)

        
        

        "a."

      • (string)

        
        

        "(1)"

      • (string)

        
        

        "I."

      • (string)

        
        

        "i."

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

      
      

      module.public.icon_renderers.multilevel_on_right(true)

  • quote

    (table)

    
    

    • clear

      (function)

      
      

      module.public.icon_removers.quote

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

      • (string)

        
        

        "quote2"

      • (string)

        
        

        "quote3"

      • (string)

        
        

        "quote4"

      • (string)

        
        

        "quote5"

      • (string)

        
        

        "quote6"

    • render

      (function)

      
      

      module.public.icon_renderers.quote_concealed

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

Dependencies

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