Skip to content
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

Get docs up-to-date for bundles and resources for Hugo 0.35 #308

Closed
bep opened this Issue Jan 24, 2018 · 70 comments

Comments

Projects
None yet
4 participants
@bep
Copy link
Member

bep commented Jan 24, 2018

A dugnad of sort.

We can use the next branch:

@regisphilibert
@kaushalmodi

I suggest a simple coordinated approach with focus on getting things done ...

@bep bep added the Enhancement label Jan 24, 2018

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 24, 2018

I suggest a simple coordinated approach with focus on getting things done ...

As in: "I can do this and then you can do that ..."

And I much prefer short and precise documentation which is both easier to understand than the chatty variant. So don't hesitate to trim down on unneeded wording.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 24, 2018

@kaushalmodi we could split the work.

And I much prefer short and precise documentation which is both easier to understand than the chatty variant. So don't hesitate to trim down on unneeded wording.

Don't worry I know this is not a blog post ;)

That being said, I'm working on updating the article with the new additions and I have a structure that I think work.

I propose starting by the page bundle architecture (no cupcake involved)

Then the available "properties" or info, not sure about the wording here

  • .Name
  • .Title
  • .Permlink
  • .RelPermalink
  • .AbsSourceFilename (not sure about mentioning this one)

Of course we'll have to emphasize the importance of the .Name property regarding to Match/ByMatch and its potential overriding by metadata.

Then the methods

  • ByMatch (introducing glob)
  • GetMatch
  • ByType

Then we can have another big part on the metadata which are a big part of the feature and needs precise explaination (src param, order overwriting etc...

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 24, 2018

.AbsSourceFilename (not sure about mentioning this one)

I would leave it out; it is kind of an internal property.

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 24, 2018

ByMatch (introducing glob)
GetMatch
ByType

The name is just ... Match.

Also, I think image processing needs some attention.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 24, 2018

How about making this whole Bundle documentation.. a Bundle?

Here's a broad-level content organization that I was thinking:

  • Bundle
    • Page bundle (index.md)
      • Headless page bundles
    • Section (or Branch?) bundle (_index.md)
    • Resources
      • resources Params
      • Methods? Properties? (@bep What would be the Go-correct term for those?)
        • .Name, .Title, ..
      • Resource filtering methods
        • .Match, .GetMatch, ..
    • Image Processing

Documentation implementation detail:

  • The whole Bundle documentation would be actually a Bundle i.e. content/../bundle/index.md
  • Page Bundle would be content/../bundle/page-bundle, Section Bundle would be content/../bundle/section-bundle (@bep or Branch Bundle?), and so on.

@regisphilibert

Then the available "properties" or info, not sure about the wording here

  • .Name
  • .Title

I think it would be useful to add .ResourceType to that list.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 24, 2018

I think it would be useful to add .ResourceType to that list.

Of couse, but we should mention that it's only the "main type" ?

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 24, 2018

How about making this whole Bundle section.. a Bundle?
Are you talking about sections or page bundle?

md file inside a bundle cannot have a standalone page, I had studied this use case.

We would need a special template for it? One that is able to loop through bundled md (called sections) and display their content in the template.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 24, 2018

md file inside a bundle cannot have a standalone page, I had studied this use case.

Correct. But that should be fine..

We would need a special template for it?

We can have a generic single layout for bundles that loops though all Resources pages, and set the layout front-matter in that bundle index front-matter. Turns out.. I was just working on that example.

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 24, 2018

I suggest you make it a section ("Page Bundles"?), which is a bundle that can contain ... bundles. But don't make it too complex; the text is important.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 24, 2018

I suggest you make it a section

OK, how about something like this:

bundles/
├── image-processing
│   └── index.md
├── _index.md
├── page-bundle
│   └── index.md
├── resources
│   └── index.md
└── section-bundle
    └── index.md

I'd suggest calling the section just Bundles as in that, we will further distinguish between Page and Section bundles. WDYT?

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 24, 2018

... but it would also be nice if "bundles and resources" wasn't separated away as "another thing". A bundle is a Page and a bundle can have many Resources.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 24, 2018

The idea was to briefly explain page vs section bundles in their own pages.. index vs _index. Those will be short descriptions.

I kept resources separate as they would apply to both page and section bundles...and the same thing for image processing.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 24, 2018

The bundles/_index.md can have a summary content that ties all those concepts together, with links to the individual page-bundle, section-bundle, resources, .. pages.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 24, 2018

@kaushalmodi I am a bit lost in you suggestion, but I trust you.

Should we start a branch and both work on it?

Would you care to start adding the bundle/section to this branch and write which should be the first part of the doc : Bundle/File structure...

Then I could write the property/methods section

Then we would treat metadata and Image processing (in this order)

@bep the image processing: Will it, at some point, be useable outside of page resources? Is it already ? And if so, shouldn't it have its own page in the doc.

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 24, 2018

Should we start a branch and both work on it?

Use the next branch.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 24, 2018

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 24, 2018

Only one minor thing.. not sure why https://next--gohugoio.netlify.com/content-management/ is now not showing everything under content-management:

image

Compare that with https://gohugo.io/content-management/.

That said, I think this problem can be solved in parallel, and shouldn't block the Bundles documentation effort.


Update

@bep

It's

{{ $section_to_display :=  .Sections | default .Paginator.Pages }}

in hugoDocs/themes/gohugoioTheme/layouts/_default/list.html.

With the Bundles branch added, .Sections is now non-nil.. earlier that was nil. So now only the Bundles branch gets added to $section_to_display. What's a good way to get a union of .Sections + .Paginator.Pages?

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 24, 2018

ok I'm gonna start the "resources" part with methods, properties and metadata

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 24, 2018

ok I'm gonna start the "resources" part with methods, properties and metadata

Cool, I'll take up the "page bundles" and "section bundles" parts.

Might rename "Section Bundles" to "Section/Branch Bundles".

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 24, 2018

Anything of note as the difference between Name and Title other than the fact that Name is used by Match and GetMatch?
They're both by default the filename right? Or am I missing something?

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 24, 2018

I don't want to derail the discussion but I can't figure out why Match never seems to catch .md files... Any idea ? I want to document this proper ;)

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 24, 2018

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 25, 2018

