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

docs: Rewrite “Archetypes” article #3543

Merged
merged 6 commits into from Jun 12, 2017

Conversation

Projects
None yet
4 participants
@davidturnbull
Copy link
Contributor

davidturnbull commented May 31, 2017

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 comment has been minimized.

Copy link
Member

bep commented May 31, 2017

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

This comment has been minimized.

Copy link
Contributor

davidturnbull commented May 31, 2017

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

@davidturnbull

This comment has been minimized.

Copy link
Contributor

davidturnbull commented May 31, 2017

@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

This comment has been minimized.

Copy link

budparr commented May 31, 2017

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

@bep

This comment has been minimized.

Copy link
Member

bep commented May 31, 2017

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

## Theme Archetypes

Whenever you generate a content file with the `hugo new` command, Hugo will start by searching for archetypes in the `archetypes` directory, initially looking for an archetype that matches the content's section and falling-back on the `default.md` archetype. If no archetypes are found in this directory, Hugo will continue its search in the `archetypes` directory of the currently active theme. In other words, it's possible for themes to come packaged with their own archetypes, ensuring that users of that theme format their content files with correctly structured front-matter.

This comment has been minimized.

@budparr

budparr May 31, 2017

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.

This comment has been minimized.

@budparr

budparr May 31, 2017

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

This comment has been minimized.

@budparr

budparr May 31, 2017

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

This comment has been minimized.

Copy link
Contributor

davidturnbull commented May 31, 2017

@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

This comment has been minimized.

Copy link

budparr commented May 31, 2017

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 comment has been minimized.

Copy link
Contributor

rdwatters commented May 31, 2017

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

This comment has been minimized.

Copy link
Member

bep commented May 31, 2017

@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

This comment has been minimized.

Copy link
Contributor

rdwatters commented May 31, 2017

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

This comment has been minimized.

Copy link
Member

bep commented May 31, 2017

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

@davidturnbull

This comment has been minimized.

Copy link
Contributor

davidturnbull commented May 31, 2017

@budparr Flowchart has been added.

@davidturnbull

This comment has been minimized.

Copy link
Contributor

davidturnbull commented Jun 12, 2017

@bep Any further changes required for this?

@bep bep merged commit 0f8f514 into gohugoio:master Jun 12, 2017

4 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
deploy/netlify Deploy preview ready!
Details
license/cla Contributor License Agreement is signed.
Details

@ghost ghost referenced this pull request Jun 12, 2017

Open

spf13/hugo v0.22 released #11

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