Hugo: Improve _index.md vs draft

[macropin]

When using 0.58.0 and other recent releases, draft pages are always rendered, however the page content is blank. ie {{ .Content }} is not rendered. All pages are present in the menu.

We're using the learn theme. This issue is not present in 0.54.0.

[macropin]

Having read https://github.com/gohugoio/hugo/commit/6ccf50ea7bb291bcbe1d56a4d697a6fd57a9c629 it sounds like either draft _index.md are treated as a special case and always rendered without content, or the handling of drafts is still not fixed. This explains our issue. But does not explain why the regression exists. For now we'll stick with 0.54.0 until this is resolved as we make extensive use of the draft functionality.

[bep]

This explains our issue. But does not explain why the regression exists.

The old behaviour was accidental and undocumented. Sections defines the structure of the content tree. You currently cannot remove the branch you're sitting on.

[bep]

OK, I'm touching this area now in relation to another issue.

I have thought a little about this, and here is how I see how it should work:

If a page is not not scheduled to build (because it's marked as a draft or it has publishDate in the future or expiryDate in the past), that page and its descendants will not be built.

This will, in the most extreme case when setting the home page to draft, produce nothing. But it's, I think, what most people would want and it saves some headache deciding what to do with dangling nodes.

/cc @regisphilibert @kaushalmodi

[regisphilibert]

I can see some edge cases where people want the section not published but their children published.

You have a "section" which still needs a _index.md for you will need it to apply some FM to descendants with Cascade.

Yet, you don't need section published as only its descendants will be accessible through the site.

So I'm not sure drafing a section should necessarily endup with the drafting of its descendents as you can easily already achieve it with Cascade:

title: That Section
cascade:
  draft: true

[bep]

Yet, you don't need section published as only its descendants will be accessible through the site.

And you mean that you should mark them as draft to solve that particular problem?

We have an apple tree. If you remove the home page, all the apples will fall to the ground.

[bep]

@regisphilibert note that I do understand what you're asking for, but let's build that and not repurpose the draft flag for something that it isn't.

[Brixy]

6316 is kind of related.

The question is whether Hugo should support

• drafted sections and
• unlisted sections

while publishing the underlying articles/children at the same time.

According to the forums and reading theme templates there seems to be a demand. Personally speaking I do have need for it and have been using hacks for these functionalities for years.

The already implemented cascade would be very logical param for fine tuning – although Newton would be shocked lying under the hovering apples of a branchless tree ;-)

[bep]

Thanks @Brixy -- there is also a related issue asking about a "no render" config per language.

I can add a little context here as to why I'm bringing this up now:

While working on the sought after "pages from data" feature, I'm consolidating the data structure used to store pages/resources to a couple of well-defined Radix trees. This gives simple and fast tree navigation and lookups. The "faster" part of this will be a bonus, but given that pages/content can come from many different sources, we need a reasonably simple way to determine where they belong in the content tree ("/content/blog/page.md" belongs in the blog section etc.).

We have some ambiguity already in Hugo, and I would hate to bring additional complexity into the above because of what seems to be unrelated requirements.

So, I'll stick with my game plan: If you draft (or in any other way "unpublish") a section, that behavior is recursive.

And then we can consider adding:

• unlisted
• unrendered (i.e. no Permalink)
• _cascade.json (or TOML etc.) that can live in any folder.

Note that the work I'm currently doing will make 3 bullets above much easier to implement/reason about.

[Brixy]

Thanks @bep for you explanation. This is truly complex. Thanks for all your excellent work.

And then we can consider adding:

• unlisted
• unrendered (i.e. no Permalink)
• _cascade.json (or TOML etc.) that can live in any folder.

👍

[regisphilibert]

Yes I agree draft should not be the way to not render some pages.

Those new keys would be very welcome by a lot of people.

[kaushalmodi]

If a page is not not scheduled to build (because it's marked as a draft or it has publishDate in the future or expiryDate in the past), that page and its descendants will not be built.

Since this change (https://github.com/gohugoio/hugo/issues/6171#issuecomment-518795490) has already happened, that proposal makes sense.

As for the original purpose of a draft page, a draft page is as good as not having that page because such pages are not deployed in production.

As absence of an _index.md prevents rendering of the entire section under it (exceptions: home page, root sections), it makes sense that a draft _index.md would give the same behavior (with the same exceptions).

[kaushalmodi]

Just thinking more on my last comment, this change will though make it difficult to manage what content is ready for publishing vs not.

E.g. right now I have few draft sections and I can work on them, see preview, etc without worrying that they will get deployed to production even if I commit those files to git (as Netlify does the deployment).

Now if the draft sections will stop generating the entire section, how will I see the preview of those section pages?

I would need to undraft the section to actually see the previews and that can get committed by mistake. Even if I don't make such mistake, it adds an overhead of checking that I don't make that mistake..

I am assuming that the draft switch will still render the entire drafted sections.

[bep]

how will I see the preview of those section pages?

hugo -D

[bep]

As for the original purpose of a draft page

The original purpose of draft did not include section pages -- as that was not a thing back then.

[bep]

@kaushalmodi I assume that what you mean is that if you have:

└── blog
    └── funny
        ├── _index.md
        └── cats.md

And _index.md is marked as draft.

If we pretend that _index.md does not exist, then cats.md would end up in the blog section, and moved to the funny section once the owning section was undrafted. To get to the above would be technical clumsy, but I would also call the behavior confusing -- and very much undefined if you do it with the home page (we would need to create that page with some defaults).

[kaushalmodi]

I assume that what you mean is ..

If we pretend that _index.md does not exist, then cats.md would end up in the blog section, and move to the funny

No! That's definitely not what I'd expect.

If that _index.md is drafted or absent, then without -D, the whole funny section will not get published.

Essentially, this proposal adds implicit "cascading" of the draft param from the _index.md to the nested pages.

I think I would be fine with that as you confirm that the -D behavior would be unaffected.

[AysunSachir]

I'm having exactly this problem now.
It was very simple to understand before.
https://discourse.gohugo.io/t/draft-set-to-true-in-branch-bundle-is-exported/21381/6

A draft is something unpublished from the beginning. This is the general purpose and global understanding of it. I can work on it, edit it, preview it, but do not publish it.

If that _index.md is drafted or absent, then without -D, the whole funny section will not get published.

Totally agree with this, moving/jumping content around is not ok.

[gonzojive]

This issue confused me for a while. I would print out what pages are drafts when --verbose is passed to the hugo server or hugo command. I could not figure out why my hugo was publishing a blank homepage.

[chrvo]

If that _index.md is drafted or absent, then without -D, the whole funny section will not get published.

Essentially, this proposal adds implicit "cascading" of the draft param from the _index.md to the nested pages.

That would also be the expected behavior from my side. If i define a section as "not published", the entire section is not published. An additional parameter to switch between the old and current behavior would be ok, but the current behavior is only acceptable in rare special cases and a blocker for us to use anything beyond 0.56.