Make the Author documentation thorough

Ref: https://github.com/kaushalmodi/ox-hugo/issues/180,
https://github.com/kaushalmodi/ox-hugo/issues/178

doc/ox-hugo-manual.org

@@ -1685,39 +1685,96 @@ disclosure /details/ to show in <span class=blue>blue</span>.
 :PROPERTIES:
 :EXPORT_FILE_NAME: author
 :END:
-The =author= front-matter parameter is designed to always be a Slice
-(list), so that multiple authors can be supported.
-
-If you already have a blog, and if the =author= front-matter already
-exists, but set as a /String/, and not a /Slice of Strings/, you can
-use the following snippet:
-
-#+begin_src go-html-template
-{{ with .Params.author }}
-    {{ $author_type := (printf "%T" .) }}
-    {{ $author_is_slice := (eq "[]string" $author_type) }}
-    <div class="author">
-        {{ if $author_is_slice }}
-            {{ index . 0 | safeHTML }}
-        {{ else }}
-            {{ . | safeHTML }}
-        {{ end }}
-    </div>
-{{ end }}
+The ~author~ front-matter parameter is designed to always be a list or
+an array, so that multiple authors can be supported.
+**** Default Author
+The ~author~ parameter is set to always export by default (as the
+default value of ~org-export-with-author~ is ~t~).
+
+The author name defaults to ~user-full-name~. You can choose to either
+customize this variable in your Emacs config, or manually set the
+author name by adding the below to the top of your Org file:
+#+begin_src org
+,#+author: FirstName LastName
 #+end_src
 
-*What the above code does* ---
-
-If the =author= front-matter parameter exists:
-- If =author= is of /Slice/ type, insert its first element,
-- Else, insert it whole.
+If using /per-subtree/ flow, and if you want to specify the author (or
+override the value set by the above ~#+author~ keyword) differently
+for all posts under a subtree, add below in that subtree's property
+drawer:
+#+begin_src org
+:PROPERTIES:
+:EXPORT_AUTHOR: Firstname LastName
+:END:
+#+end_src
 
-An alternative would be to manually set the =author= param as a
-/String/ and not a /Slice/:
+Either of above two author-setting methods will export to this TOML
+front-matter:
+#+begin_src toml
+author = ["FirstName LastName"]
+#+end_src
+**** Multiple Authors
+Multiple authors can be specified by either:
+- Using multiple ~#+author~ keywords, or
+  #+begin_src org
+  ,#+author: FAuthor1 LAuthor1
+  ,#+author: FAuthor2 LAuthor2
+  #+end_src
+- Specifying comma-separated authors, if setting them in subtree
+  properties.
+  #+begin_src org
+  :PROPERTIES:
+  :EXPORT_AUTHOR: FAuthor1 LAuthor1, FAuthor2 LAuthor2
+  :END:
+  #+end_src
 
+Either of above two author-setting methods will export to this TOML
+front-matter:
+#+begin_src toml
+author = ["FAuthor1 LAuthor1", "FAuthor2 LAuthor2"]
+#+end_src
+**** Disabling exporting of ~author~ parameter
+Author exporting can be disabled using any of these ways:
+- To disable author exporting only for a specific Org file, add below
+  to the top of that file:
+  #+begin_src org
+  ,#+options: author:nil
+  #+end_src
+- If using /per-subtree/ flow, and if you want to disable author
+  exporting only for posts under specific subtrees, add below in the
+  property drawers of those:
+  #+begin_src org
+  :PROPERTIES:
+  :EXPORT_OPTIONS: author:nil
+  :END:
+  #+end_src
+- To disable author exporting by default for all exporters (not just
+ ~ox-hugo~), set ~org-export-with-author~ to ~nil~ in your Emacs
+  config.
+**** Tweaking your Hugo template to support /list/ ~author~
+#+begin_note
+The ~author~ front-matter parameter is *always* exported as a
+TOML/YAML list.
+#+end_note
+If you already have Hugo posts with the ~author~ front-matter already
+set, it is possible that those values exist as single string values
+instead of lists.
+
+If so, you can use a snippet like the [[https://github.com/kaushalmodi/hugo-onyx-theme/blob/master/layouts/partials/author.html][~author.html~ partial]] used by
+this doc site to parse the ~author~ parameter correctly (whether it's
+a plain string or a list of strings).
+***** Forcing ~author~ to be a /string/ (alternative)
+If you are not comfortable with Hugo templates, you can alternatively
+force the ~author~ param to be a plain /string/ instead of a /list/,
+by setting it as a /custom/ front-matter parameter:
 #+begin_src org
-#+hugo_custom_front_matter: :author "fname lname"
+#+author:
+#+hugo_custom_front_matter: :author "FirstName LastName"
 #+end_src
+
+- Note :: Remember to set the default author name to nil if doing this,
+          by setting the ~#+author~ keyword (or ~:EXPORT_AUTHOR:~
+          property) to /nothing/.
 ** Enhancements
 :PROPERTIES:
 :EXPORT_HUGO_MENU: :menu "6.enhancements"

doc/themes/hugo-onyx-theme

@@ -1 +1 @@
-Subproject commit db367ad9b986a4cbd6c50d5aac284dc68ac48b18
+Subproject commit a7f66f92a8b3d33fe06008a82ef8f53fec882d9e

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

@@ -5150,7 +5150,14 @@ auto-prefixed with the section for the current post.
 :EXPORT_FILE_NAME: single-author
 :EXPORT_AUTHOR: Foo Bar
 :END:
-This post has 1 author.
+This post has 1 author set as a TOML list in front-matter.
+*** Single author as a custom parameter                           :custom_fm:
+:PROPERTIES:
+:EXPORT_FILE_NAME: single-author-custom
+:EXPORT_AUTHOR:
+:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :author "Foo Bar"
+:END:
+This post has 1 author set as a TOML string in front-matter.
 *** Multiple authors
 :PROPERTIES:
 :EXPORT_FILE_NAME: multiple-authors

test/site/content/posts/single-author-custom.md

@@ -0,0 +1,8 @@
++++
+title = "Single author as a custom parameter"
+tags = ["front-matter", "author", "custom-fm"]
+draft = false
+author = "Foo Bar"
++++
+
+This post has 1 author set as a TOML string in front-matter.

test/site/themes/hugo-bare-min-theme

@@ -1 +1 @@
-Subproject commit 8158b672dd0b1cdb7074f63a08cba5b1e06d5146
+Subproject commit 2384daf0a3f95a5514040b1b3f1a631fe6dcf480