Function: org-insert-heading

org-insert-heading is an interactive and byte-compiled function defined in org.el.gz.

Signature

(org-insert-heading &optional ARG INVISIBLE-OK LEVEL)

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 (universal-argument) prefix, set org-insert-heading-respect-content(var)/org-insert-heading-respect-content(fun) 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 (universal-argument) C-u (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 LEVEL is a number, insert a heading at that level. For backwards compatibility, when LEVEL is non-nil but not a number, insert a level-1 heading.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/org.el.gz
(defun org-insert-heading (&optional arg invisible-ok level)
  "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 LEVEL is a number, insert a heading at
that level.  For backwards compatibility, when LEVEL is non-nil
but not a number, insert a level-1 heading."
  (interactive "P")
  (let* ((blank? (org--blank-before-heading-p (equal arg '(16))))
         (current-level (org-current-level))
         (num-stars (or
                     ;; Backwards compat: if LEVEL non-nil, level is 1
                     (and level (if (wholenump level) level 1))
                     current-level
                     ;; This `1' is for when before first headline
                     1))
         (stars (make-string num-stars ?*))
         (maybe-add-blank-after
          (lambda (blank?)
            "Add a blank line before next heading when BLANK? is non-nil.
Assume that point is on the inserted heading."
            (save-excursion
              (end-of-line)
              (unless (eobp)
                (forward-char)
                (when (and blank? (org-at-heading-p))
                  (insert "\n")))))))
    (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 current-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 invisible-ok 'to-heading)))
      ;; At `point-max', if the file does not have ending newline,
      ;; create one, so that we are not appending stars at non-empty
      ;; line.
      (unless (bolp) (insert "\n"))
      (when (and blank? (save-excursion
                          (backward-char)
                          (org-before-first-heading-p)))
        (insert "\n")
        (backward-char))
      (when (and (not current-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 " " "\n")
      ;; Move point after stars.
      (backward-char)
      ;; Retain blank lines before next heading.
      (funcall maybe-add-blank-after blank?)
      ;; When INVISIBLE-OK is non-nil, ensure newly created headline
      ;; is visible.
      (unless invisible-ok
        (if (eq org-fold-core-style 'text-properties)
	    (cond
	     ((org-fold-folded-p
               (max (point-min)
                    (1- (line-beginning-position)))
               'headline)
	      (org-fold-region (line-end-position 0) (line-end-position) nil 'headline))
	     (t nil))
          (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 "")
		 (when org-auto-align-tags (org-align-tags)))
	       (end-of-line)
	       (when blank? (insert "\n"))
	       (insert "\n" stars " ")
               ;; Retain blank lines before next heading.
               (funcall maybe-add-blank-after blank?)
	       (when (org-string-nw-p split) (insert split))))
	    (t
	     (end-of-line)
	     (when blank? (insert "\n"))
	     (insert "\n" stars " ")
             ;; Retain blank lines before next heading.
             (funcall maybe-add-blank-after blank?))))
     ;; 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)))
      ;; Retain blank lines before next heading.
      (funcall maybe-add-blank-after blank?))
     (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)))
      ;; Retain blank lines before next heading.
      (funcall maybe-add-blank-after blank?))))
  (run-hooks 'org-insert-heading-hook))