@kaushalmodi moving on to Image processing, I'm not as knowledgeable in the matter so may need your help once first draft is out. Cheers.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 25, 2018

@regisphilibert I am not knowledgeable in that area either, but am willing to help however I can. I need to yet be done with page/section bundle pages.. I see a lot of folks need to understand that concept.. saw few questions regarding that on discourse today itself.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 25, 2018

// Resize to a width of 600px and preserve ratio
{{ $image := $resource.Resize "600x" }} 

// Resize to a height of 400px and preserve ratio
{{ $image := $resource.Resize "x400" }} 

Just have to say I love this simple syntax where moving the x around just does what's expected. That's the kind of innovative human syntax that makes me love this framework a bit more everyday!
That may be some kind of well known syntax elsewhere, but not where I come from... :)

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 25, 2018

Alright, Image Processing is on next.
Most of it is taken from @bep's .32 intro from https://gohugo.io/about/new-in-032/
I edited reworded for better flow and expended explanation when thought useful.
Cheers

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 25, 2018

That may be some kind of well known syntax elsewhere, but not where I come from... :)

It's an obvious syntax, but I don't think it's very common. Some people complained and suggested something in the line of "300h 200w" which is very hard on my eyes.

But having done my share of "legacy renaming" in a widely used software (Hugo) has made me think twice before releasing new API. Just a simple change from RSSlink to RSSLink cost a lot in support questions, even if we deprecated the old one in a controlled manner.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 25, 2018

It's perfect this way.

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 25, 2018

The sunrise metadata example (with the merge logic in src) looks a little contrived and does not show this feature's potential.

I think a more practical variant of @kaushalmodi 's example in my commit here would be better:

gohugoio/hugo@5a0819b

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 25, 2018

Mmm... now I'm confused about the order of metadata rules. This is @bep exemple from his commit:

[[resources]]
src = "documents/photo_specs.pdf"
title = "Photo Specifications"
[resources.params]
ref = 90564687
icon = "photo"
[[resources]]
src = "documents/guide.pdf"
title = "Instruction Guide"
[resources.params]
ref = 90564568
[[resources]]
src = "documents/checklist.pdf"
title = "Document Checklist"
[resources.params]
ref = 90564572
[[resources]]
src = "documents/payment.docx"
title = "Proof of Payment"
[[resources]]
src = "documents/*.pdf"
title = "PDF file"
[resources.params]
icon = "pdf"
[[resources]]
src = "documents/*.docx"
title = "Word document"
[resources.params]
icon = "word"

