HUGO

.Site.Author Usage?

There are a couple of previous posts on here from 2016 about this, and it doesn’t appear that the documentation has ever been updated. I found some (unpublished?) documentation inside the Github repo for Hugo by searching for “author” that shines some light on this, but it’s still not clear to me how this should be utilized.

Let’s assume I’m willing to create the scaffolding of per-author profiles, and I use the authors[] array in post front matter to reference these identifiers. I am not understanding where the per-author profiles get their layout templating from?

This is important to my purpose as I’m working on adapting an existing theme I’ve been using to support h-entry and h-card microformats. I originally approached this from the perspective of single-authorship sites where /about would be an h-card and the site config would provide a fallback if front matter wasn’t present in the post, but I think expanding this to support multi-authorship is worthwhile and Hugo seems to have some of the necessary pieces already in place. In order to fully implement this though, I need to ensure that the components of an author are marked up correctly when rendered.

Based on my dive in the source code, the best I can gather is that .Site.Author is a map which contains a set of identifiers which should match to TOML files in data/_authors. Each of the files should contain values which map to Author struct in page_author.go.

Is there any plan to publish complete documentation or how authorship is intended to work in Hugo? Preferably there would be a clean fallback so that single-authorship sites (like my own) don’t have to have the extra front matter and scaffolding, but that it’s possible to support multi-authorship in the same theme.

You would need to set a layout or type parameter in a content file, per author, since you wish to use different template for each one.

I am not aware of any special Hugo features regarding authorship.
I do vaguely remember some unresolved discussions from years ago, but perhaps others might know more.

EDIT
Also this topic might be of interest to you:

1 Like

Thanks for your reply. Yes, that thread shows several people are using a taxonomy for authors, which is a method I’m familiar with from my earlier searching. The main reason I don’t want to do this is that even in support multi-authorship, it should cleanly failback and support a primary author. Using taxonomies it requires the addition of authorship information in the front matter of every post, that’s the only way to get that. My goal with using .Site.Authors is to use information stored in the site config as a failback if nothing is specified in the front matter of a post, so that the post meta can “always” contain an authors object.

Just bumped into this thread while searching for " .Site.Author ".

I understand there is not support for Authors? Then what does this part of the docs refer to?

That’s pretty much what my question is, as well. There’s no documentation I can find that provides an example of what the configuration should look like.

Well, I’ve more or less figured out that the internal RSS template (for index.xml) uses the .Site.Author.name and .Site.Author.email variables. That’s all I’ve been able to find.

You need to add this to the config for RSS:

[author]
name = "Your Name"
email = "you@yourdomain.com"
1 Like

I wonder if @bep or @digitalcraftsman or @onedrawingperday could clarify the .Site.Author .Site.Authors thing.

In particular, in hugoBasicExample there is:

baseURL = "https://gohugo.io"
title = "Hugo Themes" 
author = "Steve Francia"
copyright = "Copyright © 2008–2019, Steve Francia and the Hugo Authors; all rights reserved."

paginate = 3
languageCode = "en"
   DefaultContentLanguage = "en"
enableInlineShortcodes = true
# prevent build failures when using Hugo's Instagram shortcode due to deprecated Instagram API.
# See https://github.com/gohugoio/hugo/issues/7228#issuecomment-714490456
ignoreErrors = ["error-remote-getjson"]

[menu]

Which based in the Hugo Docs Site Variable List says:

.Site.Author
a map of the authors as defined in the site configuration.

but other posts indicate that it is .Site.Authors and elsewhere that the correct configuration in the config.toml is:

 [author]
     name = "Joe Web Designer"
     email = "joe@example.com"

Is author = "Joe Author" in config.toml actually meant to do anything? Does it conflict with .Site.Author, and so on?

It’s all rather opaque what the actual intention is, and which answer doesn’t mean that at least some themes and/or sites are broken.

Help?

The only thing that has been implemented is .Site.Author (singular).

In config.toml, you can not do this:

author = "John Doe"

Instead, do this:

