org-insert-heading is an interactive and byte-compiled function defined in org.el. Signature (org-insert-heading &optional ARG INVISIBLE-OK TOP) Documentation Insert a new heading or an item with the same depth at point. If point is at the beginning of a heading, insert a new heading or a new headline above the current one. When at the beginning of a regular line of text, turn it into a heading. If point is in the middle of a line, split it and create a new headline with the text in the current line after point (see org-M-RET-may-split-line on how to modify this behavior). As a special case, on a headline, splitting can only happen on the title itself. E.g., this excludes breaking stars or tags. With a C-u prefix, set org-insert-heading-respect-content to a non-nil value for the duration of the command. This forces the insertion of a heading after the current subtree, independently on the location of point. With a C-u C-u prefix, insert the heading at the end of the tree above the current heading. For example, if point is within a 2nd-level heading, then it will insert a 2nd-level heading at the end of the 1st-level parent subtree. When INVISIBLE-OK is set, stop at invisible headlines when going back. This is important for non-interactive uses of the command. When optional argument TOP is non-nil, insert a level 1 heading, unconditionally. Key Bindings This command is not in any keymaps. References References in org.el: (defun org-insert-heading-after-current ...) 1 reference (defun org-insert-heading-respect-content ...) 1 reference (defun org-insert-todo-heading ...) 1 reference (defun org-insert-subheading ...) 1 reference (defun org-meta-return ...) 2 references Find all references Functions used by org-insert-heading Debugging Enable edebug Enable tracing Disassemble Forget Source Code ;; Defined in ~/.emacs.doom.d/.local/straight/repos/org/lisp/org.el (defun org-insert-heading (&optional arg invisible-ok top) "Insert a new heading or an item with the same depth at point. If point is at the beginning of a heading, insert a new heading or a new headline above the current one. When at the beginning of a regular line of text, turn it into a heading. If point is in the middle of a line, split it and create a new headline with the text in the current line after point (see `org-M-RET-may-split-line' on how to modify this behavior). As a special case, on a headline, splitting can only happen on the title itself. E.g., this excludes breaking stars or tags. With a `\\[universal-argument]' prefix, set \ `org-insert-heading-respect-content' to a non-nil value for the duration of the command. This forces the insertion of a heading after the current subtree, independently on the location of point. With a `\\[universal-argument] \\[universal-argument]' prefix, \ insert the heading at the end of the tree above the current heading. For example, if point is within a 2nd-level heading, then it will insert a 2nd-level heading at the end of the 1st-level parent subtree. When INVISIBLE-OK is set, stop at invisible headlines when going back. This is important for non-interactive uses of the command. When optional argument TOP is non-nil, insert a level 1 heading, unconditionally." (interactive "P") (let* ((blank? (org--blank-before-heading-p (equal arg '(16)))) (level (org-current-level)) (stars (make-string (if (and level (not top)) level 1) ?*))) (cond ((or org-insert-heading-respect-content (member arg '((4) (16))) (and (not invisible-ok) (invisible-p (max (1- (point)) (point-min))))) ;; Position point at the location of insertion. Make sure we ;; end up on a visible headline if INVISIBLE-OK is nil. (org-with-limited-levels (if (not level) (outline-next-heading) ;before first headline (org-back-to-heading invisible-ok) (when (equal arg '(16)) (org-up-heading-safe)) (org-end-of-subtree))) (unless (bolp) (insert "\n")) (when (and blank? (save-excursion (backward-char) (org-before-first-heading-p))) (insert "\n") (backward-char)) (when (and (not level) (not (eobp)) (not (bobp))) (when (org-at-heading-p) (insert "\n")) (backward-char)) (unless (and blank? (org-previous-line-empty-p)) (org-N-empty-lines-before-current (if blank? 1 0))) (insert stars " ") ;; When INVISIBLE-OK is non-nil, ensure newly created headline ;; is visible. (unless invisible-ok (pcase (get-char-property-and-overlay (point) 'invisible) (`(outline . ,o) (move-overlay o (overlay-start o) (line-end-position 0))) (_ nil)))) ;; At a headline... ((org-at-heading-p) (cond ((bolp) (when blank? (save-excursion (insert "\n"))) (save-excursion (insert stars " \n")) (unless (and blank? (org-previous-line-empty-p)) (org-N-empty-lines-before-current (if blank? 1 0))) (end-of-line)) ((and (org-get-alist-option org-M-RET-may-split-line 'headline) (org-match-line org-complex-heading-regexp) (org-pos-in-match-range (point) 4)) ;; Grab the text that should moved to the new headline. ;; Preserve tags. (let ((split (delete-and-extract-region (point) (match-end 4)))) (if (looking-at "[ \t]*$") (replace-match "") (org-align-tags)) (end-of-line) (when blank? (insert "\n")) (insert "\n" stars " ") (when (org-string-nw-p split) (insert split)))) (t (end-of-line) (when blank? (insert "\n")) (insert "\n" stars " ")))) ;; On regular text, turn line into a headline or split, if ;; appropriate. ((bolp) (insert stars " ") (unless (and blank? (org-previous-line-empty-p)) (org-N-empty-lines-before-current (if blank? 1 0)))) (t (unless (org-get-alist-option org-M-RET-may-split-line 'headline) (end-of-line)) (insert "\n" stars " ") (unless (and blank? (org-previous-line-empty-p)) (org-N-empty-lines-before-current (if blank? 1 0)))))) (run-hooks 'org-insert-heading-hook)) Symbol Properties event-symbol-element-mask (org-insert-heading 0) event-symbol-elements (org-insert-heading) modifier-cache ((0 . org-insert-heading))