The specific rule is first and yet is not overridden by the more generic rule following? Is it the correct behaviour?

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 25, 2018

I updated the page accordingly. Ignore my previous comment, I re-read you commit message.
I added an image in there to emphasize the Match rule on the name metadata.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 25, 2018

Hmm, how about

  • Bundle Page Bundle
    • Page Bundle Leaf Bundle
    • Section Bundle Branch Bundle

[Reference]

A taxonomy list is a "bundle", but it's not a section

I didn't know of that thing.. what are taxonomy lists? Any relation with Page Bundles?

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 25, 2018

I keep thinking that the previous sunset exemple was more concise and readable. Disagree and commit ;)

@budparr

This comment has been minimized.

Copy link
Contributor

budparr commented Jan 25, 2018

Looks like you folks are demoing the page bundles with your docs on them. I personally think it's better to keep the docs consistent for future contributors and have demos elsewhere. At any rate, when I click around the next branch, and from this comment it looks like there might be some unintended consequences in the menu system, which was created back when bundles were merely a twinkle in BEP's eye.

cc @rdwatters

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 26, 2018

I tend to agree with @budparr here. Maybe revisit the doc as bundles later on.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 26, 2018

Considering consistency, it makes sense to have the inner leaf bundles as regular pages instead, so that future contributors are not confused by the index.md files (hope they are not confused anyways). And also, those leaf bundles don't have to exist right now as there are no nested content pages or images.

But I would like to retain the other branch bundle. That bundle helps organize all the Page Bundle related documentation together.

Regarding the menu layout issue, it should be now fixed after my last commit. Even if that raises issues at other places in the site, it should be fixable. Eventually, we shouldn't prevent using these features because the layout needs to be tweaked a bit (or fixed within Hugo) to accommodate them.

If we try to stick with the old layout, it would be unwieldy to have all those pages flat in the content-management Section.

So, in summary, let's try to keep at least that outer Branch Bundle organization for the Page Bundles part.

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 26, 2018

The "bundles as a new section" was not such a great idea. It

  1. Tries to establish bundles as "something special", which it isn't. Or, it should not be. It's just another way to organize your content.
  2. It tries to create some new terms that does not exist, which I think will just confuse people
  3. It does not work with the current menu system.

What I suggest is this:

  • @regisphilibert if you could finish (that is an open term) the content of the Resources and Image Processing content page.
  • Move those pages to the parent section content-management.

When that is done, I will try to write something that ties it all together in "Content Organization", which needs a trimming and overhaul anyway.

Sounds like a plan?

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 26, 2018

Sounds like a plan?

OK. I have few comments.

It's just another way to organize your content.

If bundles is just a way to organize contents, why is it making the menu system complicated? Is here some fix needed in Hugo so that this can work in future (of course, this is an issue to tackle after the upcoming release).

It tries to create some new terms that does not exist

Wouldn't we need the new terms anyways? It will help better communicate with users. Something like "Look at Branch bundles section in the documentation" (because they used index.md instead of _index.md).

I'll refactor the bundles documentation, everything into a single page, with leaf/branch terms, and then you can refactor that further as needed.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 26, 2018

@bep yes I will finish those. For me it means finalizing the metadata exemple with you guys suggestions. Let me know if you think I left out anything else.

I’m still thinking the resources page belongs more in the template section than content management. Any thoughts on that?

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 26, 2018

I’m still thinking the resources page belongs more in the template section than content management.

As this bundle structure is going away, I agree. Earlier it made sense as all the "page bundle" related stuff was in the same section.

Now I also think that Resources would better fit in the template section.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 26, 2018

Now I also think that Resources would better fit in the template section.

Yes but my afterthought is the "Medatadata" part does belong in content management and I don't want to take it away from the resources page as both needs to be discussed alongside I think. Let's focus on finishing this for Monday. We can update later.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 26, 2018

So: b929596
and...
9978743

I updated the metadata example and renamed Resources to Page Resources.
Now that this is out of the Bundles section, I think it makes more sense.

When that is done, I will try to write something that ties it all together in "Content Organization", which needs a trimming and overhaul anyway.

Awesome

Today and this week-end won't give me as much time as this past week, but I will try to get an hour or two in the week end to follow up and help.

I appreciate being given the opportunity to help the Hugo community.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 26, 2018

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 26, 2018

