diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org index 61e1984..ac8a7a7 100644 --- a/doc/ox-hugo-manual.org +++ b/doc/ox-hugo-manual.org @@ -1685,39 +1685,96 @@ disclosure /details/ to show in blue. :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) }} -
- {{ if $author_is_slice }} - {{ index . 0 | safeHTML }} - {{ else }} - {{ . | safeHTML }} - {{ end }} -
-{{ 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" diff --git a/doc/themes/hugo-onyx-theme b/doc/themes/hugo-onyx-theme index db367ad..a7f66f9 160000 --- a/doc/themes/hugo-onyx-theme +++ b/doc/themes/hugo-onyx-theme @@ -1 +1 @@ -Subproject commit db367ad9b986a4cbd6c50d5aac284dc68ac48b18 +Subproject commit a7f66f92a8b3d33fe06008a82ef8f53fec882d9e diff --git a/test/site/content-org/all-posts.org b/test/site/content-org/all-posts.org index 8770a0c..00886a9 100644 --- a/test/site/content-org/all-posts.org +++ b/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 diff --git a/test/site/content/posts/single-author-custom.md b/test/site/content/posts/single-author-custom.md new file mode 100644 index 0000000..88f10bb --- /dev/null +++ b/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. diff --git a/test/site/themes/hugo-bare-min-theme b/test/site/themes/hugo-bare-min-theme index 8158b67..2384daf 160000 --- a/test/site/themes/hugo-bare-min-theme +++ b/test/site/themes/hugo-bare-min-theme @@ -1 +1 @@ -Subproject commit 8158b672dd0b1cdb7074f63a08cba5b1e06d5146 +Subproject commit 2384daf0a3f95a5514040b1b3f1a631fe6dcf480