Standardize author data

[derekperkins]

Here's the first attempt at standardizing Hugo author details.

1. Data lives in /data/authors with one file per author. I thought about nesting it in /data/site/authors or /data/hugo/authors, but those seemed unnecessarily hidden.
2. Author front matter is an array to support multiple authors, though it will be up to themes to support multiple authors or not. There is a convenience .Author method to return a single author.
   if there are multiple authors and this is used, there is no guarantee which author will be returned
3. I changed .Site.Author from map[string]interface{} to Author, though I don't know if that is in use outside of the embedded RSS feed
4. Social data should only be the username
5. For Author social details, I added a .URL() convenience method that returns canonical urls for major social networks
6. I added a params section to the author, though as of right now it is map[string]string instead of map[string]interface{}
7. I use snake_case in the data files but templates will access them with PascalCase
8. Here's a sample author file

given_name      = "Derek"
family_name     = "Perkins"
display_name    = "Derek Perkins"
thumbnail       = "img link"
image           = "img link"
short_bio       = "super short bio"
bio             = "Here's Derek's awesome bio"
email           = "derek@email.com"

[social]
    facebook    = "derekperkins"
    github      = "derekperkins"
    twitter     = "derek_perkins"
    googleplus  = "DerekPerkins1"

[params]
   random       = "whatever you want"

[derekperkins]

• Decide how to implement author archives
• Add tests
• Add documentation
• Add a default user when creating a new hugo site
• Where it makes sense, alter themes.hugo.io to use it

[derekperkins]

@bep @spf13

[derekperkins]

I just changed the directory to _authors and now I delete the .Site.Data["_authors"] entry so the only way to access the author data is through .Site.Authors, .Page.Author or .Page.Authors

[rdwatters]

@derekperkins This is good stuff. The best part is the "params," which means it's extensible, which makes me happy. Here is an uber nitpicky suggestion, so take it however you'd like.

If conventions are the ultimate goal, how about naming parameters in a more => less abstracted style:

name_given:
name_family:
name_middle:
<!--Think it needs display name?-->
image:
image_thumb:
bio_short:
bio_long:
email:
[social]
[params]
<!--Rather than keeping social as a fixed key-value of the author content type, could this be included as part of "params" instead?-->

Does the _ in _authors signify a collection rather than a content directory? Also, w/r/t snake vs pascal, have there been any conversations as to casing conventions for all of Hugo? I ask because it seems to be a common point of vexation on the Discuss site.

Thanks for all the work on this. The Hugo community is freakin' awesome.

[spf13]

I think social should benefit from the same treatment as author as loads of
themes reference it and it would be great to have a standard. Social should
be both available for the site as well as using the same standard for the
author.

[derekperkins]

I think social should benefit from the same treatment as author

@spf13 Are you saying that you prefer using a fixed struct for social as opposed to a map[string]string?

[derekperkins]

@rdwatters

Think it needs display name?

Yes, I think it needs a display name similar to WordPress. Not every site wants to use real names. You do bring up a good point though. Maybe we should make a function for themes to use that does a few fallbacks, checking first for DisplayName and then falling back to Given + Family.

Does the _ in _authors signify a collection rather than a content directory?

I switched to an underscore because that's how _default works. Once I load up the actual author struct, I delete .Site.Data["_authors"] so it isn't accessible there anyways. I'm not super passionate about it, it just seemed to make sense.

Also, w/r/t snake vs pascal, have there been any conversations as to casing conventions for all of Hugo?

I personally prefer Pascal over snake casing. I thought I remembered seeing somewhere that data files only used lowercase, but I couldn't find a reference. I'm more than happy to switch to Pascal casing.

[derekperkins]

@rdwatters & @spf13 - For social, I could potentially do a transparent map. We have a struct for the most common networks, but make all of them accessible through a function. When reading the data in, I could store any unmatched networks in that map and return them as if they were natively supported. That allows for more extensibility while still retaining a definite standard.

[spf13]

@spf13 Are you saying that you prefer using a fixed struct for social as opposed to a map[string]string?

It doesn't need to be a struct necessarily, but I'd like to have some definition around what Social means and make it universal and standard. Part of this would be making sure that the keys are consistent across all places social is used.

To look at your example: You've gone ahead and provided usernames/tokens for each of these values while others may put full URLs in them. Templates/Themes would really struggle with rendering these in a standard way. I'm not sure what the right answer is, but whatever it is it needs to be consistent so that Themes can just be interchangeable.
Additionally you've written out the key "googleplus" where others may just have used "google".

Perhaps the ideal approach is to allow the definition to be loose but the parsing and internal access to be rigid.

This would mean that "google" and "googleplus" would both match the social network "google". The ingestion could examine the input and parse it out into separate url and token values for each social network.

I would think a struct like:

type socialNetwork struct {
    name         string
    aliases       []string
    token         string
        urlPattern  text.template
}

type socialEntry struct {
    network     socialNetwork
    token         string
}

Or something similar for each social network would be defined in the code. Then inside Site and Author you would have a map of [socialnames]SocialEntry.

