I think that it could be useful to have like a hugo recipe book, with several pieces of code that you end up using all the time. For example, I’ve seen that many people have similar questions about taxonomies. Since I created little repo dedicated to the use of taxonomies, a couple times, helping people has been as easy as pointing them to those examples. So if we had a little recipe book, it would be easy to just point them to the snippet that best fit their needs.
I’ve been documenting several snippets and I use them for most of my projects. So I’ve found that it also helps me save some time.
You can find most of what you need in the docs. But people, specially non-developers, need more examples. And I think that if the docs were all filled with thousands of little examples, it could get very messy, unless there was a dedicated section just for snippets. For example, let’s say you have a snippet that combines .Scratch and taxonomies. Would that go in any of the 3 pages for taxonomies, or in the .Scratch page? That’s why I think that “recipes” need their own space.
So I have 3 questions:
Is there anything similar already been worked on, and that I can contribute to?
If not, is there anybody interested in having something like it?
What would be a nice way to document all those snippets? I’ve been using gists and repos. But there must be an easier way to do it. Does it belong to the docs? Or outside the docs?
Yes, that’s possible. But the developer currently switches to a new product called “Cacher” and GistBox will not be available after September. I’m just trying out Cacher (which is free for unlimited public gists) and if it’s as good as GistBox I can highly recommend. Nevertheless I have around 1,070 Gists in different categories. Hugo around 85 so far, CSS around 220 and main snippets are for WordPress and Genesis. Once I know more about Cacher I can report.
I think it’s a good idea, but I’ve seen people try to do the same with Jekyll and they end up being stale (in terms of versions) and not kept up with. I have a bunch of Hugo snippets in gists that I’d be happy to share them but they have no real context.
Blog posts tend to be the most helpful, in my opinion. I do keep a collection of Hugo related blog posts on my site (and if you see a good one that I’ve missed, let me know). There are 77 articles there and some of them are really helpful.: https://www.thenewdynamic.org/tool/hugo/
I’m making something like this to hold Hugo and CircleCI snippets. I have nothing up yet though if noone gets to this before September is over, I’ll share what I have. My plan is to do something like a GitHub Gist per snippet, but with having all of them under one “category” such as Hugo, and searchable.
I had a similar idea a couple months ago, mainly for shortcodes but it could also include all kinds of other useful snippets. The best way to make them useful (and therefore used) is to make it an educational experience for the reader. They see the snippet, they see an explanation of how it works and why it does what it does, and maybe some examples (not built out examples but just descriptions) of how it could be used. I would say, any submissions would have to include that information, because that would make learning Hugo MUCH faster for noobs and using the snippets much more enjoyable because now you know how it works and can build on it if needed. I was wanting to build a site for this but I got busy with other stuff and haven’t gotten back to it. You could have shortcodes, archetypes, partials, etc in this resource.
Ah. Maybe concept was a bit different. Pretty much without the explanations. The only explanation I imaged would be as comments in the snippet.
To me, once you include explanations, it’s basically docs. As for examples, the snippets would be the examples. I imagine linking or embedding “snippets” into docs, blog posts, etc. The snippet library would just be for hosting and maintaining the snippet.
My view is it would be better to make something that can be used to gain new users to Hugo (hence the educational part of it) while also providing great tips/snippets for everyone. If it’s just a snippet repository, that has limited usefulness and quality. If it’s useful for teaching then that helps everyone, especially new users come up to speed fast. I think if something like this is going to be worth making, it’s worth adding a bit of prose explanation to the snippet for people to grok it from a new user perspective. That’s how you build and add to the community in a sustaining and helpful way.
