Why I built my own static site generator(yakkomajuri.github.io)
yakkomajuri.github.io
Why I built my own static site generator
https://yakkomajuri.github.io/blog/teeny
123 comments
I notice that people who bring up shell scripts or makefiles in these types of discussions tend to tout the virtues of their setup based on those alone—putting undue focus on the glue layer, instead of the parts doing the heavy lifting—and this behavior strikes me as very odd.
Shell scripts are only as stable as the executables that they invoke (and portability is a separate matter worth taking into account, too—few people who mention stability address the issue of incompatible variations of shell and make across different systems). In this case, the upper bound is determined by peg-multimarkdown that you depend on.
Shell scripts are only as stable as the executables that they invoke (and portability is a separate matter worth taking into account, too—few people who mention stability address the issue of incompatible variations of shell and make across different systems). In this case, the upper bound is determined by peg-multimarkdown that you depend on.
> You don't have to be on the Node treadmill to create a static site generator. You can use something stable!
Node isn't always a treadmill. JavaScript itself is very stable, much more than many other languages. The big thing you need is something to transform markdown to HTML. You can either write it yourself, or take one that's stable. The rest can be done in plain JS, without libraries.
Node isn't always a treadmill. JavaScript itself is very stable, much more than many other languages. The big thing you need is something to transform markdown to HTML. You can either write it yourself, or take one that's stable. The rest can be done in plain JS, without libraries.
I have my own too. It is a Makefile that makes extensive use of the core utils (sed!) and xml2 and 2xml to be able to process HTML using the line-oriented tools in the core-utils.
I also built a blog engine on top of git using sh scripts and the core-utils in git hooks (https://p4bl0.net/shebang/fugitive-readme.html), but that was a long time ago and I don't use it anymore. It had a dozen users at some point and I even received a few contributions to the project. Fun times :).
I also built a blog engine on top of git using sh scripts and the core-utils in git hooks (https://p4bl0.net/shebang/fugitive-readme.html), but that was a long time ago and I don't use it anymore. It had a dozen users at some point and I even received a few contributions to the project. Fun times :).
It works by concatenating html files with some minimal replace. So it's easy to edit and update.
If it ever becomes too slow, maybe I look into using xargs -P or adding more '&' between commands.
If it ever becomes too slow, maybe I look into using xargs -P or adding more '&' between commands.
Mine uses pandoc and core utils to convert markdown to html and shoves it into an existing page template to create a blog post.
I could add menu / link tracking pretty easily but I don't need it. My script is less than 15 lines long and can convert any number of markdown files into their own pages on my site, ready to serve.
I could add menu / link tracking pretty easily but I don't need it. My script is less than 15 lines long and can convert any number of markdown files into their own pages on my site, ready to serve.
[deleted]
You can probably do most of it in awk.
I've done most of this in awk.
I've done most of this in awk.
One big benefit would be you could release the Static Site Generator as “Awk Word”, which is a pun I've been trying to make for month.
Wow, you've just made my life better.
I just use PicoCMS and I forget about it. Just upload markdown files, that's about it.
I built a static site generator mostly because I wanted to dick around with some concepts in hypertext, like automatic backlinks and a very explicit filesystem metaphor.
I also primarily target the Gemini protocol, so the web presence is a bit of an afterthought and that probably shows as well. I deliberately included every limitation of gemtext into the HTML rendering of the documents, including no inline links and no inline images. It does do some special rendering but very little.
It's backed by a git repository with gemtext files that get rendered into HTML. There is also a gmi->gmi conversion for gemini, as I introduced a few non-standard tags to instruct the page generator to add stuff like generating feeds for the blog part and so on.
The result is weird and not at all intuitive. I also realized this is basically off-brand Confluence except not as hard to navigate and 1000 times faster.
But yeah, the main point is experimentation. Testing ideas and seeing what sticks. Some of it does, but not everything. Like I have no headers for my web sites. My thought was that it's just a part you scroll by, a piece of pointless self-promotion. I wanted to elevate the content above all else. Turns out it's pretty confusing when you do that. Books have a cover for a reason.
I also primarily target the Gemini protocol, so the web presence is a bit of an afterthought and that probably shows as well. I deliberately included every limitation of gemtext into the HTML rendering of the documents, including no inline links and no inline images. It does do some special rendering but very little.
It's backed by a git repository with gemtext files that get rendered into HTML. There is also a gmi->gmi conversion for gemini, as I introduced a few non-standard tags to instruct the page generator to add stuff like generating feeds for the blog part and so on.
The result is weird and not at all intuitive. I also realized this is basically off-brand Confluence except not as hard to navigate and 1000 times faster.
But yeah, the main point is experimentation. Testing ideas and seeing what sticks. Some of it does, but not everything. Like I have no headers for my web sites. My thought was that it's just a part you scroll by, a piece of pointless self-promotion. I wanted to elevate the content above all else. Turns out it's pretty confusing when you do that. Books have a cover for a reason.
I built mine too, for similar reasons: it felt easier to write from scratch, so that my site looked the way I wanted it, than customize some of the existing solutions (Jekyll, Hugo, etc).
Sure it’s not customizable at all: it can only generate my site. And that’s fine. I like it that way.
For example: I sometimes translate poetry, and I have a bunch of code that renders individual poems from plaintext (not Markdown, because newlines and whitespace _are_ significant): https://github.com/nathell/nhp/blob/master/src/nhp/poems.clj
Sure it’s not customizable at all: it can only generate my site. And that’s fine. I like it that way.
For example: I sometimes translate poetry, and I have a bunch of code that renders individual poems from plaintext (not Markdown, because newlines and whitespace _are_ significant): https://github.com/nathell/nhp/blob/master/src/nhp/poems.clj
I should preface I'm a solo-founder with a few side-projects(nothing big). Thus you have to usually make due with "just good enough" and move on to the other 10 tasks awaiting you.
My deploy script (it's just 5-10 lines of bash) mostly for some of my "old" angularjs(yes v1)
1) merge all js files (cat file.js >> app.js)
2) make sure any files that request/include JS and HTML files are not cached (generate new random ?rcc=random-num)
Sexy ? Absolutely not , does it work ? Like a dream :)
Having the ability to just type "./deploy-aws.sh" and be done in 5 sec is an amazing ability to have for you project. Especially if you are SOLO founder.
My deploy script (it's just 5-10 lines of bash) mostly for some of my "old" angularjs(yes v1)
1) merge all js files (cat file.js >> app.js)
2) make sure any files that request/include JS and HTML files are not cached (generate new random ?rcc=random-num)
find -type f | egrep "html|js" | xargs sed -Ei s/"rcc=([0-9]+)"/rcc=$RANDOM/g
Sexy ? Absolutely not , does it work ? Like a dream :)
Having the ability to just type "./deploy-aws.sh" and be done in 5 sec is an amazing ability to have for you project. Especially if you are SOLO founder.
Thought about using s3? I have static content I keep version controlled in github with a git hub action.
When I push to the production branch, a github action does an aws s3 sync. My web service pulls static content from the s3 bucket.
It works well and i really like github actions for this kind of work.
When I push to the production branch, a github action does an aws s3 sync. My web service pulls static content from the s3 bucket.
It works well and i really like github actions for this kind of work.
Perhaps you'd like to package your preprocessor into something to make Personal Home Pages...
As evidenced by the comments in this post, developers love developing new static site generators.
Unfortunately, we typically lack the same enthusiasm for actually writing content for said static sites.
So you end up with 1,000,000 developer blogs with an average of 1 post.
The title of which is “how I built this blog using X”
After having gone through this charade many times myself (I’m a high level procrastinator), if your goal is to publish on the internet, do not spend time creating a custom static site generator.
In fact, don’t use a static site generator at all (you inevitably won’t remember how it works and will have broken dependencies years later when it comes time to pen post number 2).
Just sign up for a basic site builder (Webflow if it’s a company site, squarespace if it’s a personal blog), pick a not-offensive template, and be done with it.
Trust me, nobody will think less of you.
By eliminating the decision points around building something, you can force yourself to not waste hours comparing CSS frameworks and instead actually write something of value for other people.
Unfortunately, we typically lack the same enthusiasm for actually writing content for said static sites.
So you end up with 1,000,000 developer blogs with an average of 1 post.
The title of which is “how I built this blog using X”
After having gone through this charade many times myself (I’m a high level procrastinator), if your goal is to publish on the internet, do not spend time creating a custom static site generator.
In fact, don’t use a static site generator at all (you inevitably won’t remember how it works and will have broken dependencies years later when it comes time to pen post number 2).
Just sign up for a basic site builder (Webflow if it’s a company site, squarespace if it’s a personal blog), pick a not-offensive template, and be done with it.
Trust me, nobody will think less of you.
By eliminating the decision points around building something, you can force yourself to not waste hours comparing CSS frameworks and instead actually write something of value for other people.
So developers like developing stuff. Yeah that probably about sums it up.
I don't think that's an obstacle to writing. Let's be honest, the average blog lifetime is probably lasts less than a dozen posts. The ones that last are weird outliers, and that's not a problem from choosing the wrong technology.
I don't think that's an obstacle to writing. Let's be honest, the average blog lifetime is probably lasts less than a dozen posts. The ones that last are weird outliers, and that's not a problem from choosing the wrong technology.
> I don't think that's an obstacle to writing.
It absolutely has been for me, and I'm willing to bet if you actually track your time, you might be surprised.
Obsessing over building is like a warm blanket for someone who's a developer by trade. Writing in public, by contrast, will make a non-writer extremely uncomfortable and vulnerable.
And humans are super good at pain-avoidance.
I spent roughly 200 hours trying to be clever about building my last blog (experimenting with static site generators, headless CMS options, markdown flavors, CSS frameworks, build process, etc) when I was first getting enamored with the static site world.
Fast forward a few years, it turns out I built a monster that I can't remember how to use, nor do I care to.
And I realized instead of getting my ideas into the world, I hid behind that security blanket of "building."
It absolutely has been for me, and I'm willing to bet if you actually track your time, you might be surprised.
Obsessing over building is like a warm blanket for someone who's a developer by trade. Writing in public, by contrast, will make a non-writer extremely uncomfortable and vulnerable.
And humans are super good at pain-avoidance.
I spent roughly 200 hours trying to be clever about building my last blog (experimenting with static site generators, headless CMS options, markdown flavors, CSS frameworks, build process, etc) when I was first getting enamored with the static site world.
Fast forward a few years, it turns out I built a monster that I can't remember how to use, nor do I care to.
And I realized instead of getting my ideas into the world, I hid behind that security blanket of "building."
Well do you actually want to write? If you describe writing as a pain, maybe writing just isn't your jam.
Seems pretty common that people have a romanticized idea of writing, and like the idea of being a writer much more than they actually enjoy the writing process.
Seems pretty common that people have a romanticized idea of writing, and like the idea of being a writer much more than they actually enjoy the writing process.
Been here, done that :) thx for a fun read :)
My most recent attempt to rekindle my old blog turned into a write-a-SSG-that-can-import-tumblr and then a quest to recapture the nostalgic MySpace/text-mode feel, and no actual new blog entries.
Writing an SSG was procrastination at its finest. I did manage to migrate to ghpages and make the old tumblr and google-sites versions auto-redirect.
My most recent attempt to rekindle my old blog turned into a write-a-SSG-that-can-import-tumblr and then a quest to recapture the nostalgic MySpace/text-mode feel, and no actual new blog entries.
Writing an SSG was procrastination at its finest. I did manage to migrate to ghpages and make the old tumblr and google-sites versions auto-redirect.
Yeah, on the other hand, my pro website is based on Jekyll and it doesn’t compile anymore because of version shenanigans…
Yeah I just checked and at least my SSG code is python3. That's a bit of a surprise to me, actually.
Its telling how, over the years, I've had to keep moving my free-hosted blog to a new provider. This is the third time. I'm hoping ghpages are here to stay and don't start doing a sourceforge ad angle or anything...
Its telling how, over the years, I've had to keep moving my free-hosted blog to a new provider. This is the third time. I'm hoping ghpages are here to stay and don't start doing a sourceforge ad angle or anything...
If only network connectivity had scaled up as remarkably as CPUs did over the years, we could all be hosting services from our home machines in true peer to peer manner. Distressingly though ISPs are reinforcing the client-server model by asymmetric bandwidth, blocking ports, forcing customers to purchase business plans for static addresses and so on. All technically unwarranted, purely user-hostile behaviour.
>I went on the Gatsby website, picked a theme, and went to work. And right away, the problem was clear: it was too much.
>Beyond all the extra stuff Gatsby ships with, a lot of Gatsby blog themes try to make things "easier" for you by abstracting away the internals and exposing a config.js file, where you add your name, a bio, some links, and Gatsby does the rest.
>But that comes at a cost. And that cost was made clear by me hunting the favicon file in the directory for a while only to find that some plugin auto-generated it based on a path for a profile photo you could set in the config.
Software design should adhere to the maxim: simple stuff should be simple, complex stuff should be possible.
When software adds so much complexity that simple stuff is no longer simple, it's time to revisit the design.
>Beyond all the extra stuff Gatsby ships with, a lot of Gatsby blog themes try to make things "easier" for you by abstracting away the internals and exposing a config.js file, where you add your name, a bio, some links, and Gatsby does the rest.
>But that comes at a cost. And that cost was made clear by me hunting the favicon file in the directory for a while only to find that some plugin auto-generated it based on a path for a profile photo you could set in the config.
Software design should adhere to the maxim: simple stuff should be simple, complex stuff should be possible.
When software adds so much complexity that simple stuff is no longer simple, it's time to revisit the design.
My website is constructed (and deployed) by a Makefile with a crappy find-and-replace script masquerading as a templating system. More or less this:
all: $(addprefix $(OUTDIR)/, $(addsuffix .html, $(PAGES))) $(addprefix $(OUTDIR)/, $(notdir $(wildcard imgs/*))) $(OUTDIR)/styles.css
$(OUTDIR)/%: imgs/% | $(OUTDIR)
ln $< $@
$(OUTDIR)/%.html: pages/%.page template | $(OUTDIR)
$(BUILDER) template $< $@
$(OUTDIR)/styles.css: styles.css
ln $< $@
deploy:
rsync -avh $(OUTDIR)/ $(DEST)Yes, but it gets tricky real quick.
You might want to have all html pages added to a <ul> in an index.html.
Then you might want a sitemap (similar solution to above).
Then you might want an RSS feed (and an atom feed).
Then you might want height and width attributes automatically set in <img> tags.
It's all doable, but soon your build script is a classic static site generator and dwarfs the Makefile in functionality and complexity.
You might want to have all html pages added to a <ul> in an index.html.
Then you might want a sitemap (similar solution to above).
Then you might want an RSS feed (and an atom feed).
Then you might want height and width attributes automatically set in <img> tags.
It's all doable, but soon your build script is a classic static site generator and dwarfs the Makefile in functionality and complexity.
Indeed, but that's overkill for most personal sites...
That isn't really true. Adding things like image width and height attributes are basic essentials for any content drive website. If you push new content regularly then an RSS feed is very useful for visitors. If you want to be found in Google then you need a sitemap.
If you're not going to do the absolute minimum for your site's users why bother making a site in the first place?
If you're not going to do the absolute minimum for your site's users why bother making a site in the first place?
I wouldn't say any of those qualify as "absolute minimum", particularly for personal sites which owe nothing to their visitors. Omitting img dimensions will cause nothing worse than reflow, while a "what's new" section can be a partial alternative to RSS. As for Google, I'd presume a properly linked (internally) site should be fully crawled even without a sitemap. Maybe not as efficiently, but again, for a personal homepage it is sufficient. Of course in that case one can ask why not just use WP or a SSG that gives you those for free. The downside is of course the time you need to invest upfront in learning those tools and then keeping up to date with their changes and breakages. In contrast, simple HTML, CSS and JS can be safely expected to work for decades at the very least.
In contrast, simple HTML, CSS and JS can be safely expected to work for decades at the very least.
'make' is older than html by almost 20 years.
'make' is older than html by almost 20 years.
What $(BUILDER) are you using? Could be GNU m4 (been there, done that) or something more (or less?) evolved.
Nothing fancy, just a python script that parses each page's "header" (a set of '='-delimited KVPs), interprets the rest as the main content, and then does some text substitution in the template (in practice, I only have a KVP for the page title that's used in the template).
Okay, you get nerd points for that.
I write my website in Emacs org mode, then export to html. I like to think that I win on nerd points :-)
I write my website in Emacs org mode, then export to html. I like to think that I win on nerd points :-)
I tried that but couldn't grok how to set an arbitrary page structure. The default org html export is awful and it seems very opinionated about the workflow, but the docs weren't clear about what those opinions were.
Now I'm using a Frankenstein's monster of org-pandoc and `cat`
Now I'm using a Frankenstein's monster of org-pandoc and `cat`
> I tried that but couldn't grok how to set an arbitrary page structure.
I don't know what this means - I write a normal org document with headings and suchlike, and then export. For site structure I store each page as a separate org file and the html-export exports the links correctly.
It might just be that I am happy with the output so I didn't try to change anything, so didn't run into the problem you did.
I don't know what this means - I write a normal org document with headings and suchlike, and then export. For site structure I store each page as a separate org file and the html-export exports the links correctly.
It might just be that I am happy with the output so I didn't try to change anything, so didn't run into the problem you did.
What do you do if you want to change the layout of the rendered html?
For example, suppose you wanted a sidebar, or an absolute-positioned floating navbar or something.
For example, suppose you wanted a sidebar, or an absolute-positioned floating navbar or something.
> For example, suppose you wanted a sidebar, or an absolute-positioned floating navbar or something.
I suppose that I would have to specify that I wanted to export a ToC with a maximum depth of 1. Currently all my css rules are in a different file (not managed by emacs/org) and I would modify the css in that file to ensure that the ToC appears in a left positioned div, or a floating absolute div, etc.
To be honest, I think that that will only work for a ToC. If you asked "how would you specify a list for the sidebar and another for the top menu navbar" I won't be able to give you an answer[1].
[1] Hey, maybe it can be done, but not as far as I know.
I suppose that I would have to specify that I wanted to export a ToC with a maximum depth of 1. Currently all my css rules are in a different file (not managed by emacs/org) and I would modify the css in that file to ensure that the ToC appears in a left positioned div, or a floating absolute div, etc.
To be honest, I think that that will only work for a ToC. If you asked "how would you specify a list for the sidebar and another for the top menu navbar" I won't be able to give you an answer[1].
[1] Hey, maybe it can be done, but not as far as I know.
I made my own static site generator in a very similar fashion, a small recommendation/tip I found is that instead of creating your own "use this template" definition, you could use "Front Matter"[1] to define this initially:
[2] https://www.npmjs.com/package/front-matter
---
template: custom.html
---
# My normal markdown
import fm from "front-matter";
const data = await fs.readFile(...);
const { attributes, body } = await fm(data);
// attributes: { template: "custom.html" }
// body: "# My normal markdown ..."
[2] https://www.npmjs.com/package/front-matter
Front matter are YAML. I wouldn't call parsing it trivial, though if you want to create a simpler alternative and don't think about it, you're probably going to end up with something worse than YAML.
I never did. I call trivial using an existing tool designed for this, I would def not expect the author be parsing front-matter code manually (as shown in my example).
Hey, thanks for pointing out the `front-matter` library. I've updated Teeny to use that instead of HTML comments.
I definitely advocate for writing your own static generator. For me, my personal web page is my sanctum. Maintaining it is a labor of love.
back in the day, i built my own blog in php[0], while my friend built an ssg for hers (using perl no less). i scoffed at the time, but seeing how things turned out, it seems she gets the last laugh. perhaps the difference is not so large now that cdn's are a dime a dozen.
[0]: after seeing and deriding the code for wordpress. another, much bigger, last laugh there too.
[0]: after seeing and deriding the code for wordpress. another, much bigger, last laugh there too.
I'm surprised nobody mentioned Hugo[0] yet.
I write Markdown and commit to a git repo, then a web hook in Caddy pulls and builds the static site, anything I commit is up in a matter of seconds.
I'd much rather spend what little time I have writing blogs to help people learn new things than write YASSG.
Someone below linked to a site with over 400 SSGs.I think OPs "why" was really "because I wanted to", after having only tried Jekyll and Gatsby (apparently).
[0]https://gohugo.io/
I write Markdown and commit to a git repo, then a web hook in Caddy pulls and builds the static site, anything I commit is up in a matter of seconds.
I'd much rather spend what little time I have writing blogs to help people learn new things than write YASSG.
Someone below linked to a site with over 400 SSGs.I think OPs "why" was really "because I wanted to", after having only tried Jekyll and Gatsby (apparently).
[0]https://gohugo.io/
Not the author, but my issue with Hugo is that the template language is so different from everything else I've ever used that it didn't feel worth the effort to learn (and, later, re-learn) it, when I could just find a different static site generator with a more agreeable template language.
Note: this only applies if you're planning to write your own HTML. If you're using a packaged theme, Hugo would likely be a great choice. I didn't want to use an existing theme, because all the ones I found either didn't do what I wanted or were bloated (or they had Facebook and Twitter logos built in...). For the record, my entire index page (including CSS and favicon) is 1/5th the size of just the CSS used in Hugo's tutorial.
Note: this only applies if you're planning to write your own HTML. If you're using a packaged theme, Hugo would likely be a great choice. I didn't want to use an existing theme, because all the ones I found either didn't do what I wanted or were bloated (or they had Facebook and Twitter logos built in...). For the record, my entire index page (including CSS and favicon) is 1/5th the size of just the CSS used in Hugo's tutorial.
A limited SSG is so easy to write that it might just be less work to slap one together that meets your needs than spend the time trying out a few existing ones and learning enough about how to use them to make an evaluation.
I am afraid to sound millennial but why not WordPress + Static Site Generator Plugin? I totally get it, this is a fun project to test some skills but if the concern was going live, I can go live with vanilla wordpress with their default theme in less than a minute.
Off the top of my head, no constant site-breaking WordPress updates to install, no constant WordPress/plugin vulnerabilities, not to mention much less CPU/storage needed to host the site. Further, since the site is generated to static files, you can host it on any server technology without any concern for whether your given "stack" is supported.
[deleted]
Because it's slow. Even the fastest wordpress static site plugin still requires the huge wordpress site to initialize. I have never seen a fast wordpress site. I mean sub 50ms loading times.
With a plain nginx route to index.html containing some fixed CSS,js files is so much faster.
I think you're misunderstanding what Wordpress's static site generator plugin does. It bakes the WP content in to static HTML files that the server (eg nginx) then serves to the user. Website visitors never hit any part of WP. It's only there for the admin and editor. You can serve the static files from a different server infrastructure (say, an S3 bucket) with a little work.
In other words, it does precisely what you're saying it should do.
In other words, it does precisely what you're saying it should do.
So sounds like you now have to maintain a static site and a wordpress site - is this any easier than just using a static site generator directly?
You only have to maintain the Wordpress site unless you do fancy stuff on top of it. And on modern Wordpress that's quite minimal. The point of this approach is that people with Wordpress expertise can continue to manage the website and you get all the benefits of a static website.
My Wordpress sites have minimal plugins (hence minimal JS and CSS) and run via a VPS and using Litespeed Enterprise, and they're almost as fast as static sites - but with 100x the ease of use and power.
Heck, my Wordpress blogs are faster than when I had static sites on shared hosting.
Heck, my Wordpress blogs are faster than when I had static sites on shared hosting.
some reasons i can think of:
1) it's more fun
2) it's good practice as a programmer
3) you get complete control over what content is generated (i.e. can minimize CSS/JS size)
4) you get complete customization - you can make your own way to template things that is convenient for you, or auto-import a particular file format you like to keep for your notes on disk, etc
5) you don't have to learn how to use wordpress
(It's not to say I think using wordpress is bad - if you like it, use it!)
1) it's more fun
2) it's good practice as a programmer
3) you get complete control over what content is generated (i.e. can minimize CSS/JS size)
4) you get complete customization - you can make your own way to template things that is convenient for you, or auto-import a particular file format you like to keep for your notes on disk, etc
5) you don't have to learn how to use wordpress
(It's not to say I think using wordpress is bad - if you like it, use it!)
I think it's the same reason as Gatsby:
> you add your name, a bio, some links, and Gatsby does the rest.
>
> But that comes at a cost. And that cost was made clear by me hunting the favicon file
> you add your name, a bio, some links, and Gatsby does the rest.
>
> But that comes at a cost. And that cost was made clear by me hunting the favicon file
I have been burnt many times by wordpress. Updates that fail and hose everything, continual hacks because you can't update, then automated updates that worked until they didn't, obscure PHP errors from oddly configured hosts, dodgy plugins that people add that get them hacked even if they are updated to the newest version of wordpress.
It is great for non-technical people, but the risks are high.
I personally find that github pages is a better alternative now: most users can handle doing edits in github's web UI, and on commit the changes are auto-deployed to the live site and appear within 60 seconds or so. And it helps me to see their git history when they screw something up.
It is great for non-technical people, but the risks are high.
I personally find that github pages is a better alternative now: most users can handle doing edits in github's web UI, and on commit the changes are auto-deployed to the live site and appear within 60 seconds or so. And it helps me to see their git history when they screw something up.
[deleted]
Agreed.
I have a series of content websites, and at first I used Jekyll and it was fast to load, but everything took 10x longer to do than just using WordPress.
I now use WordPress on a VPS and served with Litespeed Enterprise and the performance (read: load times and CWV/GMetrix scores) is very very good - better than static sites hosted on shared hosting, in-fact.
I have a series of content websites, and at first I used Jekyll and it was fast to load, but everything took 10x longer to do than just using WordPress.
I now use WordPress on a VPS and served with Litespeed Enterprise and the performance (read: load times and CWV/GMetrix scores) is very very good - better than static sites hosted on shared hosting, in-fact.
A static site generator I've been enjoying lately (and using for my blog) is Metalsmith: https://metalsmith.io/
It feel like it's the best of both worlds, because it's simple to learn and customize, but there are plugins for the things you don't want to spend time writing yourself. Note: it is Node-based, so only useful if you're comfortable with JavaScript.
For example, I'm using plugins to: check for broken links, generate an RSS feed, and run a test server with automatic reloading.
But then I was able to easily add in my own code to handle relative links, generate Graphviz diagrams, and format dates.
One other recommendation: I hated almost every template language I ran across (Hugo's, Liquid, Nunjucks, EJS), but I'm thrilled with the simplicity of Handlebars (https://handlebarsjs.com/), although it is a bit limiting and the "block helper with parameters" syntax is strange (perhaps an indicator that I'm trying to do too much in the templating language!).
It feel like it's the best of both worlds, because it's simple to learn and customize, but there are plugins for the things you don't want to spend time writing yourself. Note: it is Node-based, so only useful if you're comfortable with JavaScript.
For example, I'm using plugins to: check for broken links, generate an RSS feed, and run a test server with automatic reloading.
But then I was able to easily add in my own code to handle relative links, generate Graphviz diagrams, and format dates.
One other recommendation: I hated almost every template language I ran across (Hugo's, Liquid, Nunjucks, EJS), but I'm thrilled with the simplicity of Handlebars (https://handlebarsjs.com/), although it is a bit limiting and the "block helper with parameters" syntax is strange (perhaps an indicator that I'm trying to do too much in the templating language!).
Nicely done. Pico.css is a cool idea I hadn't seen before.
I have built 2 SSG's over the years, once in 2009 and one this year. So it's fun to read through someone's internal thought process on their motivations and decisions.
Someone put together this mega list of 460 SSGs that I found helpful for inspiration and learning: https://staticsitegenerators.net/. Also would be a good place to add Teeny, though not sure if they are still updating the actual website.
I have built 2 SSG's over the years, once in 2009 and one this year. So it's fun to read through someone's internal thought process on their motivations and decisions.
Someone put together this mega list of 460 SSGs that I found helpful for inspiration and learning: https://staticsitegenerators.net/. Also would be a good place to add Teeny, though not sure if they are still updating the actual website.
Not fond of Pico.css’s weight, though: over 50KB, nowhere near as lightweight as the name suggests (even if it’s above-average compressible, 8KB gzipped—but I wouldn’t count even 8KB uncompressed as pico); in this case, if you flatten the variables and strip unused code, you’re left with under 4KB (~1.4KB gzipped). Lots of bloat from unused light mode support, things like form controls, and a fair bit of frivolous custom properties usage. This is the sort of place where I see the appeal of the likes of Tailwind, because they generate such huge amounts of CSS that you just about have to use an unused style remover. But it is another build step, and contrary to the deliberate intent here.
Yes it is quite cool, I also wasn't aware of it.
I guess I finally found out the theme I have been searching for.
I guess I finally found out the theme I have been searching for.
Whether or not this would suit your own needs or you would rather use Jekyll etc., these sorts of things are great exercises and experience for devs.
Use your own favourite language etc. but I wonder how many people who call themselves devs would be able to do something equivalent in a few days, considering all of the little gotchas with parsing, performance, flexibility etc.
Maybe this sort of thing would be better than a normal FANG interview where they just want to see how you would actually get something done?
Use your own favourite language etc. but I wonder how many people who call themselves devs would be able to do something equivalent in a few days, considering all of the little gotchas with parsing, performance, flexibility etc.
Maybe this sort of thing would be better than a normal FANG interview where they just want to see how you would actually get something done?
20 years ago I built my own SSG. There weren't as many back then. :) I even built my own RSS2 generator - https://pypi.org/project/PyRSS2Gen/ .
It was great when I started. I did some teaching back then and put my lectures in its own section, which I could re-build and serve to the local network for my students.
I no longer know how it works. I don't care to maintain it. It needs big changes to handle something like embedding a Jupyter notebook. And it depends on Python 2.6(!).
With hundreds of pages, and its own custom URL layout that I don't want to break, I dread migrating to a modern system.
It was great when I started. I did some teaching back then and put my lectures in its own section, which I could re-build and serve to the local network for my students.
I no longer know how it works. I don't care to maintain it. It needs big changes to handle something like embedding a Jupyter notebook. And it depends on Python 2.6(!).
With hundreds of pages, and its own custom URL layout that I don't want to break, I dread migrating to a modern system.
I felt in love with building static websites last year too.
Thanks to a custom build with kotlinxhtml and a bunch of other tools, I'm very efficient. High performance thanks to simple html+css and a little vanilla js, so the pages show up instantly with 38k+ monthly visitors on a low-spec cheap server. No background loading or rendering in js or whatever.
Thanks to a custom build with kotlinxhtml and a bunch of other tools, I'm very efficient. High performance thanks to simple html+css and a little vanilla js, so the pages show up instantly with 38k+ monthly visitors on a low-spec cheap server. No background loading or rendering in js or whatever.
I have taken a different route [1]. Started to work on a desktop app for creating static sites. It features a block/frame based editor, works fully offline (except deployment of course). It should specifically target non-technical users.
[1] https://www.project-daily.com/pages/an-experiment_1065.html
[1] https://www.project-daily.com/pages/an-experiment_1065.html
Interested. I have a few decidedly "non-technical users" in mind. Any way to keep updated on the project?
Message me at "h e l l o AT project - daily DOT com". Remove the spaces etc. I will try to keep you updated.
I am also planning on generating an RSS feed from the app itself. Once this works, you can subscribe that.
That's quite the excessive obfuscation considering the generic local part that spammers will surely try anyway.
I'm in this situation now. I have a mostly complete personal site/blog written with Nuxt. It's a Vue based SSG. Works well but overall I don't actually like Nuxt as it imposes some awful conventions that you "can" get around but what's the point?
The JS configuration file is a dumping ground of modules and objects that aren't even consistent with themselves and now Nuxt 3 is out and within a matter of hours had 100 bugs reported on Github.
All I planned on was a basic markdown blog with some interactive Vue components for things like diagrams.
Little bit tired of Node based SSG's so I looked at the .NET options (my prefered stack). There used to be one called Wyam that rebranded to Statiq and now you need to actually buy a license for (typical .NET shenanigans).
I ruled out Hugo and Jekyll because their template languages are certainly less ideal. From what I saw it was common in both to have starting blocks in one file and the ending of the block in another. Basically one file would have <body> and then another random file would have </body> in it, what a mess!
So it's either back to Node based SSGs or write one in .NET (I once did start that, a bunch of markdown files would be processed with a markdown library and then passed to the AngleSharp library to generate the HTML).
https://astro.build/ is next on my list and seems promising so far.
Overall, despite there possibly being thousands of SSG's none of them actually seem to please a majority of developers. I think that's unique, because for problem xyz there's usually maybe a top 3 or 5 hyped up popular options but SSG's are a wild west.
The JS configuration file is a dumping ground of modules and objects that aren't even consistent with themselves and now Nuxt 3 is out and within a matter of hours had 100 bugs reported on Github.
All I planned on was a basic markdown blog with some interactive Vue components for things like diagrams.
Little bit tired of Node based SSG's so I looked at the .NET options (my prefered stack). There used to be one called Wyam that rebranded to Statiq and now you need to actually buy a license for (typical .NET shenanigans).
I ruled out Hugo and Jekyll because their template languages are certainly less ideal. From what I saw it was common in both to have starting blocks in one file and the ending of the block in another. Basically one file would have <body> and then another random file would have </body> in it, what a mess!
So it's either back to Node based SSGs or write one in .NET (I once did start that, a bunch of markdown files would be processed with a markdown library and then passed to the AngleSharp library to generate the HTML).
https://astro.build/ is next on my list and seems promising so far.
Overall, despite there possibly being thousands of SSG's none of them actually seem to please a majority of developers. I think that's unique, because for problem xyz there's usually maybe a top 3 or 5 hyped up popular options but SSG's are a wild west.
I think it's a mix of the convenience factor being low enough* that it mostly appeal to technical people, and the complexity factor also being low enough that a lot of said technical people think they can do it in a week-end (I did my first prototype in 2 or 3 evenings) or two.
You can start simple with MAKEFILEs, perl scripts, pandoc and other basic/builtin unix scripts etc... and go up to build a full SSG site in Node or Ruby / Python etc... with a million dependencies if you wish to.
*: every time you want to publish something you have to run a command , wait and push the output to a webhost configured properly, as opposed to installing something once and writing in a webform and your words appear on the site.
You can start simple with MAKEFILEs, perl scripts, pandoc and other basic/builtin unix scripts etc... and go up to build a full SSG site in Node or Ruby / Python etc... with a million dependencies if you wish to.
*: every time you want to publish something you have to run a command , wait and push the output to a webhost configured properly, as opposed to installing something once and writing in a webform and your words appear on the site.
"This was nice, but I lost the flexibility I would have wanted to customize the pages a bit - GitHub let's you pick a theme and that's that."
You can actually make your own themes with github pages
You can actually make your own themes with github pages
Life isn't complete until one's made their own static site generator! I had to make two directory websites earlier this year and that exercise turned into a static directory site generator - https://github.com/knadh/dirmaker
It's the new "make your own framework".
I had my own static site generator. A bunch of PHP and Shell scripts, but I moved everything to 11ty a few years ago and haven’t looked back. If you haven’t tried it, check it out.
https://www.11ty.dev/
What I like about 11ty is that it comes with several template languages out of the box and you can pick whatever you want. You can also mix several languages.
Or you can run it in a bare-bones minimal version. I guess it just fits my mental model.
Furthermore, it doesn’t have constant updates. The API is quite stable (although 1.0 will be released soon, which requires some manual work). But I haven’t had to change a thing in a couple years.
Not affiliated, just happy with it.
https://www.11ty.dev/
What I like about 11ty is that it comes with several template languages out of the box and you can pick whatever you want. You can also mix several languages.
Or you can run it in a bare-bones minimal version. I guess it just fits my mental model.
Furthermore, it doesn’t have constant updates. The API is quite stable (although 1.0 will be released soon, which requires some manual work). But I haven’t had to change a thing in a couple years.
Not affiliated, just happy with it.
I "built" a static site generator because it was easier than learning to configure someone else's. It's basically a hundred or so lines of nodejs and a bunch of calls to pandoc.
I do not know if where you host your website, but if you have to upload it to a hosting provider, it is nice to have an upload folder that contains only the files that have changed (or regenerate the files that have changed).
For my personal website, in plain HTML, I have a syntax/link check program that places the new files in an ftp folder.
For another website that is generated with javascript en node.js, I use a script to copy the generated files to a certain folder if they have changed.
> <!-- template: blog -->
Many Markdown utilities support front matter, which is designed to solve exactly this problem.
Many Markdown utilities support front matter, which is designed to solve exactly this problem.
---
template: blog
other-key: other-value
---Why I'll never build another static site generator:
- because I've done it already and I haven't gained anything from it other than feeding my ego
- it makes me work on keeping it updated to "my custom needs" more than I work on the actual project that needs it
- it always gets outdated really fast, esp if it uses js a lot
- I've learned that it's generally a waste of time, time better spent on other areas of your business and existing tools are good enough
- because I've done it already and I haven't gained anything from it other than feeding my ego
- it makes me work on keeping it updated to "my custom needs" more than I work on the actual project that needs it
- it always gets outdated really fast, esp if it uses js a lot
- I've learned that it's generally a waste of time, time better spent on other areas of your business and existing tools are good enough
The idea of a static site generator becoming outdated fast is utterly alien to me: it's a freaking compiler, text in, HTML & CSS out. Unless you sit on a seriously unstable set of dependencies, the whole thing should be pretty stable. I haven't changed my own generator in years. Also, what do you need JavaScript for?
The other points I won't deny, though I sure liked feeding my ego.
The other points I won't deny, though I sure liked feeding my ego.
In fact, stability is one of the reasons why I use my own static site generator - nothing changes unless I want it to.
It better to generate single-purpose tools, which can be reused, instead of single-use static generator, which cannot be reused.
> it always gets outdated really fast, esp if it uses js a lot
Think you worded that incorrectly. It should be
> it always gets outdated really fast if it uses js a lot
I agree with that point. I wouldn't write a static site generator in JS for that reason.
Think you worded that incorrectly. It should be
> it always gets outdated really fast if it uses js a lot
I agree with that point. I wouldn't write a static site generator in JS for that reason.
JS is stable. More stable than most other languages. If you have reservations about NodeJS and the precarious NPM ecosystem, then say that. But equating JS with NodeJS and its community's dubious practices just exacerbates the problem.
Many people equate programming languages with their ecosystem. That’s how you get people claiming that $newlang is so much worse than $oldlang, because it has no tools, no libraries, the compiler generates slow code, there is no community, and you can’t get commercial support.
That may be true, but that doesn’t say which language is better.
That may be true, but that doesn’t say which language is better.
[deleted]
I haven't stumbled upon pico.css. I'll definitely check it out. It seems that it looks quite interesting to tinker with its functionalities.
I've made a couple. The current incarnation is two nodejs files that fetch markdown from a database and lay them out using some javascript string templates.
Jekyll sites tend to be lovingly configured but then rarely updated, I've found. I'm simply happy when I don't have to visit the abomination of medium.com frankly.
Jekyll sites tend to be lovingly configured but then rarely updated, I've found. I'm simply happy when I don't have to visit the abomination of medium.com frankly.
I miss the days when Blogger was just a half decent static site generator that uploaded to any FTP service. When they discontinued it, I rewrote my site as a pretty basic custom php/mysql app. It’s been that way since around 2008. I don’t mind the occasional maintenance but static is a little appealing.
I've made my own (in a few incarnations) for my own website. I should do a writeup some day, I made my own Make and everything. I figure I'm at about 2 posts per technological revision, but given that's sort of why it's there I'm fine with it.
The two things I really want from a SSG for my blog are the ability to avoid indexing posts by dates and the ability to link from md files to other md or image files in the same directory. I’ve tried maybe 8 or so of the most popular options and haven’t found this.
I also wanted the ability to handle relative links between Markdown files (and relative links for images). I'm surprised this isn't a default feature of nearly every static site generator, honestly.
Fortunately, some of the extensible static site generators make this fairly easy to add as a feature. Here's an example for Eleventy (aka 11ty):
https://github.com/11ty/eleventy/discussions/1973#discussion...
Fortunately, some of the extensible static site generators make this fairly easy to add as a feature. Here's an example for Eleventy (aka 11ty):
https://github.com/11ty/eleventy/discussions/1973#discussion...
[deleted]
I've done this too, but what I e learned is that many libraries have really inflexible APIs or are written to only handle very basic cases. Like, if your parser builds an AST internally, would it kill library devs to expose that AST or the functions that manipulate it? It's not like that's never a thing, but it amazes me how common it is for library code to be written like developers will never want different behavior. This is what has made writing things like static site generators more time consuming for me than it should be.
This is how Pelican works https://docs.getpelican.com/en/latest/index.html
Pelican is very underrated.
Nice job :)
I don't completely agree about Jekyll (it can be very light weight, requiring zero Ruby unless you need to extend things), but rolling your own solution for a personal home page is always nice.
I don't completely agree about Jekyll (it can be very light weight, requiring zero Ruby unless you need to extend things), but rolling your own solution for a personal home page is always nice.
I have a PHP/Symfony project boilerplate that I use for all of my projects and I added static site generating to that boilerplate. That allows me to make a static site and then easily switch from static to dynamic if I need to. The only thing I need to change to make the switch is my CI configuration. It has already come in handy on a couple of projects and it doesn't require any special maintenance since I'm just storing the output of my dynamic app.
Didn't see anyone mention Pandoc in the comments so far... https://pandoc.org
Pandoc plus jinja2 to generate its markdown input makes for a really simple yet very flexible system.
My approach to static site generation these days is to use Parcel Bundler. (Note that V2 has come out, but most of my experience with V1, so YMMV.)
It’s a little bit of a strange tool, but you can start by pointing it at an HTML file, and it will automatically build it, bundling and minifying any dependent resources and giving them a hashed filename for better caching.
If you want to do multiple pages, it’s simple; you can just link them. Parcel Bundler will pull the links and bundle them just like the first page, recursively. When it generates linked pages, it won’t make a hashed filename, so your directory structure will be left in-tact. If you want nice subdir pages, you can put index.html files into subdirectories, and voila. And as a bonus, any resources you depend on from two different pages will share the same bundled resource, as you would probably hope.
But HTML can get repetitive, so you probably want templating of some sort. For that, I tend to rely on Pug templates. They support blocks and template inheritance, so now you can do more advanced stuff without having to repeat yourself constantly.
Finally, if you wanted to use TypeScript or SCSS, you just, can. They will be compiled and bundled to JS and CSS transparently, exactly like you would probably hope.
And then maybe you want to do something more interesting than what it can do out of the box. Like for example, maybe you want to render Markdown files into a template (obviously relevant to this use case.) In that case, you can extend Parcel. My favorite shameless plug is a documentation site I have set up for a reverse engineering project which uses Parcel to render Markdown and Kaitai Struct files into templates which are interlinked with each-other. The resulting site is fully static and the build process is relatively quick. I don’t know of any cleaner way to do something like this!
https://packets.pangdox.com/
The biggest downside of Parcel is that I did, in fact, need a custom plugin to render Markdown files directly into templates. Maybe there’s a simpler way or a plugin on NPM that serves this relatively common use case. But I just love having the page graph intertwined with the asset graph like this; it’s super powerful for building fully static websites. The only thing it feels weak for is if you want to generate pages from data somehow; Parcel is pretty tethered to pages being an asset, so as far as I know you can’t simply synthesize them. Still, despite this and other quirks, I really do enjoy the experience.
I've written my own static site generators before, too, and with all static site generators pretty much, I’ve felt unsatisfied with how they interacted with bundlers and compilers.
It’s a little bit of a strange tool, but you can start by pointing it at an HTML file, and it will automatically build it, bundling and minifying any dependent resources and giving them a hashed filename for better caching.
If you want to do multiple pages, it’s simple; you can just link them. Parcel Bundler will pull the links and bundle them just like the first page, recursively. When it generates linked pages, it won’t make a hashed filename, so your directory structure will be left in-tact. If you want nice subdir pages, you can put index.html files into subdirectories, and voila. And as a bonus, any resources you depend on from two different pages will share the same bundled resource, as you would probably hope.
But HTML can get repetitive, so you probably want templating of some sort. For that, I tend to rely on Pug templates. They support blocks and template inheritance, so now you can do more advanced stuff without having to repeat yourself constantly.
Finally, if you wanted to use TypeScript or SCSS, you just, can. They will be compiled and bundled to JS and CSS transparently, exactly like you would probably hope.
And then maybe you want to do something more interesting than what it can do out of the box. Like for example, maybe you want to render Markdown files into a template (obviously relevant to this use case.) In that case, you can extend Parcel. My favorite shameless plug is a documentation site I have set up for a reverse engineering project which uses Parcel to render Markdown and Kaitai Struct files into templates which are interlinked with each-other. The resulting site is fully static and the build process is relatively quick. I don’t know of any cleaner way to do something like this!
https://packets.pangdox.com/
The biggest downside of Parcel is that I did, in fact, need a custom plugin to render Markdown files directly into templates. Maybe there’s a simpler way or a plugin on NPM that serves this relatively common use case. But I just love having the page graph intertwined with the asset graph like this; it’s super powerful for building fully static websites. The only thing it feels weak for is if you want to generate pages from data somehow; Parcel is pretty tethered to pages being an asset, so as far as I know you can’t simply synthesize them. Still, despite this and other quirks, I really do enjoy the experience.
I've written my own static site generators before, too, and with all static site generators pretty much, I’ve felt unsatisfied with how they interacted with bundlers and compilers.
[deleted]
The comments here made me realize that building your own SSG probably is an excellent challenge to learn a new programming language. Thanks for the inspiration. I think I'll try this with golang and/or rust one day.
While we're all sharing, here's mine:
https://git.sr.ht/~evan-hoose/SSSSS
Is it garbage? Yes. But it's my garbage, and does what I need it to!
https://git.sr.ht/~evan-hoose/SSSSS
Is it garbage? Yes. But it's my garbage, and does what I need it to!
[deleted]
[deleted]
When you use Nanoc, it's like building your own with a nice set of tools.
https://nanoc.app/
https://nanoc.app/
This one is mine https://mkws.sh/, super simple, shell based.
Something I'm trying to optimize is time from idea to first word on the essay. The more time the less likely im going to write...
Now I am wondering why anyone would use an existing static website generator. Everyone should write their own.
I was about to that myself this weekend, you just saved me few hours, I'll start using it right away :)
will recommend water.css over picocss
I feel like this is a design flaw: https://github.com/picocss/pico/issues/13
I feel like this is a design flaw: https://github.com/picocss/pico/issues/13
That is informative and inspiring. Thank you for having shared your initiative.
Wonder should it mention it is on GitHub. Is it true that and whilst one can a few js for dynamic contents sort of, by and large it is a constraint to static as no real db update etc.
You don't have to be on the Node treadmill to create a static site generator. You can use something stable!