Visibility and folding

Headlines fold by their depth in the outline (a *** headline right under a * one folds one level below it). Plain list items with sub-items or more lines fold one level deeper (cycle_include_plain_lists, org-cycle-include-plain-lists), and drawers and #+begin_/#+end_ blocks one level deeper than what contains them, so a block in a drawer, or a drawer in a quote, center or special block, folds on its own. When the text before a headline ends with at least cycle_separator_lines (2) blank lines, the last one stays visible when the subtree above is folded, and so does the one before a child headline in CONTENTS (org-cycle-separator-lines); a negative value keeps all of those blank lines visible. Blank lines at the end of the file are never hidden (org-cycle-show-empty-lines).

<Tab>           (ctx) Subtree cycling like org-cycle: a folded subtree
                shows its text and its children (CHILDREN); right after
                that, <Tab> shows the whole subtree (SUBTREE); otherwise it
                folds it (FOLDED). A subtree without children goes from
                FOLDED to SUBTREE. On a list item, the same with its
                sub-items. On a drawer, block or inline task line, toggle
                that fold. On text, indent the line like org-indent-line
                (cycle_emulate_tab, org-cycle-emulate-tab: true,
                "white", "whitestart", "exc-hl-bol"; false cycles
                the entry instead). In Insert mode inside a table, move to
                the next field. Cycling shows or hides the outline only:
                drawers, blocks and results keep their folded or open
                state (Emacs never re-hides a drawer while cycling).
                With a count (in place of C-u): 16<Tab> restores the
                startup visibility, 64<Tab> shows everything including
                drawers, and any other N shows the whole subtree of the
                ancestor at level N.
<S-Tab>         Global cycling: OVERVIEW → CONTENTS (headlines only) →
                SHOW ALL when pressed in a row; after any other command
                it starts again from OVERVIEW. OVERVIEW and CONTENTS fold
                the outline; drawers, blocks and #+RESULTS stay as they
                were (blocks fold only with hideblocks, drawers per
                hidedrawers). SHOW ALL shows every headline and block,
                a folded drawer stays folded. CONTENTS also shows inline
                tasks, folded. With a count N, show the headlines with up
                to N stars.
<C-c><Tab>      Fold the subtree, then show the children of the entry (a
                count: that many levels) without its text
                (org-ctrl-c-tab).
<C-c><C-k>      Fold the subtree, then show every headline in it without
                their text, keeping archived subtrees folded
                (org-kill-note-or-show-branches).
<C-c><C-r>      Show the context of the cursor (org-reveal): the headlines
                above it, their children and the current entry. A count 4
                (C-u) also shows the text of the headlines above; 16 the
                parent's whole subtree.
<C-c><C-Tab>    Cycle the subtree even when it is archived
                (:Org force_cycle_archived).
<C-c><C-x>v     Copy the visible text (org-copy-visible).
:Org hide_entry       Hide the text of the entry; its children stay as
                      they are (org-fold-hide-entry).
:Org hide_block_all   Fold every block (org-fold-hide-block-all).
:Org hide_drawer_all  Fold every drawer, or those of the Visual selection
                      (org-fold-hide-drawer-all).

Cycling options: cycle_global_at_bob (org-cycle-global-at-bob) makes <Tab> at the very start of the buffer, not on a headline, cycle the global visibility; cycle_max_level (org-cycle-max-level) makes deeper headlines text for <Tab> (without it, one level less than inlinetask_min_level); cycle_skip_children_state_if_no_children = false (org-cycle-skip-children-state-if-no-children) gives entries without children a CHILDREN state too.

Visibility cycling runs the User autocmds OrgCyclePre before it changes the visibility (org-cycle-pre-hook, and its old name org-pre-cycle-hook) and OrgCycle after (org-cycle-hook). data.state is the new state: "overview", "contents" or "all" for global cycling, "folded", "children" or "subtree" for a headline or item ("empty", before only, for an entry without text); data.lnum is the line cycled:

