New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add front matter metadata for Resources #4244

Closed
bep opened this Issue Jan 9, 2018 · 32 comments

Comments

Projects
None yet
5 participants
@bep
Member

bep commented Jan 9, 2018

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"

@bep bep added the Enhancement label Jan 9, 2018

@bep bep added this to the v0.33 milestone Jan 9, 2018

@bep bep self-assigned this Jan 9, 2018

@bep bep added the Proposal label Jan 9, 2018

@regisphilibert

This comment has been minimized.

regisphilibert commented Jan 10, 2018

Awesome. And then in your template/shortcodes ?

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

This comment has been minimized.

Member

bep commented Jan 10, 2018

Awesome. And then in your template/shortcodes ?

Yes.

@regisphilibert

This comment has been minimized.

regisphilibert commented Jan 10, 2018

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

This comment has been minimized.

Member

bep commented Jan 10, 2018

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

This comment has been minimized.

regisphilibert commented Jan 10, 2018

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

@bep

This comment has been minimized.

Member

bep commented Jan 10, 2018

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

This comment has been minimized.

Contributor

onedrawingperday commented Jan 10, 2018

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

This comment has been minimized.

Member

bep commented Jan 10, 2018

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

This comment has been minimized.

regisphilibert commented Jan 10, 2018

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

This comment has been minimized.

Contributor

onedrawingperday commented Jan 10, 2018

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

This comment has been minimized.

Member

bep commented Jan 11, 2018

@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

This comment has been minimized.

regisphilibert commented Jan 11, 2018

@bep what's the difference between

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

and

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

This comment has been minimized.

Member

bep commented Jan 11, 2018

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

This comment has been minimized.

regisphilibert commented Jan 11, 2018

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

This comment has been minimized.

Member

bep commented Jan 11, 2018

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

This comment has been minimized.

Contributor

onedrawingperday commented Jan 11, 2018

@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

This comment has been minimized.

carab commented Jan 12, 2018

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

This comment has been minimized.

Contributor

onedrawingperday commented Jan 12, 2018

@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

This comment has been minimized.

carab commented Jan 12, 2018

@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

This comment has been minimized.

Member

bep commented Jan 12, 2018

@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

This comment has been minimized.

Contributor

onedrawingperday commented Jan 12, 2018

@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

This comment has been minimized.

Member

bep commented Jan 12, 2018

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 added a commit to bep/hugo that referenced this issue Jan 15, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 15, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 16, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 16, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 16, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 16, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 16, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 16, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 17, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 17, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

bep added a commit to bep/hugo that referenced this issue Jan 17, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

@bep bep removed the Proposal label Jan 17, 2018

@bep

This comment has been minimized.

Member

bep commented Jan 17, 2018

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

@regisphilibert

This comment has been minimized.

regisphilibert commented Jan 17, 2018

Neat! And counterthing is awesome.

@carab

This comment has been minimized.

carab commented Jan 17, 2018

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

This comment has been minimized.

Member

bep commented Jan 17, 2018

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.

bep added a commit to bep/hugo that referenced this issue Jan 17, 2018

resource: Add front matter metadata to Resource
This commit expands the Resource interface with 3 new methods:

* Name
* Title
* Params

All of these can be set in the Page front matter. `Name` will get its default value from the base filename, and is the value used in the ByPrefix and GetByPrefix lookup methods.

Fixes gohugoio#4244

@bep bep closed this in #4280 Jan 17, 2018

@kaushalmodi

This comment has been minimized.

Member

kaushalmodi commented Jan 17, 2018

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

This comment has been minimized.

Member

bep commented Jan 17, 2018

@kaushalmodi why not just ... try.

@kaushalmodi

This comment has been minimized.

Member

kaushalmodi commented Jan 17, 2018

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

@bep

This comment has been minimized.

Member

bep commented Jan 17, 2018

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

This comment has been minimized.

Member

bep commented Jan 17, 2018

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

@bep

This comment has been minimized.

Member

bep commented Jan 17, 2018

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

bep added a commit that referenced this issue Jan 17, 2018

resource: Use path.Match instead of filepath.Match
They behave similar, but it is a path we're matching.

See #4244
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment