From 0882a21997b0830f43643cac9f0de4beaa698988 Mon Sep 17 00:00:00 2001 From: Serghei Iakovlev Date: Sun, 29 Sep 2024 15:54:01 +0200 Subject: Rework author configuration --- exampleSite/content/documentation/index.md | 116 +++++++++++++++++++++++++++++ exampleSite/hugo.toml | 1 + layouts/_default/home.humanstxt.txt | 38 ++++++++-- layouts/_default/list.atom.xml | 22 +++++- layouts/_default/list.jsonfeed.json | 19 ++++- layouts/_default/single.html | 6 +- layouts/partials/author.html | 14 ---- layouts/partials/head.html | 7 +- layouts/partials/head/author.html | 13 ++++ layouts/partials/post-meta/author.html | 3 - layouts/partials/schema.org/article.html | 19 ++++- layouts/partials/site-author.html | 35 --------- 12 files changed, 223 insertions(+), 70 deletions(-) delete mode 100644 layouts/partials/author.html create mode 100644 layouts/partials/head/author.html delete mode 100644 layouts/partials/post-meta/author.html delete mode 100644 layouts/partials/site-author.html diff --git a/exampleSite/content/documentation/index.md b/exampleSite/content/documentation/index.md index 0289b4e..e4d2928 100644 --- a/exampleSite/content/documentation/index.md +++ b/exampleSite/content/documentation/index.md @@ -202,6 +202,122 @@ The example from Raisin in the Sun shows us that we don't need much special mark --- +## Configuring Author Selection + +Ed offers flexible author management that adapts to both simple and +complex content needs. By leveraging Hugo’s templating capabilities and the +theme’s configuration structure, you can control how authors are displayed +without redundancy. This section explains how to set up author defaults, +customize individual posts, and maintain clean frontmatter for your content. + +### Author Display in Ed + +Ed uses the author’s name for displaying attribution on individual post +pages, right below the title. This ensures that readers can easily see who wrote +the article. Additionally, the author’s name is included in the HTML metadata of +each page, such as: + +```html + +``` + +If you prefer not to show the author on your posts, you can disable this feature +by adding the following setting to your configuration: + +```toml +[params] + showAuthor = false +``` + +Finally, the built-in RSS template, which used by the theme, as well as custom +feeds templates, will include the author metadata in the feed, if present. If +they are not set, Hugo will not include the author metadata in the feed. + +#### Setting a Global Default Author + +In many cases, a site has a primary author for the majority of posts. Instead of +specifying the author in every single page’s frontmatter, Ed allows you to +define a global default in your Hugo configuration. To set this up, add the +following snippet to your `hugo.toml` file: + +```toml +[params.author] + name = 'John Doe' + email = 'john@example.com' +``` + +This snippet registers `John Doe` as the default author for any post that doesn’t +explicitly specify an author. Now, when your content files omit the author +parameter, Ed will automatically use this global setting. + +#### Overriding the Author per Page + +For cases where an individual post has a different author or multiple contributors, +simply include the `author` parameter in the frontmatter of that page. Ed +supports both single-author and multi-author configurations: + +- **Single Author:** If a post has one unique author, specify it as a string: + ```markdown + --- + title: Exploring Hugo + date: 2024-09-19T14:08:00+02:00 + author: Jane Smith + --- + ``` +- **Multiple Authors:** For posts with more than one author, use a list of strings: + ```markdown + --- + title: Exploring Hugo + date: 2024-09-19T14:08:00+02:00 + author: + - Jane Doe + - John Smith + --- + ``` + +Ed will format and display these authors appropriately, using commas to +separate the names. + +#### Template Logic and Author Handling + +The logic behind this setup is handled in a partial template, ensuring that the +theme intelligently selects the correct author value. The template performs the +following checks: + +1. **Checks for a Page-Specific Author:** If the frontmatter includes the author + parameter, it takes precedence. The theme distinguishes between a single string + and a list of strings, applying appropriate formatting. +2. **Falls Back to Global Default:** If no author is defined at the page level, + the template falls back to the global value defined in `[params.author]` in + your configuration file. + +This ensures consistent and clean display of author names throughout the site. + +#### Practical Usage Scenarios + +1. **Single Author Blogs:** If your site primarily has one author, define the + global default in `hugo.toml` and skip specifying the author in individual + posts. This reduces redundancy and simplifies the frontmatter structure. +2. **Multi-Author or Guest Posts:** For collaborative projects, specify multiple + authors directly in the frontmatter. The theme will handle the formatting + automatically. +3. **Guest Posts with Defaults:** You can use the global setting for regular + posts and specify authors explicitly only for guest contributions, maintaining + clarity and reducing manual repetition. + +#### Important Considerations + +- **Default Fallback:** When both the frontmatter and `params.author.name` are + empty, Ed will return an empty string, leading to no author being + displayed. Always ensure that either the frontmatter or the global + configuration is populated. +- **Email and Other Metadata:** While `params.author.email` can be set globally, + the current template logic does not expose email addresses by default. + If you wish to include email metadata in your posts, additional adjustments + would be required. + +--- + ## Footnotes Footnotes are the bread and butter of scholarship. Hugo makes footnotes a fairly simple affair: diff --git a/exampleSite/hugo.toml b/exampleSite/hugo.toml index db3e18d..0932c4a 100644 --- a/exampleSite/hugo.toml +++ b/exampleSite/hugo.toml @@ -85,6 +85,7 @@ refLinksErrorLevel = 'WARNING' # The site.Title will be used if empty. publisher = 'Serghei Iakovlev' + showAuthor = true [params.author] name = 'Serghei Iakovlev' email = 'contact@serghei.pl' diff --git a/layouts/_default/home.humanstxt.txt b/layouts/_default/home.humanstxt.txt index 23286fe..98b1c79 100644 --- a/layouts/_default/home.humanstxt.txt +++ b/layouts/_default/home.humanstxt.txt @@ -1,12 +1,38 @@ -{{- $siteAuthor := partial "site-author.html" . -}} -{{- with $siteAuthor.name }} +{{- $authorName := "" }} +{{- $authorEmail := "" }} +{{- $authorGithub := "" }} +{{- $authorTwitter := "" }} +{{- $authorLocation := "" }} +{{- with site.Params.author }} + {{- if reflect.IsMap . }} + {{- with .email }} + {{- $authorEmail = . }} + {{- end -}} + {{- with .name }} + {{- $authorName = . }} + {{- end }} + {{- with .github }} + {{- $authorGithub = . }} + {{- end }} + {{- with .twitter }} + {{- $authorTwitter = . }} + {{- end }} + {{- with .location }} + {{- $authorLocation = . }} + {{- end }} + {{- else }} + {{- $authorName = . }} + {{- end }} +{{- end }} + +{{- with $authorName }} /* TEAM */ Author: {{ . }} -{{- with $siteAuthor.email }}{{ printf "\n Contact: %s" . }}{{ end }} -{{- with $siteAuthor.github }}{{ printf "\n GitHub: @%s" . }}{{ end }} -{{- with $siteAuthor.twitter }}{{ printf "\n Twitter: @%s" . }}{{ end }} -{{- with $siteAuthor.location }}{{ printf "\n From: %s" . }}{{ end }} +{{- with $authorEmail }}{{ printf "\n Contact: %s" . }}{{ end }} +{{- with $authorGithub }}{{ printf "\n GitHub: @%s" . }}{{ end }} +{{- with $authorTwitter }}{{ printf "\n Twitter: @%s" . }}{{ end }} +{{- with $authorLocation }}{{ printf "\n From: %s" . }}{{ end }} {{- end }} /* SITE */ diff --git a/layouts/_default/list.atom.xml b/layouts/_default/list.atom.xml index 6ef45ab..c51bebd 100644 --- a/layouts/_default/list.atom.xml +++ b/layouts/_default/list.atom.xml @@ -15,7 +15,21 @@ {{- $pages = $pages | first $limit -}} {{- $siteLastMod := partial "site-last-mod.html" . -}} -{{- $siteAuthor := partial "site-author.html" . -}} + +{{- $authorEmail := "" }} +{{- $authorName := "" }} +{{- with site.Params.author }} + {{- if reflect.IsMap . }} + {{- with .email }} + {{- $authorEmail = . }} + {{- end -}} + {{- with .name }} + {{- $authorName = . }} + {{- end }} + {{- else }} + {{- $authorName = . }} + {{- end }} +{{- end }} {{- safeHTML "" }} @@ -29,10 +43,10 @@ {{- end -}} {{- end }} {{ $logo := resources.Get (site.Params.assets.logo | default "/img/open-graph-logo.png") }}{{ $logo = $logo.Resize "96x96" }}{{ $logo.Permalink | absURL }} - {{ $logo.Permalink | absURL }}{{ with $siteAuthor.name }} + {{ $logo.Permalink | absURL }}{{ if or (not (eq $authorEmail "")) (not (eq $authorName "")) }} - {{ . }} - {{ with $siteAuthor.email }}{{ . | html }}{{ end }} + {{ with $authorName }}{{ . }}{{ end }} + {{ with $authorEmail }}{{ . | html }}{{ end }} {{ end }}{{ with site.Params.Copyright }} {{ . | plainify }}{{ end }} Hugo{{ if ne $siteLastMod "" }} diff --git a/layouts/_default/list.jsonfeed.json b/layouts/_default/list.jsonfeed.json index 29c9bf4..d44c7e0 100644 --- a/layouts/_default/list.jsonfeed.json +++ b/layouts/_default/list.jsonfeed.json @@ -14,7 +14,20 @@ {{- $limit := site.Params.feedSize | default 25 -}} {{- $pages = $pages | first $limit -}} -{{- $siteAuthor := partial "site-author.html" . -}} +{{- $authorName := "" }} +{{- $authorTwitter := "" }} +{{- with site.Params.author }} + {{- if reflect.IsMap . }} + {{- with .name }} + {{- $authorName = . }} + {{- end -}} + {{- with .twitter }} + {{- $authorTwitter = . }} + {{- end }} + {{- else }} + {{- $authorName = . }} + {{- end }} +{{- end }} { "version": "https://jsonfeed.org/version/1.1", @@ -25,9 +38,9 @@ {{- $logo := resources.Get (site.Params.assets.logo | default "/img/open-graph-logo.png") }}{{ $logo = $logo.Resize "96x96" }} "icon": {{ $logo.Permalink | jsonify }}, "favicon": {{ $logo.Permalink | jsonify }}, - {{ with $siteAuthor.name }}"authors": [ + {{ with $authorName }}"authors": [ { - "name": {{ . | jsonify }}{{ with $siteAuthor.twitter }}, + "name": {{ . | jsonify }}{{ with $authorTwitter }}, "url": {{ (printf "https://twitter.com/%s" . ) | jsonify }}{{ end }} } ],{{ end }} diff --git a/layouts/_default/single.html b/layouts/_default/single.html index fe33269..a061e89 100644 --- a/layouts/_default/single.html +++ b/layouts/_default/single.html @@ -7,7 +7,11 @@

