Hacker News Reader

Comment by Brajeshwar | Hacker News Reader

Honestly, I could not get to a point of clarity on What does this exactly do. I went through the website's landing page and looks pretty rock solid. But this seems to be trying to do too many things in a pretty complex way for a small and simple output. I want to like this, and I think this can help me with some of my mundane chores and focus on the content but I just cannot quite grasp it.

Can someone, please, do a "This" is the typical problem we face with HTML in Static Site Generators and "this" does "something" to solve that?

View on HN

I agree that the advantages are not clear. Maybe this table of comparisons should go on the landing page: https://soupault.app/tips-and-tricks/comparison/

Most SSGs force a blog-oriented directory structure like assets/ static/ theme/ posts/ public/. But soupault only needs an input/ and output/.

Most SSGs convert markdown to HTML. But soupault is good at processing (or ignoring) any sort of source content, which is nice for excluding one-off pages, or parsing non-markdown, or using existing HTML content.

For me what‘s standing out is getting rid of frontmatter. The title is extracted from <title>, for example. Have a look at the widgets section of the reference manual, it‘s really cool what they do.

I was wondering if that part should have been the main page slogan: "Soupault’s DOM manipulation is as powerful as client-side JavaScript (without interactivity, of course), but the result is a static page."

>Maybe this table of comparisons should go on the landing page

The elephant in the room is that none of the popular tools' websites make any sense to people who aren't already familiar with that class of tools. I happened to accidentally come up with a tool that's too unlike anything else to be easy to explain by "it's like {alreadyPopularTool} but with {importantDifference}".

I also hope that people from the Web 1.0 revivalist circles who hate typical SSGs for their hostility to handwritten HTML on board, although that development was ironic: the reason I included the HTML post-processor mode was to help those folks inject consistent navigation into otherwise handwritten pages or similar — in reality they just told me they were _proud_ of wasting their time on that completely automatable task, but the post-processor mode was a surprise hit with people who wanted to fix up outputs of inflexible HTML generators.

The comparison table is not very helpful for people who might not have seen an SSG before, placing it on the main page might create a confrontational tone (because it's focused on things that soupault made possible compared to other tools), and I'd have to constantly watch those projects to see if anything is no longer true.

For example, it would be pretty easy to allow Hugo call AsciiDoc and other external processes with custom CLI options — I'm sure someone will eventually do it and it will be a big improvement for those who want to use Hugo.

It was a little difficult to wrap my head around at first, but for me its main benefit is this:

In many static site generators, if there is a page in a collection of pages (say, a product page) that you want to add a custom layout to (but without affecting other pages in that collection), you often need to create a separate template, or modify the default template to allow for this exception. With Soupault, page content is typically written in HTML and giving a specific page a custom layout is as simple as including an <html> element in that page’s content file and it will be treated as a completely standalone page. In other words, a content file is not as different from a template as in typical static site generators.

This flexibility and HTML-first approach cuts down on complex or sprawling templates introduced to deal with many exceptions. And as a result, someone only needs to know HTML to make most edits to a website. Of course, you can make certain patterns more efficient with “widgets” (basically snippets to insert content dynamically) defined in the main configuration file, but it is not requisite.

At the end of the day, the website is mostly just HTML with a simple project directory structure, which makes it understandable to a wider audience, which is important to me since I want the website to be easily understandable for future maintainers of it.

Edit: Another benefit is that Soupault is a single statically-linked executable with no dependencies, and therefore can be downloaded via a simple link. This also extends the longevity of websites built with it (i.e. it is easy to get the development environment setup).

> Edit: Another benefit is that Soupault is a single statically-linked executable with no dependencies, and therefore can be downloaded via a simple link.

My single executable is called 'docker' for these kind of tools. No need to download anything at all.

> If you are already familiar with other static site generators, check out the comparison with Hugo, Zola, and Jekyll. [1] You may also want to read the FAQ. [2]

[1] https://soupault.app/tips-and-tricks/comparison/

[2] https://soupault.app/tips-and-tricks/faq/

I'm gunna be honest: I'm in this court ("why?" "what problem does this solve?") with, well, the whole SSG thing.

I get why people want to write their content in Markdown (well, specifically, I get why tech people want to write their content in Markdown, but not normal humans who almost always want a WYSIWYG) - but what I just can't get my head around is the vast complexity that almost all these tools seem to bring to the table.

I've looked at it for so long now I think I've basically got a terrible mental block - for most scenarios, I just don't get it. I don't see what the problem is that is being solved. Booting up a bunch of HTML files, or a simple WordPress site, or a manually built PHP thing that pulls Markdown files and uses a couple of includes to solve the "how do we replicate menus?" question - this makes sense to me.

I'm not talking about this tool (like you I have no idea what it actually does) but the whole Hugo/Gatsby/Jekyll/etc thing. Having (what looks like!) a steep learning curve, then a whole bunch of build steps, lots of dependencies, frameworks, templates etc etc - in order to get what is being sold here as the end game (a fast, dependency free, "just html", no risk website) just feels like ...madness.

I badly need someone to explain to me why all these tools are doing something better. That's a serious request, btw, would love for someone to enlighten me!

The tools (mostly) all start out simple, as you described. Then they start to get traction and users. More users equals more diverse use cases and feature requests. Each individual request makes sense, for that group of users, and is implemented. Slowly the software grows in complexity, until you have Hugo etc... Then people say it's too complex and start over - and it all happens again.

This applies to all software - and most other things that humans make that have large numbers of users, like governments, countries, or other systems.

Delegating the complexity to the user was my biggest motivation behind many features of soupault.

Hugo has two different Markdown libraries baked in and you have to choose them, and it also had hardcoded commands to call rST and AsciiDoc processors. If you are migrating from a different SSG, Markdown processors behavior differences can bite you and there's no way out.

With soupault, you just configure a command to convert a file with a certain extension to HTML, and all features (ToC, footnotes, anything provided by plugins...) work the same because they they are implemented by manipulating the parsed HTML element tree.

Want a CSS preprocessor? You can pipe <style> tag contents through any external program if you feel like it. Want to re-compress or manipulate images? You can write a Lua script that gets their paths from <img> and <picture> tags and calls an external program on their files. And so on.

Happy user of Soupault here. What you described here:

> Markdown processors behavior differences can bite you and there's no way out.

is under appreciated. The lack of “surprises” in Soupault is very appreciated.

Reply on news.ycombinator.com