vim.api.nvim_create_autocmd("User", {
  pattern = "OrgCycle",
  callback = function(ev) print(ev.data.state) end,
})

How much is shown around a location reached by a jump follows fold_show_context_detail (org-fold-show-context-detail), per context: agenda (showing an entry from the agenda), org-goto (goto_heading), occur-tree (sparse-tree searches), tags-tree (tags/property sparse trees), link-search (a link to a search in a file), and default. The spans are "minimal" (the headline, and the entry when not on it), "local" (the headline, its entry and the next headline), "ancestors" (the headline and the ones above it, and the entry when not on the headline), "ancestors-full" (the whole subtree and the headlines above), "lineage" (also the children of the headlines above, the entry and its first child), "tree" (all children) and "canonical" (also the text of the headlines above). A single span (or true = "canonical", false = "minimal") applies to every context.

A closed fold shows its first line as it looks open, as in Emacs: the TODO keyword, priority, tags, links and emphasis keep their highlighting and concealing, followed by ellipsis. The plugin sets 'foldtext' to an empty string for this; the ellipsis is an inline mark that only the windows where the fold is closed show.

Vim folds nest, so a fold that is open shows every line in it: they cannot show the child headlines of an entry while hiding its own text, as the Emacs CONTENTS view, <C-c><Tab>, <C-c><C-k>, #+STARTUP: content and show2levels, and a VISIBILITY: content property do, nor hide the siblings of a sparse-tree match. Those lines are hidden with conceal_lines extmarks (Neovim 0.11 or later, 'conceallevel' 2, set by the plugin), and the headline gets the ellipsis. Hidden lines are never under the cursor: <j> / <k> skip them and other jumps show them (a search, mark, <G> or Ex command landing on the hidden line next to the cursor too) (like Emacs, which never leaves point in invisible text). Edits that touch hidden text follow catch_invisible_edits (org-fold-catch-invisible-edits): typing on a hidden line, typing, <CR> or <BS> at the end of a line followed by hidden lines, <Del> there, <BS> at the start of a line after hidden lines. "smart" (the default) shows the text around and lets typing and <BS> at the end of the visible line through, else refuses the edit; "show-and-error" shows it and refuses; "show" shows it and edits; "error" refuses; false edits. catch_invisible_edits_commands (org-fold-catch-invisible-edits-commands) says which edits are checked, by command: self_insert (typed text), delete_backward_char (<BS>), delete_char (<Del>), return (<CR>) and actions such as meta_return, each "insert", "delete" or "delete-backward" (false: not checked). Hidden lines are shared by the windows showing the buffer (like Emacs invisible text), while folds are per window. Vim's own fold commands (zo, zR, ...) don't show hidden lines; the org commands above do.

Startup visibility comes from #+STARTUP: (overview, content, showall, show2levels … show5levels, showeverything, nofold), falling back to the startup_folded option. Drawers are then folded (hidedrawers, off with nohidedrawers or hide_drawer_startup = false) and so are blocks with hideblocks (or hide_block_startup = true); showing a subtree (<Tab>'s SUBTREE, a VISIBILITY: all property) leaves folded blocks folded, like Emacs. Except with showeverything, a VISIBILITY property (folded, children, content, all) then sets the visibility of its subtree.

Subtrees tagged :ARCHIVE: stay folded when you cycle (TAB, S-TAB, the startup visibility), like Emacs org-cycle-open-archived-trees = nil. Use <C-c><C-Tab> to open one anyway, or set cycle_open_archived_trees = true.

:Org overview, :Org content, :Org show_all, :Org show_everything and :Org set_startup_visibility set the visibility explicitly.

Vim's linewise commands act on a closed fold as a whole (dd on a folded headline deletes the subtree, >> indents all of it); Emacs edits only the visible headline. That is Vim's fold semantics and is not caught.