Not sure if any of that made sense, but the idea is similar to how we handle params.

[derekperkins]

You've gone ahead and provided usernames/tokens for each of these values while others may put full URLs in them.

I'm currently parsing out usernames even if someone enters the full url or eliminating the @ if they use @username for just that reason and added the URL() function for theme authors.

This would mean that "google" and "googleplus" would both match the social network "google".

Do you feel strongly about that? I'd rather just tell people what to put in their config.

I can move forward with the structs you suggested. Having socialNetwork like you have here would make it trivial to extend the built in list of supported networks from a theme or config file if someone wanted to use a less common network.

[spf13]

I don't feel strongly about that at all. As long as the documentation is clear, I'm fine with declaring the keys to use.

[ryanwalls]

Any updates? I think this would be a nice addition.

[bep]

Not sure what the comments are meant to be here, but if you suggest some kind of "XML or JSON" naming here, you might as well add JSON tags here so it gets used when people do {{ author | jsonify }} That would be useful, come to think of it.

[dencold]

Is this going to be part of the 0.17 release? I don't see any activity here for over a month, so wanted to offer my help if there is anything else remaining (documentation?) for this to be part of the next release of hugo. I've been doing some similar work on my personal theme to add better support for Author metadata, so I'd really like this to be standardized for general users of Hugo.

Let me know how I can help! Great addition @derekperkins!

[derekperkins]

Ok, I just switched to camelCase and rebased on top of the current master.

@dencold / @ryanwalls: I don't have time to create documentation, so if you could flesh that out, I don't see any reason this shouldn't be merged for 0.17.

[digitalcraftsman]

Because this pull request is already open for a while I began to refactor the URL method as bep suggested and added a few tests. I could also add documentation for the current state of the pull request.

Temporary, I created a branch on my own fork for the additions.

Depending on the state of this pull request, I could create a temporary branch in this repo (like multilingual) in which this pr and my additins will be merged.

A few things are still undiscussed:

• the generation of an author archive was suggested. Are there any ideas to approach this? Maybe we should also have an eye on Add ability to generate per-{year, month, day} archives #448.
• add a default user when creating a new hugo site. Should we just prompt the user to fill out basic information like name, bio and email? Similar to:

$ hugo new site example.com
Do you want to create an author profile? [y/n] y
What is your first name?
John
What is your last name?
Doe
... 

[derekperkins]

I think URL should remain a switch. Different networks are going to have different ways to handle them, which a map can't handle. I don't think the switch is hard to read.

I think this PR should get merged as is, and we can discuss further implementation details like you've brought up in their own separate discussions.

[derekperkins]

@digitalcraftsman Thanks for working on tests.

I love the idea for prompting author creation on a new site.

[digitalcraftsman]

I think URL should remain a switch. Different networks are going to have different ways to handle them, which a map can't handle. I don't think the switch is hard to read.

Let the others decide. I don't mind both approaches.

Regarding the prompt: we should create an internal template for an author file. The user can either ignore the generation of an author (if it makes no sense) or he can fill out the minimum of information needed. In the last case we insert the given data into the template and save it as an author file.

Furthermore, I would like to introduce an hugo new author command that shows basically the same prompt. That users don't have to copy a author template from the docs.

[digitalcraftsman]

I added some documentation to my branch for this feature.

[dencold]

I wanted to chime in to say I really like the direction of this PR. Glad we are getting close to a standard for Author support in Hugo, going to help theme authors & downstream users a lot. I had a couple of thoughts here.

1. URL method: I agree with @bep and @digitalcraftsman. Using a map to resolve the canonical path seems much more idiomatic Go than the current switch approach. @derekperkins, could you elaborate on how you could see a social network somehow not fitting this approach? Maybe we're missing something here.
2. Author prompting: I love this idea. However, I would be more in favor of the hugo new author approach here. The hugo new site command does not currently have any prompting whatsoever, and I don't think we should introduce it now. If we do, we should get signoff from @spf13 since this is a changed behavior.

I'm happy to contribute documentation and anything else to get this feature greenlit for the next release. It's a nice step forward. Thanks again everyone!

[digitalcraftsman]

@dencold I agree that it's better to use only a completely seperate command for the profile creation instead of modifying hugo new site.

[derekperkins]

@bep Since I can't comment on #3088, are you proposing to scrap this PR?

[derekperkins]

@bep I'd like to comment on your author proposal in #3088, but I don't have permissions. Where would you like me to put my feedback?

[moorereason]

@derekperkins, I unlocked #3088.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[sirinath]

Can this be updated reviewed? But instead of data make it flexible to configure where data of authors is stored. It can be in data or taxonomy as many sites use taxonomies for multiple authors. This data can be made available through .Site.Author and .Page.Author.

[coolaj86]

2021 Update - Good News 🎉

There are no official docs, but someone has documented how Author and Authors work by looking into the source code - specifically, how index.xml is rendered.

See here:
discourse.gohugo.io/t/site-author-usage/31459/8

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.