Hugo: Add front matter metadata for Resources

[bep]

Hugo 0.32 added Resources with image processing etc.

It uses naming conventions inside folders to bundle images, pages etc.

This works great.

A natural extension to this is to add some resource specific metadata to a page's front matter. Some motivations for this are:

• Add metadata to images etc. (title, description, photographer, license)
• Make it possible to link in project-relative resources:
  
  
  
  • Reuse images from a photo library, no duplication
  
  
  • Allow reuse of content files
  
  
  • Also makes it possible to bundle content files in home page etc.
  
  

I suggest this simple data structure:

[[resources]]
title = "My Cool Logo"
description = "Some other text"
 # page relative file reference
src = "mylogo.png"
# All fields will be put into a .Params map
license = "CC BY SA"

[[resources]]
 # Project relative file reference
# This will get the metadata from its own front matter, so no need to add more.
src = "/my-pages/mylogo.md"

[regisphilibert]

Awesome. And then in your template/shortcodes ?

{{ range .Resources }}
    {{ .Params.description }}
{{ end }}

[bep]

Awesome. And then in your template/shortcodes ?

Yes.

[regisphilibert]

Also by "page relative file reference", do you mean it is directory agnostic. (sorry for the lack of better word) and we just use the basename for "src"?

[bep]

Also by "page relative file reference", do you means it is directory agnostic.

There are two use cases for this:

1. Add metadata to a file in the bundle, so you need a way to link the file with metadata.
2. Add a file reference + metadata to a file outside of the page bundle (for example some media library)

So, given this project:

├── content
│   └── mybundle
│       ├── index.md
│       └── sunset.jpg
└── photos
    └── logo.png

To add metadata to the sunset: src = "sunset.jpg"and to the logo src = "/photos/logo.png".

This was the first idea I came up with and open to suggestions. But the missing leading slash marks it as a file inside the bundle.

[regisphilibert]

Gotcha! Makes sense.
So 2 pages can use a shared image but assign its own "metadata" to it.

[bep]

So 2 pages can use a shared image but assign its own "metadata" to it.

Yea, but the main motivation for the 2) is to avoid duplication + to be able to pull in content from "other places". It makes the bundle less portable, but may be worth it to some.

[onedrawingperday]

I like this syntax because it's simple and easily understood.

`[[resources]]`
`title = "My Cool Logo"`
`description = "Some other text"`
 `# page relative file reference`
`src = "mylogo.png"`
`# All fields will be put into a .Params map`
`license = "CC BY SA"`

But I also think that maybe we need some kind of front matter separator to group these parameters per .Resources image. So that it is possible to add meta data to several images in a Page Bundle.

Is grouping these parameters per image possible? Or is it out of scope for the time being?

[bep]

Is grouping these parameters per image possible? Or is it out of scope for the time being?

That is a good idea. I would imagine all/most photos would have the same photographer/license etc.

Hmm.

What if src can be a string or a slice:

[[resources]]
title = "My Cool Logo"
description = "Some other text"
 # page relative file reference
src = ["l1.png", "l2.png"]
# All fields will be put into a .Params map
license = "CC BY SA"

Maybe also some simple wildcard matching:

[[resources]]
title = "My Cool Logo"
description = "Some other text"
 # page relative file reference
src = "*.png"
# All fields will be put into a .Params map
license = "CC BY SA"

... maybe.

[regisphilibert]

Why not both?
If you endup with 50 pictures, the wildcard makes more sense.
If you only have a few though and only 2 or 3 of them share the same metadata, it may be easier for the content manager to use a slice.

Also I suppose this would work so sunset.png has both metada assigned?

[[ resources ]]
author = "Whoever"
src = "*.png"

[[resources]]
src = "sunset.png"
description = "nice sunset by the beach"

[onedrawingperday]

Of course parameters like photographer/licence etc will be the same. But the description could very well be different per image in a Page Bundle.

If we have something like this:
src = ["l1.png", "l2.png"]

Maybe there can be an easy way to couple it with something like this:
description = ["Description for l1.png", "Description for l2.png" ]

Also I like what @regisphilibert proposed above.

[[ resources ]]
author = "Whoever
src = "*.png"

[[resources]]
src = "sunset.png"
description = "nice sunset by the beach"

Whatever you think would be best to implement @bep

[bep]

@onedrawingperday we should try to avoid making this too hard to understand, but we should strive for "as little text as possible".

This would maybe work?

[[resourceGroups]]
license = "CC BY SA"
[[resources]]
title = "My Cool Logos"
description = "Some other text"
src = ["l1.png", "l2.png"]
[[resources]]
title = "My Other Cool Images"
description = "Some other text"
src = "*.png"

WIth a little flexibility in the parsing there the "group" is optional.

[regisphilibert]

@bep what's the difference between

[[resourceGroups]]
license = "CC BY SA"

and

[[resources]]
license = "CC BY SA"
src = "*"

[bep]

