diff --git a/doc/outline.txt b/doc/outline.txt index 2f52b2f..a0f493d 100644 --- a/doc/outline.txt +++ b/doc/outline.txt @@ -23,13 +23,11 @@ PREREQUISITES *outline-prerequisites* INSTALLATION *outline-installation* -Packer: +- GitHub repo: `"hedyhli/outline.nvim"` +- Or SourceHut repo: `url = "https://git.sr.ht/~hedy/outline.nvim"` (an + equivalent key to `url` for your plugin manager) ->lua - use 'hedyhli/outline.nvim' -< - -Lazy: +Lazy.nvim example: >lua { @@ -46,14 +44,14 @@ Lazy: }, < -Lazy with lazy-loading: +Lazy.nvim with lazy-loading example: >lua { "hedyhli/outline.nvim", + lazy = true, cmd = { "Outline", "OutlineOpen" }, - keys = { - -- Example mapping to toggle outline + keys = { -- Example mapping to toggle outline { "tt", "Outline", desc = "Toggle outline" }, }, opts = { @@ -62,7 +60,7 @@ Lazy with lazy-loading: }, < -This allows Lazy.nvim to lazy load the plugin on commands `Outline`, +This allows Lazy.nvim to lazy-load the plugin on commands `Outline`, `OutlineOpen`, and your keybindings. @@ -70,23 +68,27 @@ SETUP *outline-setup* Call the setup function with your configuration options. -Note that a call to `.setup()` is _required_ for this plugin to work -(simrat39/symbols-outline.nvim#213). +Note that a call to `.setup()` is **required** for this plugin to work +(otherwise you might see this error: simrat39/symbols-outline.nvim#213). >lua require("outline").setup({}) < +|outline-skip-to-commands| + CONFIGURATION *outline-configuration* The configuration structure has been heavily improved and refactored in this -plugin. For details and reasoning, see |outline-breaking-changes|. +plugin. If you’re migrating from the original symbols-outline, see #12 on +github under "breaking +changes" section. TERMINOLOGY ~ -Check this list if you there’s any confusion with the terms used in the +Check this list if you have any confusion with the terms used in the configuration. - **Provider**: Source of the items in the outline view. Could be LSP, CoC, etc. @@ -100,6 +102,8 @@ configuration. provided by provider. - **Focus**: Which window the cursor is in +|outline-skip-to-commands| + DEFAULT OPTIONS ~ @@ -130,29 +134,33 @@ Default values are shown: -- Auto close the outline window if goto_location is triggered and not for -- peek_location auto_close = false, - -- Automatically go to location in code when navigating outline window. - auto_goto = false, + -- Automatically scroll to the location in code when navigating outline window. + auto_jump = false, -- Vim options for the outline window show_numbers = false, show_relative_numbers = false, + wrap = false, show_cursorline = true, - -- Enable this when you enabled cursorline so your cursor color can + -- Enable this only if you enabled cursorline so your cursor color can -- blend with the cursorline, in effect, as if your cursor is hidden -- in the outline window. -- This is useful because with cursorline, there isn't really a need -- to know the vertical column position of the cursor and it may even -- be distracting, rendering lineno/guides/icons unreadable. - -- This makes your line of cursor look the same as if the cursor wasn't - -- focused on the outline window. + -- This makes your line of cursor have the same color as if the cursor + -- wasn't focused on the outline window. + -- This feature is experimental. hide_cursor = false, - -- Whether to wrap long lines, or let them flow off the window - wrap = false, - -- Whether to focus on the outline window when it is opened. - -- Set to false to remain focus on your previous buffer when opening + -- Whether to auto-focus on the outline window when it is opened. + -- Set to false to *always* retain focus on your previous buffer when opening -- outline. + -- If you enable this you can still use bangs in :Outline! or :OutlineOpen! to + -- retain focus on your code. If this is false, retaining focus will be + -- enforced for :Outline/:OutlineOpen and you will not be able to have the + -- other behaviour. focus_on_open = true, -- Winhighlight option for outline window. -- See :help 'winhl' @@ -163,31 +171,33 @@ Default values are shown: }, outline_items = { - -- Whether to highlight the currently hovered symbol (high cpu usage) + -- Whether to highlight the currently hovered symbol and all direct parents highlight_hovered_item = true, - -- Show extra details with the symbols (lsp dependent) + -- Show extra details with the symbols (lsp dependent) as virtual next show_symbol_details = true, - -- Show line numbers of each symbol next to them. + -- Show corresponding line numbers of each symbol on the left column as + -- virtual text, for quick navigation when not focused on outline. -- Why? See this comment: -- https://github.com/simrat39/symbols-outline.nvim/issues/212#issuecomment-1793503563 show_symbol_lineno = false, }, - -- Options for outline guides. + -- Options for outline guides which help show tree hierarchy of symbols guides = { enabled = true, markers = { + -- It is recommended for bottom and middle markers to use the same number + -- of characters to align all child nodes vertically. bottom = '└', middle = '├', vertical = '│', - horizontal = '─', }, }, symbol_folding = { -- Depth past which nodes will be folded by default autofold_depth = nil, - -- Automatically unfold hovered symbol + -- Automatically unfold currently hovered symbol auto_unfold_hover = true, markers = { '', '' }, }, @@ -218,7 +228,8 @@ Default values are shown: winblend = 0 }, - -- These keymaps can be a string or a table for multiple keys + -- These keymaps can be a string or a table for multiple keys. + -- Set to `{}` to disable. (Using 'nil' will fallback to default keys) keymaps = { show_help = '?', close = {"", "q"}, @@ -230,7 +241,7 @@ Default values are shown: peek_location = "o", -- Visit location in code and close outline immediately goto_and_close = "" - -- Change cursor position of outline window to the current location in code. + -- Change cursor position of outline window to match current location in code. -- "Opposite" of goto/peek_location. restore_location = "", -- Open LSP/provider-dependent symbol hover information @@ -252,8 +263,10 @@ Default values are shown: unfold_all = "E", fold_reset = "R", -- Move down/up by one line and peek_location immediately. - down_and_goto = "", - up_and_goto = "", + -- You can also use outline_window.auto_jump=true to do this for any + -- j/k//. + down_and_jump = "", + up_and_jump = "", }, providers = { @@ -269,12 +282,12 @@ Default values are shown: blacklist = {}, -- You can use a custom function that returns the icon for each symbol kind. -- This function takes a kind (string) as parameter and should return an - -- icon. + -- icon as string. icon_fetcher = nil, -- 3rd party source for fetching icons. Fallback if icon_fetcher returned -- empty string. Currently supported values: 'lspkind' icon_source = nil, - -- The next fall back if both icon_fetcher and icon_source has failed, is + -- The next fallback if both icon_fetcher and icon_source has failed, is -- the custom mapping of icons specified below. The icons table is also -- needed for specifying hl group. icons = { @@ -316,7 +329,7 @@ Default values are shown: < To find out exactly what some of the options do, please see the -|outline-recipes| section of the readme at the bottom for screen-recordings. +|outline-recipes| section at the bottom for screen-recordings/shots. The order in which the sources for icons are checked is: @@ -332,16 +345,16 @@ COMMANDS *outline-commands* - **:Outline[!]** Toggle outline. With bang (`!`) the cursor focus stays in your original window - after opening the outline window. Set `focus_on_win = true` to always use this + after opening the outline window. Set `focus_on_open = true` to always use this behaviour. - **:OutlineOpen[!]** Open outline. With bang (`!`) the cursor focus stays in your original window - after opening the outline window. Set `focus_on_win = true` to always use this + after opening the outline window. Set `focus_on_open = true` to always use this behaviour. - **:OutlineClose** Close outline - **:OutlineFocus** - Toggle focus on outline + Toggle focus between outline and code/source window - **:OutlineFocusOutline** Focus on outline - **:OutlineFocusCode** @@ -351,7 +364,7 @@ COMMANDS *outline-commands* - **:OutlineFollow[!]** Go to corresponding node in outline based on cursor position in code, and focus on the outline window. - With bang, retain focus on the code window. + With bang (`!`), retain focus on the code window. This can be understood as the converse of `goto_location` (see keymaps). `goto_location` sets cursor of code window to the position of outline window, whereas this command sets position in outline window to the cursor position of @@ -361,20 +374,17 @@ COMMANDS *outline-commands* DEFAULT KEYMAPS *outline-default-keymaps* -These mappings are active for the outline window. +These mappings are active only for the outline window. Key Action ------------- ---------------------------------------------------- Esc / q Close outline - ? Show help Enter Go to symbol location in code o Go to symbol location in code without losing focus Shift+Enter Go to symbol location in code and close outline - Ctrl+k Go up and goto location - Ctrl+j Go down and goto location Ctrl+g Update outline window to focus on code location - Ctrl+Space Hover current symbol (provider action) K Toggles the current symbol preview + Ctrl+Space Hover current symbol (provider action) r Rename symbol a Code actions h Fold symbol or parent symbol @@ -384,6 +394,9 @@ These mappings are active for the outline window. W Fold all symbols E Unfold all symbols R Reset all folding + Ctrl+k Go up and peek location + Ctrl+j Go down and peek location + ? Show current keymaps as a vim message HIGHLIGHTS *outline-highlights* @@ -536,7 +549,7 @@ location directly and not use the preview window: >lua outline_window = { - auto_goto = true, + auto_jump = true, }, < @@ -546,7 +559,7 @@ This feature was added by @stickperson in an upstream PR 🙌 https://github.com/hedyhli/outline.nvim/assets/50042066/3d06e342-97ac-400c-8598-97a9235de66c Or, you can use keys `` and `` to achieve the same effect, whilst not -having `auto_goto` on by default. +having `auto_jump` on by default. SYMBOL DETAILS ~