@regisphilibert I have made few edits to your Page Resources page. Can you review them: kaushalmodi@e96c933

In the process of ensuring the changes I made about the "order matters" part, I could have found an issue with using :counter.. it does not increment! @bep If you confirm this is a bug, I can open an issue on the hugo core repo.

Test cases:

TOML

YAML

Note above, that even though I have name : "pdf-file-:counter" for src : "**.pdf", the name for all PDF files stays stuck at pdf-file-1.. the counter does not increment.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 26, 2018

OK.. as I experiment more, a weird pattern emerges..

  • title = "pdf-file-:counter" --- Titles get set as expected: pdf-file-1, pdf-file-2, ..
  • name = "pdf-file-:counter" 🚫 --- All names are set as pdf-file-1
  • foo = "foo-:counter" (in params) 🚫 --- All foo get set as foo-:counter verbatim.. so no :counter replacement.

Shouldn't :counter way the same way as in title no matter in which param it is used.


Update

Figured out a minimal case to reproduce this issue.

Works

Here I have only:

[[resources]]
  src = "**.pdf"
  name = "pdf-file-:counter"

Counter in name increments fine.

Does not work

Here I have:

[[resources]]
  src = "documents/photo_specs.pdf"
  title = "Photo Specifications"
[[resources]]
  src = "**.pdf"
  name = "pdf-file-:counter"

The difference from the "Works" case is that, here I first set the title for "documents/photo_specs.pdf". As that might also be implicitly setting the Name, the later name = "pdf-file-:counter" rule does not work only for that file.

The behavior is strange though.. it could be understood if the name rule had no effect on the Name of "documents/photo_specs.pdf".. assuming that that was set implicitly in the first rule. The problem is that the Name does get almost set as per the name rule but the count is always stuck at 1.

In summary, if a resource is fetched by an src filter earlier, the :counter messes up if set in a later rule.

Other

One thing is for sure.. :counter works only in title and name, but not in params.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 26, 2018

@kaushalmodi thanks as a non native speakers your proof reading and wording adjustments are of great help.

That being said, I think :counter is pretty self explanatory and your approach burdens this bullet whose purpose is just illustrate a metadata rule/src default setting on pdf files.

Maybe isolate :counter explanation in a notice afterward ?

Again, thanks for your corrections.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 26, 2018

is pretty self explanatory

I also assumed that, until #308 (comment) happened :)

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 26, 2018

I also assumed that, until #308 (comment) happened :)

Let's wait on @bep's input on that before altering the doc on it.

@regisphilibert

This comment has been minimized.

Copy link
Contributor

regisphilibert commented Jan 26, 2018

Beside if we’re not confident about :counter current behavior all the more reason to leave out of the doc for now.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 27, 2018

@regisphilibert

@bep fixed the :counter issue (gohugoio/hugo#4335) today. I'll go ahead and merge my branch on the next by tomorrow, while moving the :counter description to a separate paragraph.

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 27, 2018

@regisphilibert

thanks as a non native speakers your proof reading and wording adjustments are of great help.

I couldn't have done that write-up better! I simply took care of my OCD, putting commas and dots :)

@kaushalmodi

This comment has been minimized.

Copy link
Member

kaushalmodi commented Jan 29, 2018

merge my branch on the next by tomorrow

Done!

@bep I hit another snag while testing with a test case while coming up with the :counter documentation.. details here.

@bep

This comment has been minimized.

Copy link
Member Author

bep commented Jan 29, 2018

@kaushalmodi you need to not notify me about the same issue in duplicate copies/threads.

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

Add rough draft for page and section bundles
- Also a table showing the main differences between page and section bundles on
  in Bundles section content.
- Minor update of description in front-matter.
- Update default `list.html` layout as a quick-fix for the issue explained in
  #308 (comment)

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

Add rough draft for page and section bundles
- Also a table showing the main differences between page and section bundles on
  in Bundles section content.
- Minor update of description in front-matter.
- Update default `list.html` layout as a quick-fix for the issue explained in
  #308 (comment)

bep added a commit to gohugoio/gohugoioTheme that referenced this issue Feb 8, 2018

Add rough draft for page and section bundles
- Also a table showing the main differences between page and section bundles on
  in Bundles section content.
- Minor update of description in front-matter.
- Update default `list.html` layout as a quick-fix for the issue explained in
  gohugoio/hugoDocs#308 (comment)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.