Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Static site generators need less rigid content APIs

fvsch.com

Post reply on HN
Print view View original

71–75 of 75 posts

Re: Static site generators need less rigid content APIs

#71

Post by bjornerik »

JeanMarcS wrote: post #22

For sure everyone have his favorite way of doing things and what seemed obvious for some will look strange for others. As I tested myself several SSG, I (as many it seems !) thought « Well, none fit my needs so let’s make one » My problem was that I need an interface for the final clients, which are no tech at all, to be able to edit content. Solutions like Hugo are not possible as it would means install it on a comp…

The article in the top of this thread is interesting. I can just add that in Hugo we have tried to make it simple for the simple stuff, but also make the "harder stuff" possible. We have naming conventions for layout files to keep it DRY (to avoid having to set "layout: blog" or something in every content file (you can)) and we have some special meaning behind "index.md" and "_index.md" -- which among other things allows for a navigable and not so rigid content tree. We even have plans to, in near future, to extend that tree into the content files themselves (ToC, paragraphs, sections). We may have different trade-offs than the article writer: With many sections and thousands of files in a deeply nested content tree, Hugo's layout system its speed may make more sense. Or not. So we do try, but it is hard to make everyone happy. I'm bep on GitHub.

Re: Static site generators need less rigid content APIs

#72

Post by fvsch »

PuffinBlue wrote: post #31
kaushalmodi wrote: post #21

The post author seems to have not reviewed at least the Hugo docs very well. One clean sign is that he listed "Page Bundles", "Leaf Bundles", index.md and _index.md as "different concepts", when in fact they are all Page Bundles. Also the author completely missed the point that everything is a "page". I wish I had time to write a detailed reply to this post but looks like the author has made up his mind to puke on Hu…

Nothing that you wrote really comes across as anything but 'yeah, Hugo is complicated'. Which is sort of the point of the specific call out of Hugo. And I've been using it for a very long time now. I actually wrote the original _index.md explainer page for the docs at the time the switch was made to stop it being 'abused' for section front matter. At least, I think that was the work around people were using, I forget…

My point in that article was indeed about complexity and the difficulty of learning many concepts. How do you figure which concepts are actually "the same"? If they are indeed the same, why ask users to pay the cognitive cost of learning five concepts then figure out that they’re synonyms? But are they really the same, though? I gather that they must do a few things differently. In my experience when I renamed a `index.md` to `_index.md`, I lost access to one feature and got access to a new one (my issue was that I actually needed both!).

The section I wrote about Hugo, and indeed my whole article, is not purely about technical capabilities. It’s about user capabilities when using specific software, so there’s some focus on what the software can do, but also on the user’s perception of what the software can do and on the learning curve.

In my day-and-a-half with Hugo, I’ve read most of the docs twice, and have read some old issues and release notes. It looks like some of the complexity in Hugo’s design comes from adding features and redesigning some features over time. This process tends to accumulate cruft, and calls for compromise between conceptual clarity and backwards compatibility.

At one point I’ve read release note (for 0.20 I think) that said something like “from now on, everything is a Page”, but was surprised that different kinds of pages had access to different kind of data, somewhat arbitrarily. By contrast, if you start with a concept like “everything is a page and has a predictable feature set”, it’s easier to have this simpler design correctly implemented and correctly reflected in documentation.

Re: Static site generators need less rigid content APIs

#73

Post by fvsch »

pknopf wrote: post #36
nkristoffersen wrote: post #34

Earlier quoted context omitted.

The bottom line is flexibility and speed. With Gatsby you get both. Only looking at it as a .txt > .html convertor is very limiting. I generate 1,500 webpages every day from custom datasources with Gatsby. Using React components gives me DRY code. This gives me very great flexibility during development and great SEO and speed in production.

> The bottom line is flexibility and speed Gatsby gives you neither. Give me a tree navigation. Oh, it's not supported? Now, in order to implement it, I have to figure nodes/graphql/webpack/fragments (I know the tech, but it it's _used_) to get a solution that I could whip up myself in 30 minutes if the tooling and techstach wasn't bogging me down. There is a hidden cost to large peices of software with high ceremony…

This matches my impression of Gatsby after a day with it. I bailed a bit more quickly than with Hugo, so I refrained from adding a Gatsby section to my already too long article. Also my main takeaway was “Gatsby is an overengineered mess from (and favored by) people who are already all-in on React and GraphQL and don’t realize the learning curve they’re asking others to climb to build simple sites”. Too categorical for something I’ve only spent a short day with, so I decided not to include it.

While I do know React well enough, when trying to work with local content I had to follow a tutorial that asked me:

1. To install 2 plugins 2. To copy-paste 3 different chunks of boilerplate code (configuration, the code that maps filesystem data into some kind of representation — maybe using GraphQL already, I’m not sure — and lastly the GraphQL queries to retrieve that data). 3. To personalize this boilerplate code, which requires me to learn GraphQL.

Other tools can do similar work without plugins, without having to learn a second language (GraphQL) separate from the core language that the tool is using (JavaScript), and without having to write code to feed content into a in-program representation yourself.

It could be that all this overhead is worthwhile because it enables you to do complex things. But from what I’ve read I wasn’t even sure that Gatsby could achieve my use case without me duplicating my information architecture as “feed content to the in-program representation” code, and I didn’t want to risk spending a second day only to find out that it couldn’t. (Your comments about tree navigation, as well as some of the GitHub issues I’ve read, suggest I was right to bail out.)

My actual takeaway is that Gatsby might be a good fit if you already know React and GraphQL (or already wanted to spend time learning those), and are working with remote content from a headless CMS and some other sources. But for local content only, unless you already know Gatsby or want to use that project to learn it, it’s needlessly complex and overkill.

Re: Static site generators need less rigid content APIs

#74

Post by kall »

fvsch wrote: post #73
pknopf wrote: post #36

Earlier quoted context omitted.

> The bottom line is flexibility and speed Gatsby gives you neither. Give me a tree navigation. Oh, it's not supported? Now, in order to implement it, I have to figure nodes/graphql/webpack/fragments (I know the tech, but it it's _used_) to get a solution that I could whip up myself in 30 minutes if the tooling and techstach wasn't bogging me down. There is a hidden cost to large peices of software with high ceremony…

This matches my impression of Gatsby after a day with it. I bailed a bit more quickly than with Hugo, so I refrained from adding a Gatsby section to my already too long article. Also my main takeaway was “Gatsby is an overengineered mess from (and favored by) people who are already all-in on React and GraphQL and don’t realize the learning curve they’re asking others to climb to build simple sites”. Too categorical f…

I think you might be right on with "people who are already all-in on React and GraphQL". I honestly prefer writing JSX/React+GraphQL to a template language even for static content. I like that gatsby makes that an option without making an annoying SPA content site. It‘s a good reality check that this is likely a niche prefer ce.

And I also want to use headless CMSs or other data sources, in my current project a GraphQL source, which maps right in with the (very recent) schema stitching. So I think gatsby is the right choice for me, but I will carefully consider recommending it in the future. Being a VC backed company they may have more cheerleading than other open source SSGs going on.

Re: Static site generators need less rigid content APIs

#75

Post by kylemathews »

pknopf wrote: post #10

This blog post really captures the motivation behind me creating statik. https://github.com/pauldotknopf/statik > This is a simple tool/library. There are no opinions or abstractions, aside from the abstraction needed to host and export content. There is nothing preventing you, the developer, from doing what you want with your project. Parse and render markdown files in a directory for a blog? Build a user manual? Wh…

Wow, you really hate Gatsby don't you?
Post reply on HN