I'm thinking out loud here, which may not make sense. But a resourceGroup can have many resource definitions. Each resource can override params values on the group level if needed.

So:

[[resourceGroups]]
src = "*.png"
title = "My Image"
license = "CC BY SA"
[[resources]]
title = "My Cool Logo"
src = ["l1.png", "l2.png"]
[[resources]]
title = "My Other Image"
src = "l3.png"


[[resourceGroups]]
# Do the same for other resource types

In the above every PNG image in the bundle will get the title "My Image" and the CC license, but some will get a custom title.

[regisphilibert]

If it's all the same, as a user, I'd rather only have to remember about [[resources]] and the fact that its src parameter car either be a "slice" or a "string (allowing pattern-matching)"
This makes less documentation.

[bep]

If it's all the same,

It's not, but I agree about the documentation/understanding part. I will think about this. If it is easy to implement, maybe we can support both variants.

[onedrawingperday]

@bep I am fine with:

[[resourceGroups]]

It gives the flexibility that would be needed to add descriptions to multiple .Resources images in a Page Bundle.

And it's easy to understand, in my non-dev opinion.

[carab]

Hello,

I am not sure I understand the need for [[resourceGroups]], why can't we use only [[resources]] like below ?

[[resources]]
src = "*.png"
title = "My Image"
license = "CC BY SA"
[[resources]]
title = "My Cool Logo"
src = ["l1.png", "l2.png"]
[[resources]]
title = "My Other Image"
src = "l3.png"

[[resources]]
# Do the same for other resource types

Each resources declaration would be overriding previous declarations targeting the same file, in a cascading way, as in CSS with selectors.

Also, what do you think of using an implicit file for setting the frontmatter for a specific resource, like this for example :

├── content
│   └── mybundle
│       ├── index.md
│       └── sunset.jpg
│       └── sunset.md
│       └── sunrise.jpg
│       └── sunrise.md

sunset.md frontmatter would be automatically loaded for the sunset.jpg resource, and the content could then be used as a description which includes markdown.

[onedrawingperday]

@carab I am not a fan of your approach. I do not want to have img descriptions in several files. That will clutter Page Bundle folders.

Also overwriting [[ Resources ]] like you propose will make it impossible to have multiple descriptions for different imgs from within the index.md

EDIT
There are Context issues to consider in Go templates. I think it's needed to define a [[ resourceGroups ]] then overwrite portions of it. Also it is more readable IMO.

[carab]

@onedrawingperday I think if you only have a few images it's easier to keep it in one file, but if you have fifty it would be more practical to split them no ?

Also overwriting [[ Resources ]] like you propose will make it impossible to have multiple descriptions for different imgs from within the index.md

I'm not I was clear enough because I don't see how is that impossible ?

[[resources]]
title = "My Other Image"
src = "l3.png"

This will override every previous [[resources]] which targeted the l3.pngresource.

[bep]

@carab thanks for the input; I think you are right, your suggestion is better. A "metadata file per resource" may make sense, but that is out of scope of this particular issue.

[onedrawingperday]

@carab personally I prefer to keep image gallery meta descriptions in one file. But then again who am I to say no to the opposite, if you need it @bep should consider it.

Regarding the [[ Resources ]]syntax you propose again I don't know if it's possible to do it like this in Go.

But certainly using .Params.resources.title in templates looks much better than .Params.resourcesGroup.resources.title (if I am getting this right).

[bep]

Re. other files, I suspect that would consude people (and hurt performance); what we eventually will get and then we can think about this in a bigger picture is:

• External config.toml segments (for author bios etc.)
• Probably also external front matter, i.e. "index.toml", but having "mylogo.toml" is probably taking it one step too far.

@onedrawingperday the syntax above is TOML, which looks fine to me.

[bep]

See http://hugotest.bep.is/resourcemeta/ for two bundles with examples.

[regisphilibert]

Neat! And counterthing is awesome.

[carab]

This looks great !
So if I understand the order, each 'resources' definition adds to the previous ones ?
(edit: if they concern the same files)

[bep]

So if I understand the order, each 'resources' definition adds to the previous one

Yes, it is additive (if that is even a word), but there is no merge logic, which is why I said that the order matters: I.e. the first name, title or params wins.

Also, the counter is per glob pattern (more mapping info is needed to make it "more advanced"), but what I want to use it for is for image collections with a natural order with no sensible filename.

[kaushalmodi]

Just trying to understand the spec of this new resources front-matter.. does it mean that specifying the src is always mandatory.. or will its absence assume src to be *.*?

[bep]

@kaushalmodi why not just ... try.

[kaushalmodi]

I'll try eventually.. I just start with creating a spec as I want to support this in ox-hugo: https://github.com/kaushalmodi/ox-hugo/issues/115

[bep]

er.. does it mean that specifying the src is always mandatory..

You will get an error if you don't have a value for src.

[bep]

Also, the value for src must be valid according to https://golang.org/pkg/path/filepath/#Match

[bep]

But thinking about it, I should probably use the path variant. But the spec is just about the same.