[author]
name = "John Doe"
location = "San Francisco"

The key names (name and location in the example above) are irrelevant. Create your own as needed. Then access these values from a template:

{{ .Site.Author.name }}
{{ .Site.Author.location }}

You can also define many authors in config.toml:

[author]
  [author.john_doe]
    name = "John Doe"
    location = "San Francisco"
  [author.jane_smith]
    name = "Jane Smith"
    location = "New York"

Then access these values from a template:

{{ .Site.Author.john_doe.name }}
{{ .Site.Author.john_doe.location }}
{{ .Site.Author.jane_smith.name }}
{{ .Site.Author.jane_smith.location }}

So then in content you could do something like:

+++
title = "Test"
date = 2021-03-17T07:15:35-07:00
draft = false
author = "john_doe"
+++

Then access the details from a template:

{{ index .Site.Author .Params.author "name" }}
{{ index .Site.Author .Params.author "location" }}
4 Likes

Well, not exactly. The default RSS template uses some hardcoded keys.

1 Like

Also for multiple authors users can define them in a project’s config like so:

[author]
authors = [
  {name = "Alex", location = "GR"},
  {name = "John", location = "US"}
]

Then call the authors’ list from the template like so:

{{ range site.Author.authors }}
<p>{{ .name }} in {{ .location }}</p>
{{ end }}

Furthermore conditional logic can be used to selectively render a specific author’s details from the project config in a content file that has been authored by them.

For example with a file that has the following parameter: author = "Alex"

One can enter the following in the single page template:

{{ range site.Author.authors }}
{{ if eq .name $.Params.author }}{{ .name }} in {{ .location }}{{ end }}
{{ end }}
2 Likes

@onedrawingperday @digitalcraftsman Given that

author = "Joe Designer"

is wrong, should I file a bug (or corrective PR) against the hugoBasicExample repo, as it currently uses exactly that (wrong) construct?

I think most people gave up on trying to get that to work, so have either [params] which duplicate the author field, or just don’t expect that the “author =” actually will do anything, although the copyright field does seem to be used (and work with .Site.Copyright).

Also, is this going to stay as the ‘expected behavior’ (@bep) so that it makes sense for me to do a PR on the Hugo Docs with the information gleaned here (since some of us do actually read the docs, but in this case there has been contradictory examples, and incomplete documentation)?

@jmooring @onedrawingperday Thank you for the clarity!

1 Like

The author parameter was entered in the hugoBasicExample config 7 years ago by the original Hugo creator.

It appears that sometime later, the author parameter was changed into a map.

I haven’t really paid attention to it, because I never needed to.

@cshoredaniel Yes, I think that you should send a PR at the hugoBasicExample repo, but first you need to create an associated issue with a link to this forum topic, so that your PR fixes the issue.

Also please note that I am no longer associated with the Hugo project on GitHub and I no longer maintain the Hugo Themes Showcase and its repositories.

I am simply a moderator of this forum (time permitting) and nothing more.

2 Likes

@onedrawingperday Thank you! I suspected parameter changed from original. And thank you for reminding me to create an issue before submitting a PR (and confirming a PR is appropriate).

‘Life happened’ and I’m a list rusty on ‘protocol’ for PR’s and such. Your work as a moderator is appreciated — I know what you mean about ‘time permitting’, although I have a little more of it now.

2 Likes

Thank you very much @jmooring and @onedrawingperday for the detailed response that answers my question. I know there are several other threads lacking this information I found in my search. If cshoredaniel doesn’t have time, I am happy to update the docs and examples myself if someone can point me in the right direction.

Now I can get cracking this weekend on updating the theme to implement authors appropriately for h-entries and h-feeds.

Really appreciated!

1 Like

Opened two related PRs:

1 Like

And I’ve got a PR for the hugoBasicExample

As noted in my Github comment .Site.Authors vs. Site.Author confused me. They were not created with the same intentions, so the PR I did is basically unrelated to the ones you have, but is related to this discussion.

1 Like

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.