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

Show comment
Hide comment
@bep

bep May 31, 2017

Member

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

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.

Show comment
Hide comment
@davidturnbull

davidturnbull May 31, 2017

Contributor

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

Contributor

davidturnbull commented May 31, 2017

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

@davidturnbull

This comment has been minimized.

Show comment
Hide comment
@davidturnbull

davidturnbull May 31, 2017

Contributor

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

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.

Show comment
Hide comment
@budparr

budparr May 31, 2017

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

budparr commented May 31, 2017

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

@bep

This comment has been minimized.

Show comment
Hide comment
@bep

bep May 31, 2017

Member

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

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

@davidturnbull

This comment has been minimized.

Show comment
Hide comment
@davidturnbull

davidturnbull May 31, 2017

Contributor

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

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.

Show comment
Hide comment
@budparr

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

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.

Show comment
Hide comment
@rdwatters

rdwatters May 31, 2017

Contributor

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.

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.

Show comment
Hide comment
@bep

bep May 31, 2017

Member

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

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.

Show comment
Hide comment
@rdwatters

rdwatters May 31, 2017

Contributor

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?

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.

Show comment
Hide comment
@bep

bep May 31, 2017

Member

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

Member

bep commented May 31, 2017

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

@davidturnbull

This comment has been minimized.

Show comment
Hide comment
@davidturnbull

davidturnbull May 31, 2017

Contributor

@budparr Flowchart has been added.

Contributor

davidturnbull commented May 31, 2017

@budparr Flowchart has been added.

@davidturnbull

This comment has been minimized.

Show comment
Hide comment
@davidturnbull

davidturnbull Jun 12, 2017

Contributor

@bep Any further changes required for this?

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