Add support for <details> disclosure widget

doc/ox-hugo-manual.org

@@ -1553,6 +1553,111 @@ You can find many examples of table styling here:
 -----
 
 /Credit: [[https://css-tricks.com/complete-guide-table-element/][Guide to styling tables in HTML5-friendly manner]]/ --- /css-tricks.com/
+*** Details and summary
+:PROPERTIES:
+:EXPORT_FILE_NAME: details-and-summary
+:END:
+The "details" Org Special Blocks (~#+begin_details~ .. ~#+end_details~)
+are used for generating the Details disclosure elements [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details][~<details>~]]
+and ~<summary>~.
+
+/This is a *special* case of Org Special Blocks implemented only in
+~ox-hugo~./
+
+To separate the summary from the details:
+- Use the summary-divider string ~---~ at the *beginning of a new
+  line*.
+**** Regular details disclosure
+#+begin_src org
+#+begin_details
+Why is this in *green*?
+---
+You will learn that later below in [[#details-css][CSS]] section.
+#+end_details
+#+end_src
+will render like below:
+#+begin_details
+Why is this in *green*?
+---
+You will learn that later below in [[#details-css][CSS]] section.
+#+end_details
+**** Details disclosure without details or without summary
+- If the ~details~ Special Block does not contain the summary divider
+ ~---~, it will be considered that the /summary/ part is not
+  provided.
+  #+begin_src org
+  #+begin_details
+  Here are the /details/.
+  #+end_details
+  #+end_src
+  will render like below:
+  #+begin_details
+  Here are the /details/.
+  #+end_details
+  #+begin_note
+  In the absence of summary, most browsers will use a default string
+  "Details" for the summary.
+  #+end_note
+- If the last line in a ~details~ Special Block is *only the summary
+  divider ~---~*, it will be considered that the /details/ part is not
+  provided.
+  #+begin_src org
+  #+begin_details
+  Some *Summary*
+  ---
+  #+end_details
+  #+end_src
+  will render like below:
+  #+begin_details
+  Some *Summary*
+  ---
+  #+end_details
+  #+begin_note
+  Even if the details part is absent, the collapsing triangle will
+  still be rendered. But nothing will show up when that triangle is
+  uncollapsed.. /as the details portion is not there/.
+  #+end_note
+**** Open by default disclosure widget
+The ~<details>~ disclosure widget is initially closed by default. But
+it can be made to show up opened by default by adding the ~open~
+attribute like this:
+#+begin_src org
+#+attr_html: open
+#+begin_details
+Some *Summary*
+---
+Here are the /details/.
+#+end_details
+#+end_src
+will render like below:
+#+attr_html: open
+#+begin_details
+Some *Summary*
+---
+Here are the /details/.
+#+end_details
+**** CSS rules for these widgets
+:PROPERTIES:
+:CUSTOM_ID: details-css
+:END:
+- ~details summary~ will apply to the /summary/ portion of the
+  disclosure widget.
+- ~details .details~ will apply to the /details/ portion of the
+  disclosure widget.
+
+#+html: <style>.green { color: green; }</style>
+#+html: <style>.blue { color: blue; }</style>
+
+For instance, the CSS rules set using below caused all the disclosure
+/summaries/ to show in <span class="green">green</span>, and all the
+disclosure /details/ to show in <span class=blue>blue</span>.
+#+begin_src org
+#+html: <style>details summary { color: green; }</style>
+#+html: <style>details .details { color: blue; }</style>
+#+end_src
+
+#+html: <style>details summary { color: green; }</style>
+#+html: <style>details .details { color: blue; }</style>
 ** Enhancements
 :PROPERTIES:
 :EXPORT_HUGO_MENU: :menu "6.enhancements"

ox-hugo.el

@@ -2265,6 +2265,49 @@ INFO is a plist holding export options."
       ;; Overwrite the value of the `:description' key in `info'.
       (plist-put info :description contents)
       nil)
+     ((string= block-type "details")
+      ;; Recognize Org Special blocks like:
+      ;;   #+begin_details
+      ;;   summary. This will be wrapped in <summary> and </summary>
+      ;;   ---
+      ;;   details
+      ;;   #+end_details
+      (let* ((is-open (member "open" (org-element-property :attr_html special-block)))
+             (str1 (org-blackfriday-special-block special-block contents nil))
+             ;; Insert a new-line before the closing </details> tag
+             ;; for correct Markdown parsing for cases when the
+             ;; Special Block content ends a code block. Without this
+             ;; inserted newline, the Markdown converted content will
+             ;; look like below, and Blackfriday won't parse it
+             ;; correctly.
+             ;;   ```emacs-lisp
+             ;;   (message "a code block")
+             ;;   ```</details>
+             ;; A closing </p> tag is also added.. the opening <p>
+             ;; tag is later added in the `str2' var if summary is
+             ;; present, else in `str3' var.
+             (str1 (replace-regexp-in-string "</details>\\'" "\n</p>\\&" str1))
+             ;; Detect the summary divider special string "---".  It
+             ;; must begin at the beginning of a line.  Also ensure to
+             ;; replace only the first match, if any.
+             ;; Also add the opening <p> tag with "details" class
+             ;; so that just as CSS rules can be set for summary
+             ;; ("details summary"), they can be set for the details
+             ;; portion following the <summary> too, using "details
+             ;; .details".
+             (str2 (replace-regexp-in-string
+                    "^\\(---\\)\n\\(.\\|\n\\)*\\'"
+                    "</summary><p class=\"details\">"
+                    str1 nil nil 1))
+             (has-summary (not (string= str1 str2)))
+             str3)
+        ;; (message "[DBG details/summary]: is-open:%S `%s' `%s'" is-open str1 str2)
+        (setq str3 (if has-summary
+                       (replace-regexp-in-string "\\`<details>" "\\&<summary>" str2)
+                     (replace-regexp-in-string "\\`<details>" "\\&<p class=\"details\">" str2)))
+        (if is-open
+            (replace-regexp-in-string "\\`\\(<details\\)>" "\\1 open>" str3)
+          str3)))
      ;; https://emacs.stackexchange.com/a/28685/115
      ((cl-member block-type paired-shortcodes
                  ;; If `block-type' is "foo", check if any of the

test/site/content-org/all-posts.org

@@ -3433,16 +3433,17 @@ Line 3 had no =>= char.
 > ← See that this =>= on line 4 is retained even at the beginning of the line.
 Line 5 has this > charcter in-between and is retained.
 #+end_verse
-* Special Blocks                                              :special_block:
+* Org Special Blocks                                          :special_block:
+** Special Blocks
 :PROPERTIES:
 :EXPORT_FILE_NAME: special-blocks
 :END:
-** HTML5 Element Blocks
-*** Block without NAME, class or id
+*** HTML5 Element Blocks
+**** Block without NAME, class or id
 #+begin_article
 This is /an article/.
 #+end_article
-*** Block with NAME
+**** Block with NAME
 #+name: Aside-A
 #+begin_aside
 /Some/ *text* --- 1
@@ -3450,7 +3451,7 @@ This is /an article/.
 | a | b | c |
 | d | e | f |
 #+end_aside
-*** Block with class and id
+**** Block with class and id
 #+attr_html: :class my-section :id section-a
 #+begin_section
 /Some/ *text* --- 2
@@ -3458,18 +3459,18 @@ This is /an article/.
 | g | h | i |
 | j | k | l |
 #+end_section
-*** An inline HTML5 element
+**** An inline HTML5 element
 Unmarked.
 #+begin_mark
 /Some/ *marked* text --- 2.5.
 #+end_mark
 Unmarked again.
-** DIV-wrapped Blocks
-*** DIV without NAME, class or id
+*** DIV-wrapped Blocks
+**** DIV without NAME, class or id
 #+begin_something
 This is /some text/ wrapped in a =div= block with class =something=.
 #+end_something
-*** DIV with NAME
+**** DIV with NAME
 #+name: Foo-A
 #+begin_foo
 /Some/ *text* --- 3
@@ -3477,7 +3478,7 @@ This is /some text/ wrapped in a =div= block with class =something=.
 | m | n | o |
 | p | q | r |
 #+end_foo
-*** DIV with class and id
+**** DIV with class and id
 #+attr_html: :class my-bar :id bar-a
 #+begin_bar
 /Some/ *text* --- 4
@@ -3485,6 +3486,65 @@ This is /some text/ wrapped in a =div= block with class =something=.
 | s | t | u |
 | v | w | x |
 #+end_bar
+** Details and summary                           :details:summary:disclosure:
+:PROPERTIES:
+:EXPORT_FILE_NAME: details-and-summary
+:END:
+#+begin_description
+Details disclosure elements [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details][~<details>~]] and ~<summary>~.
+#+end_description
+
+These can be conveniently created using the Org Special Block
+~#+begin_details~ .. ~#+end_details~.
+
+To separate the summary from the details, use the summary-divider
+string ~---~ at the *beginning of a new line*.
+*** Closed details disclosure (default)
+**** Summary + Details
+#+begin_details
+Some *Summary*
+---
+#+include: "./all-posts.org::#details-disclosure-details" :only-contents t
+#+end_details
+**** No summary, only details
+In the situation where the summary divider is absent i.e. when user
+hasn't provided a summary, the browser will use a default summary
+string (usually "Details").
+#+begin_details
+#+include: "./all-posts.org::#details-disclosure-details" :only-contents t
+#+end_details
+**** Only summary, no details
+If the summary divider is the last string in this special block, it
+will mean that this ~<details>~ element has only the /summary/ and no
+/details/. In that case too, the browser will still render the
+collapsing triangle. But nothing will show up when you uncollapse
+it.. /as there no details/.
+#+begin_details
+Some *Summary*
+---
+#+end_details
+*** Open by default disclosure widget
+The details disclosures are closed by default, add ~#+attr_html: open~
+right below the details special block to have the disclosures open by
+default.
+**** Summary + Details (Open)
+#+attr_html: open
+#+begin_details
+Some *Summary*
+---
+#+include: "./all-posts.org::#details-disclosure-details" :only-contents t
+#+end_details
+**** No summary, only details (Open)
+#+attr_html: open
+#+begin_details
+#+include: "./all-posts.org::#details-disclosure-details" :only-contents t
+#+end_details
+**** Only summary, no details (Open)
+#+attr_html: open
+#+begin_details
+Some *Summary*
+---
+#+end_details
 * Shortcodes                                                      :shortcode:
 ** Alert CSS                                                       :noexport:
 *** Common CSS
@@ -5958,6 +6018,22 @@ If a post has the =DRAFT= state set, the =draft= front matter variable
 should be set to =true=, even if the post has a sub-heading
 immediately after the post heading.
 * Reusable sections                                        :noexport:ARCHIVE:
+** Details portion in <details> element
+:PROPERTIES:
+:CUSTOM_ID: details-disclosure-details
+:END:
+Here are some /details/.
+
+- list element 1
+- list element 2
+
+Here's a paragraph.
+
+And another paragraph.
+
+#+begin_src emacs-lisp
+(message "a code block")
+#+end_src
 ** Nested sections example
 :PROPERTIES:
 :CUSTOM_ID: nested-sections-example

test/site/content/posts/details-and-summary.md

@@ -0,0 +1,118 @@
++++
+title = "Details and summary"
+description = "Details disclosure elements [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and `<summary>`."
+tags = ["special-block", "details", "summary", "disclosure"]
+draft = false
++++
+
+These can be conveniently created using the Org Special Block
+`#+begin_details` .. `#+end_details`.
+
+To separate the summary from the details, use the summary-divider
+string `---` at the **beginning of a new line**.
+
+
+## Closed details disclosure (default) {#closed-details-disclosure--default}
+
+
+### Summary + Details {#summary-details}
+
+<details><summary>Some **Summary**
+</summary><p class="details">
+Here are some _details_.
+
+-   list element 1
+-   list element 2
+
+Here's a paragraph.
+
+And another paragraph.
+
+```emacs-lisp
+(message "a code block")
+```
+</p></details>
+
+
+### No summary, only details {#no-summary-only-details}
+
+In the situation where the summary divider is absent i.e. when user
+hasn't provided a summary, the browser will use a default summary
+string (usually "Details").
+
+<details><p class="details">Here are some _details_.
+
+-   list element 1
+-   list element 2
+
+Here's a paragraph.
+
+And another paragraph.
+
+```emacs-lisp
+(message "a code block")
+```
+</p></details>
+
+
+### Only summary, no details {#only-summary-no-details}
+
+If the summary divider is the last string in this special block, it
+will mean that this `<details>` element has only the _summary_ and no
+_details_. In that case too, the browser will still render the
+collapsing triangle. But nothing will show up when you uncollapse
+it.. _as there no details_.
+
+<details><summary>Some **Summary**
+</summary><p class="details">
+</p></details>
+
+
+## Open by default disclosure widget {#open-by-default-disclosure-widget}
+
+The details disclosures are closed by default, add `#+attr_html: open`
+right below the details special block to have the disclosures open by
+default.
+
+
+### Summary + Details (Open) {#summary-details--open}
+
+<details open><summary>Some **Summary**
+</summary><p class="details">
+Here are some _details_.
+
+-   list element 1
+-   list element 2
+
+Here's a paragraph.
+
+And another paragraph.
+
+```emacs-lisp
+(message "a code block")
+```
+</p></details>
+
+
+### No summary, only details (Open) {#no-summary-only-details--open}
+
+<details open><p class="details">Here are some _details_.
+
+-   list element 1
+-   list element 2
+
+Here's a paragraph.
+
+And another paragraph.
+
+```emacs-lisp
+(message "a code block")
+```
+</p></details>
+
+
+### Only summary, no details (Open) {#only-summary-no-details--open}
+
+<details open><summary>Some **Summary**
+</summary><p class="details">
+</p></details>