I don't want to shit on this project, because that's not my intent. My biggest gripe with static site generators in general is that for some reason they require the author to write their pages in something other than plain HTML. It's literally a machine-readable format and yet they all want to mix json, yaml, or something with markdown. And "but the output html would overwrite the input html" isn't really an excuse since they all tend to output to a build directory.

And before someone says, "well you can work on your dream static site generator yourself", rest assured, I am, but I'm also very lazy and usually stop once it gets to a "good enough" state for my own use, but isn't quite ready to share with others.

▲

thangalin 4 hours ago | parent | next [-]

> My biggest gripe with static site generators in general is that for some reason they require the author to write their pages in something other than plain HTML.

Being the author of KeenWrite, a Markdown editor that uses YAML variables (for content and metadata), I'm biased, but here's my take:

1. Writing <p> tags for every paragraph gets tedious.

2. Markdown is succinct (**bold** vs. <strong>bold</strong>).

3. Content is easier to edit when not surrounded by angle brackets.

4. Content is more robust against markup gaffs (e.g., missing closing tags, tag typos).

5. HTML mixes structural markup with content, making design changes harder.

6. Markdown's simpler format is more portable to other output formats (PDF, ePub).

7. Markdown diffs are easier to review, and likely have fewer merge conflicts.

8. Non-technical contributors are more comfortable with Markdown.

9. Embedding metadata through meta tags is messier and harder to parse using raw HTML.

Here are a couple of blog posts written in Markdown and converted to HTML using my software:

* https://keenwrite.com/blog/2025/09/08/feature-matrix/

* https://keenwrite.com/blog/2025/10/15/creating-catchy-cover-...

The user manual is a set of Markdown documents converted to PDF (note how the words TeX and ConTeXt and LaTeX are typeset; try to do that with HTML):

* https://keenwrite.com/docs/user-manual.pdf

	▲	bigbuppo 3 hours ago \| parent \| next [-]
		And this is the other big rub with static site generators... they start off as one person's strong opinions as The Right Way To Do It. And that's fine. 1. Not really 2. Get a better editor 3. Not really, or get a better editor 4. Get a better editor, implement error checking, and use HTML5 5. The idea is to use clean semantic html as the source document and stuff it into a presentation template 6. The source document is clean semantic html 7. Let's be real. 99.99999% of all static site generators are used by one person, generally technically proficient. Merge problems will only happen if you screw up. Also, most modern version control systems aren't storing deltas so merge hell isn't like it was back in the CVS era. 8. Get your non-technical people a better editor 9. Have you explained the quirks of YAML to a non-technical person in one of the Scandinavian countries like Sweden or False? 10. why isn't this formatting properly?
	▲	bigbuppo an hour ago \| parent \| prev [-]
		Also... KeenWrite looks nice. You made the better editor for markdown.

▲

hnlmorg 4 hours ago | parent | prev | next [-]

Forgive my ignorance here but if you want to write HTML then what do you gain from a static site generator?

Couldn’t you just ‘cat’ your templates together with a shell script?

	▲	bigbuppo 3 hours ago \| parent [-]
		Starting with clean valid semantic HTML makes it a whole heck of a lot easier to preview in a web browser or editor with a preview feature and gives you quite a few editing options. Granted, there are now live markdown previews in some editors, so this is less of a concern than it was. However, you can easily toss in some CSS in there to make things a little nicer, while the typical markdown preview is going to look like Netscape 2. As for the templates... those are also HTML. You're just replacing the relevant part of the template's DOM with what you pulled from the source document. Same goes for any boxes on the page you need to stuff with generated content. Your index pages and blog lists are generated from the metadata and other items pulled from the relevant parts of the source documents using the favored html processsing library of the week. edit: I think I did a terrible job answering your question in my initial reply. Ultimately, a static site generator is doing what was the way that SGML was envisioned to function... you started with a simpler authoring document and passed it through a processing pipeline that generated a richer SGML document that was eventually output to some sort of output presentation form. My take is that instead of using yaml and markdown for the source documents you just use semantic html, and that templates just use everything that WHATWG has given us with modern HTML instead of that plus a template language.

▲

granra 5 hours ago | parent | prev [-]

Generally I think you have a point when making landing pages or things of that sort. I however basically only use static site generators for blogging and I think markdown/asciidoc/whatever + metadata is nicer for writing content than directly in HTML.

I made nixtml and I take no offence :)

	▲	bigbuppo 3 hours ago \| parent [-]
		I think part of my take stems from the fact that I'm old enough to remember when SGML was supposed to solve all our problems.