{{ if in (slice "drama" "narrative" "poem") $postType }} - {{ partial "post-meta/author.html" . }} + {{ $showAuthor := .Site.Params.showAuthor | default false }} + {{ $author := partial "head/author.html" . }} + {{ if (and $showAuthor (ne $author ""))}} + {{ i18n "by" . }} + {{ end }} {{ else }} {{ partial "post-meta/date.html" . }} {{ end }} diff --git a/layouts/partials/author.html b/layouts/partials/author.html deleted file mode 100644 index 4ca1209..0000000 --- a/layouts/partials/author.html +++ /dev/null @@ -1,14 +0,0 @@ -{{- $siteAuthor := partial "site-author.html" . -}} - -{{- /* First, check for current page author(s) */}} -{{- if .Params.author }} - {{- $author_type := (printf "%T" .Params.author) }} - {{- if (or (eq $author_type "[]string") (eq $author_type "[]interface {}")) }} - {{- (delimit .Params.author ", " ) }} - {{- else }} - {{- .Params.author }} - {{- end }} -{{- /* Otherwise, get site authors */}} -{{- else if $siteAuthor.name }} - {{- $siteAuthor.name }} -{{- end -}} diff --git a/layouts/partials/head.html b/layouts/partials/head.html index 94684a2..0a4b02a 100644 --- a/layouts/partials/head.html +++ b/layouts/partials/head.html @@ -8,7 +8,12 @@ - + {{ $showAuthor := .Site.Params.showAuthor | default false }} + {{- $author := partial "head/author.html" . }} + {{ if (and $showAuthor (ne $author ""))}} + + {{- end }} + {{ hugo.Generator }} {{ partial "styles.html" . }} diff --git a/layouts/partials/head/author.html b/layouts/partials/head/author.html new file mode 100644 index 0000000..94788e9 --- /dev/null +++ b/layouts/partials/head/author.html @@ -0,0 +1,13 @@ +{{- $author := "" -}} + +{{- with .Params.author -}} + {{- if (reflect.IsSlice .) -}} + {{- $author = delimit . ", " -}} + {{- else -}} + {{- $author = . -}} + {{- end -}} +{{- else -}} + {{- $author = site.Params.author.name -}} +{{- end -}} + +{{- return $author -}} diff --git a/layouts/partials/post-meta/author.html b/layouts/partials/post-meta/author.html deleted file mode 100644 index 1b56004..0000000 --- a/layouts/partials/post-meta/author.html +++ /dev/null @@ -1,3 +0,0 @@ -{{ with .Params.author }} - {{ i18n "by" . }} -{{ end }} diff --git a/layouts/partials/schema.org/article.html b/layouts/partials/schema.org/article.html index f4112b6..1549784 100644 --- a/layouts/partials/schema.org/article.html +++ b/layouts/partials/schema.org/article.html @@ -13,7 +13,20 @@ {{- $logo := resources.Get (site.Params.assets.logo | default "/img/open-graph-logo.png") -}} {{- $logo = $logo.Resize "96x96" }} -{{- $siteAuthor := partial "site-author.html" . }} +{{- $siteAuthorName := "" }} +{{- $siteAuthorTwitter := "" }} +{{- with site.Params.author }} + {{- if reflect.IsMap . }} + {{- with .name }} + {{- $siteAuthorName = . }} + {{- end -}} + {{- with .twitter }} + {{- $siteAuthorTwitter = . }} + {{- end }} + {{- else }} + {{- $siteAuthorName = . }} + {{- end }} +{{- end }}