You can use the
org-element API to figure out where the current section begins and ends:
(defun my/org-delete-subtree ()
(let* ((ctx (org-element-context))
(type (org-element-type ctx))
(beg (org-element-property :begin ctx))
(end (org-element-property :end ctx)))
(when (eq type 'headline)
(kill-region beg end))))
The function is supposed to be called with
point before the headline of the subtree, so it is suitable for use with
The API documentation describes the functions above (and much more), but you will have to familiarize yourself with the parse tree representation, if only to figure out what properties (e.g
:begin) to use. And you will have to be very careful: it can act as both a whittling knife of exquisite precision and a chainsaw of awesome power that can do a lot of damage.
Some historical comments: as @orgtre points out in a comment and in the other answer, there is a built-in function
org-cut-subtree which already implements this functionality (and more), so there is no need to write your own function as I did above.
org-cut-subtree function dates from the very beginning of Org mode (it was part of Org mode 3.14 which is before there was even a git repo I believe). The syntax specification of Org mode was almost non-existent at the time and the functions were pretty lenient on what they accepted as legal input: Carsten Dominik, the creator of Org mode, wanted a system in plain text to do what he needed (he is an astronomer and he needed a system to keep track of what he had to do, but also take notes, including equations, which is why LaTeX figures so large in Org mode) and he and others (particularly Bastien Guerry) grew it organically over the years.
Eventually, Nicolas Goaziou took over maintenance of the code and added a parser (named
org-element, introduced in 2012 with version 7.9.2 ), and defined a more formal (but still fairly informal) syntax, cleaned up corner cases, declared some things illegal (e.g. there was a time when
SCHEDULED: timestamps could be anywhere - now, they have to be right after the headline). A lot of this functionality was used in the complete overhaul of the export system that was released with Org mode 8.0 in 2013.
Ever since that time, new functions have been using
org-element facilities for parsing, rather than the ad-hoc parsing that
org-cut/copy-subtree use, but these functions worked, and still work, well enough that nobody has rewritten them to use the current parser.
A lot of these "historical" functions still live in the single biggest file that Org mode has (which, BTW, used to be the only file that Org mode had when it started),
org.el, which accounts for about 15% of the total number of lines (not LOC) in Org mode today.
All this is definitely a tangent, but I enjoyed writing it - I hope you enjoyed reading it!