docs: Rewrite “Archetypes” article

[davidturnbull]

I'd like to rewrite a significant portion of the Hugo documentation, to improve clarity and accuracy, and this is my first attempt at doing so.

Suggestions and changes are welcome.

:)

[bep]

This looks very good, but one underappreciated feature of the archetype files that doesn't really get enough attention is that you can fill in the "content section", which is really useful if you have a common layout/disposition for a type of article (with headers etc.).

[davidturnbull]

Great point. I'll work on adding that to the article.

[davidturnbull]

@bep I've added a "Scaffolding Content" section to the article that discusses this feature.

Side note: It'd be great if anyone who uses archetypes could submit examples of theirs, as I think linking to archetypes for the sake of "inspiration" would encourage people to use the feature.

[budparr]

Nice work! Quick note: "front-matter" should be "front matter"

[bep]

This is excellent -- the way you put it, the "content scaffolding" looks even more useful than I thought ...

While we're at it: Could you add this issue to the Notes section: #452

It is an issue I had hoped somebody else could fix, but I guess I will get to it eventually. It is a slightly annoying thing about archetypes that the field order gets "messed with".

[budparr]

and falling-back on the default.md archetype.

This doesn't seem technically correct to me, because I don't believe the look up falls back on the defaults before looking to the theme. I think it looks for matches at the top level, then the theme, then defaults at the top level or defaults in the theme.

[budparr]

Scratch that. I just tested it and it does hit the default first.

[budparr]

Hate to be a pain on this, but I think it's easy to get tripped up on default behavior. So, perhaps, after "and falling-back on the default.md archetype" you can say something like "if one is present" because if there's a default archetype in the top-level directory, any archetypes that exist only in the theme will be ignored.

[davidturnbull]

@bep I've added a reference to the issue within the article, rather than under the "Notes" heading. I think it's easier to understand in context, but I can change this if need be.

@budparr Thanks for the input. I've made the requested changes. To further illustrate the way Hugo handles defaults, I've tried making a flowchart in Sketch, but I'm not a designer, so clarity might still be an issue. Either way, I think flow-charts would help to clarify the decision-making that Hugo does.

[budparr]

Hey, @davidturnbull I think it'd be good to include your graphic. It can always be improved later, but I think it adds clarity.

[rdwatters]

This is pretty freakin' fantastic @davidturnbull One consideration you might want to take a look at is the content on the docs concept, which is already quite different from what is on the gohugo.io: https://hugodocs.info/content-management/archetypes/

Source: https://github.com/rdwatters/hugo-docs-concept/blob/master/content/content-management/archetypes.md

That said, I don't want you to have to do any work twice, so let me know how I can help facilitate. And I agree with @budparr that the graphic is a nice addition 😄 Thanks for these revisions.

[bep]

@rdwatters Bringing in the unreleased docs concept is adding confusion and isn't very helpful. Let us focus on this article which is targeted to get merged into this repository.

[rdwatters]

I think bringing in the unreleased docs concept is adding confusion and isn't very helpful.

How would you recommend I make sure @davidturnbull 's improvements don't get lost when we finally get the new docs site up and running?

[bep]

@rdwatters I would recommend that discussion to be taken somewhere else.

[davidturnbull]

@budparr Flowchart has been added.

[davidturnbull]

@bep Any further changes required for this?

[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.