diff --git a/NEWS.md b/NEWS.md
index 799e05f6b..62f1ab6df 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,10 @@
 # roxygen2 (development version)
 
+* Subheadings, i.e. headings of level 2 and above, are now allowed in
+  markdown text. They generate subsections within the roxygen tag
+  (within `@description`, `@details`, `@return`, etc.) `##` creates a
+  subsection, `###` a sub-subsection, etc. Headings can be nested (#907).
+
 * `\link{foo}` links in external inherited documentation are automatically
   transformed to `\link{package}{foo}` so that they work in the generated
   documented (#635).
diff --git a/R/markdown.R b/R/markdown.R
index db207ef01..83ec24192 100644
--- a/R/markdown.R
+++ b/R/markdown.R
@@ -174,10 +174,10 @@ escape_comment <- function(x) {
 }
 
 mdxml_heading <- function(xml, state) {
-  if (state$tag$tag != "@includeRmd") {
-    return(mdxml_unsupported(xml, state$tag, "markdown headings"))
-  }
   level <- xml_attr(xml, "level")
+  if (state$tag$tag != "@includeRmd" && level == 1) {
+    return(mdxml_unsupported(xml, state$tag, "level 1 markdown headings"))
+  }
   head <- paste0(
     mdxml_close_sections(state, level),
     "\n",
diff --git a/tests/testthat/test-markdown.R b/tests/testthat/test-markdown.R
index ec123223d..330a2af77 100644
--- a/tests/testthat/test-markdown.R
+++ b/tests/testthat/test-markdown.R
@@ -393,12 +393,92 @@ test_that("unhandled markdown generates warning", {
   text <- "
     #' Title
     #'
-    #' ## Heading
+    #' > block quotes do not work,
+    #' > sadly
     #'
     #' Blabla
     #' @md
     #' @name x
     NULL
   "
-  expect_warning(roc_proc_text(rd_roclet(), text), "markdown headings")
+  expect_warning(roc_proc_text(rd_roclet(), text), "block quotes")
+})
+
+test_that("level 1 heading in markdown generates warning", {
+  text <- "
+    #' Title
+    #'
+    #' # This is not good
+    #'
+    #' Blabla
+    #' @md
+    #' @name x
+    NULL
+  "
+  expect_warning(
+    roc_proc_text(rd_roclet(), text),
+    "level 1 markdown headings"
+  )
+})
+
+test_that("level >2 markdown headings work in @description", {
+  text <- "
+    #' Title
+    #'
+    #' @description
+    #' ## This is good
+    #' yes
+    #'
+    #' @details
+    #' Blabla
+    #' @md
+    #' @name x
+    NULL
+  "
+  out <- roc_proc_text(rd_roclet(), text)[[1]]
+  expect_equal_strings(
+    out$fields$description$values,
+    "\\subsection{This is good}{\n\nyes\n}"
+  )
+})
+
+test_that("level >2 markdown headings work in @details", {
+  text <- "
+    #' Title
+    #'
+    #' Description.
+    #'
+    #' @details
+    #' ## Heading 2
+    #' ### Heading 3
+    #' Text.
+    #' @md
+    #' @name x
+    NULL
+  "
+  out <- roc_proc_text(rd_roclet(), text)[[1]]
+  expect_equal_strings(
+    out$fields$details$values,
+    "\\subsection{Heading 2}{\n\\subsection{Heading 3}{\n\nText.\n}\n\n}"
+  )
+})
+
+test_that("level >2 markdown headings work in @return", {
+  text <- "
+    #' Title
+    #'
+    #' Description.
+    #'
+    #' @return Even this
+    #' ## Can have a subsection.
+    #' Yes.
+    #' @md
+    #' @name x
+    NULL
+  "
+  out <- roc_proc_text(rd_roclet(), text)[[1]]
+  expect_equal_strings(
+    out$fields$value$values,
+    "Even this\n\\subsection{Can have a subsection.}{\n\nYes.\n}"
+  )
 })