24 ms·

Why I built my own static site generator

168 points by yakkomajuri 5y ago

tarkin2 5y ago
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.
tbmatuka 5y ago
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.
fjfaase 5y ago
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.
- account42 5y ago
  rsync is the tool to know for copying trees of files where most are unchanged.
  - fjfaase 5y ago
    Does that also work if FTP is the only means to upload files to your hosting provider? If not, do you know of a simple FTP client that can do the same?
abdullahkhalids 5y ago
This is how Pelican works https://docs.getpelican.com/en/latest/index.html https://docs.getpelican.com/en/latest/index.html
- goodpoint 5y ago
  Pelican is very underrated.
breck 5y ago
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/ https://staticsitegenerators.net/. Also would be a good place to add Teeny, though not sure if they are still updating the actual website.
- pjmlp 5y ago
  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.
- chrismorgan 5y ago
  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.
DDR0 5y ago
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.
snicker7 5y ago
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.
- clairity 5y ago
  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.
willvarfar 5y ago
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.
- laurent92 5y ago
  Yeah, on the other hand, my pro website is based on Jekyll and it doesn’t compile anymore because of version shenanigans…
  - willvarfar 5y ago
    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...
    - Santosh83 5y ago
      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.
system2 5y ago
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.
- amatecha 5y ago
  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 5y ago
    [deleted]
- rhn_mk1 5y ago
  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
- dack 5y ago
  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!)
- deleted 5y ago
  [deleted]
- holoduke 5y ago
  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.
adriangrigore 5y ago
This one is mine https://mkws.sh/ https://mkws.sh/, super simple, shell based.
dalke 5y ago
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/ 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.
jchw 5y ago
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/ 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.
cozzyd 5y ago
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)
- deaddabe 5y ago
  What $(BUILDER) are you using? Could be GNU m4 (been there, done that) or something more (or less?) evolved.
  - cozzyd 5y ago
    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).
- Tomte 5y ago
  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.
  - cozzyd 5y ago
    Indeed, but that's overkill for most personal sites...
    - onion2k 5y ago
oscarcp 5y ago
I was about to that myself this weekend, you just saved me few hours, I'll start using it right away :)
rawoke083600 5y ago
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) find -type f | egrep "html|js" | xargs sed -Ei s/"rcc=([0-9]+)"/rcc=$RANDOM/g 3) ssh-copy over to server 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.
- smackeyacky 5y ago
  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.
- BillinghamJ 5y ago
  Perhaps you'd like to package your preprocessor into something to make Personal Home Pages...
tristanperry 5y ago
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.
Shared404 5y ago
While we're all sharing, here's mine: https://git.sr.ht/~evan-hoose/SSSSS https://git.sr.ht/~evan-hoose/SSSSS Is it garbage? Yes. But it's my garbage, and does what I need it to!
Maphistow 5y ago
"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
WA 5y ago
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/ 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.
chimen 5y ago
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
- loup-vaillant 5y ago
  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.
  - account42 5y ago
    In fact, stability is one of the reasons why I use my own static site generator - nothing changes unless I want it to.
- deleted 5y ago
  [deleted]
- bachmeier 5y ago
  > 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.
  - cxr 5y ago
    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.
franciscop 5y ago
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: --- template: custom.html --- # My normal markdown Since it's a fairly standard tool, parsing it is trivial with npm packages[2] and you don't need to be manually parsing the strings: import fm from "front-matter"; const data = await fs.readFile(...); const { attributes, body } = await fm(data); // attributes: { template: "custom.html" } // body: "# My normal markdown ..." [1] https://jekyllrb.com/docs/front-matter/ https://jekyllrb.com/docs/front-matter/ [2] https://www.npmjs.com/package/front-matter https://www.npmjs.com/package/front-matter
- Zababa 5y ago
  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.
  - franciscop 5y ago
    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).
- yakkomajuri 5y ago
  Hey, thanks for pointing out the `front-matter` library. I've updated Teeny to use that instead of HTML comments.
fogof 5y ago
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.
- schemescape 5y ago
  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#discussioncomment-1344106 https://github.com/11ty/eleventy/discussions/1973#discussion...
scary-size 5y ago
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 https://www.project-daily.com/pages/an-experiment_1065.html
- Snoddas 5y ago
  Interested. I have a few decidedly "non-technical users" in mind. Any way to keep updated on the project?
  - scary-size 5y ago
    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.
    - account42 5y ago
      That's quite the excessive obfuscation considering the generic local part that spammers will surely try anyway.
begueradj 5y ago
That is informative and inspiring. Thank you for having shared your initiative.
skinnyasianboi 5y ago
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.
deleted 5y ago
[deleted]
nathell 5y ago
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 https://github.com/nathell/nhp/blob/master/src/nhp/poems.clj
ngcc_hk 5y ago
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.
nico_h 5y ago
I have an 84 line bash script that abuses find, sed and multimarkdown to generate a website with a blog, static pages, navigation and rss feed for the blog. The index page has a header and the last 5 blog entries ((Navigation between the blog entries is plain old basic javascript).(https://github.com/nicolasH/frankensteins https://github.com/nicolasH/frankensteins) You don't have to be on the Node treadmill to create a static site generator. You can use something stable!
- wheybags 5y ago
  Mine is similar, but I use the C preprocessor for templating (you can run it independently, by running `cpp`)
  - cabalamat 5y ago
    I once built a website using the M4 preprocessor. (I wouldn't recommend it.)
    - wheybags 5y ago
      cpp is barely passable, I wouldn't dream of even trying m4 :v
- nico_h 5y ago
  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.
- spaniard89277 5y ago
  I just use PicoCMS and I forget about it. Just upload markdown files, that's about it.
- Zababa 5y ago
  > 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.
donatj 5y ago
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.
petepete 5y ago
When you use Nanoc, it's like building your own with a nice set of tools. https://nanoc.app/ https://nanoc.app/
Ultimatt 5y ago
Didn't see anyone mention Pandoc in the comments so far... https://pandoc.org https://pandoc.org
- quink 5y ago
  Pandoc plus jinja2 to generate its markdown input makes for a really simple yet very flexible system.
cabalamat 5y ago
>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.
lbriner 5y ago
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?
marginalia_nu 5y ago
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.
alias_neo 5y ago
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/ https://gohugo.io/
- schemescape 5y ago
  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.
- Semiapies 5y ago
  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.
pembrook 5y ago
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.
- marginalia_nu 5y ago
  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.
  - pembrook 5y ago
    > 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."
schwartzworld 5y ago
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.
lloydatkinson 5y ago
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/ 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.
- nico_h 5y ago
  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.
deleted 5y ago
[deleted]
knadh 5y ago
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 https://github.com/knadh/dirmaker
- hk1337 5y ago
  It's the new "make your own framework".
haroman 5y ago
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.
deleted 5y ago
[deleted]
aazaa 5y ago
>  Many Markdown utilities support front matter, which is designed to solve exactly this problem. --- template: blog other-key: other-value ---
ravenstine 5y ago
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.
z3t4 5y ago
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...
schemescape 5y ago
A static site generator I've been enjoying lately (and using for my blog) is Metalsmith: https://metalsmith.io/ 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/ 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!).
deleted 5y ago
[deleted]
_def 5y ago
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.
archibaldJ 5y ago
will recommend water.css over picocss I feel like this is a design flaw: https://github.com/picocss/pico/issues/13 https://github.com/picocss/pico/issues/13
TedHerman 5y ago
Now I am wondering why anyone would use an existing static website generator. Everyone should write their own.

168 points by yakkomajuri 5y ago

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.

tbmatuka 5y ago

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.

fjfaase 5y ago

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.

account42 5y ago
rsync is the tool to know for copying trees of files where most are unchanged.
- fjfaase 5y ago
  Does that also work if FTP is the only means to upload files to your hosting provider? If not, do you know of a simple FTP client that can do the same?

abdullahkhalids 5y ago

This is how Pelican works https://docs.getpelican.com/en/latest/index.html https://docs.getpelican.com/en/latest/index.html

goodpoint 5y ago
Pelican is very underrated.

breck 5y ago

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/ https://staticsitegenerators.net/. Also would be a good place to add Teeny, though not sure if they are still updating the actual website.

pjmlp 5y ago
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.
chrismorgan 5y ago
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.

DDR0 5y ago

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.

snicker7 5y ago

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.

clairity 5y ago
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.

willvarfar 5y ago

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.

laurent92 5y ago
Yeah, on the other hand, my pro website is based on Jekyll and it doesn’t compile anymore because of version shenanigans…
- willvarfar 5y ago
  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...
  - Santosh83 5y ago
    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.

system2 5y ago

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.

amatecha 5y ago
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 5y ago
  [deleted]
rhn_mk1 5y ago
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
dack 5y ago
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!)
deleted 5y ago
[deleted]
holoduke 5y ago
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.

adriangrigore 5y ago

This one is mine https://mkws.sh/ https://mkws.sh/, super simple, shell based.

dalke 5y ago

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/ 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.

jchw 5y ago

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/ 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.

cozzyd 5y ago

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)

deaddabe 5y ago
What $(BUILDER) are you using? Could be GNU m4 (been there, done that) or something more (or less?) evolved.
- cozzyd 5y ago
  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).
Tomte 5y ago
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.
- cozzyd 5y ago
  Indeed, but that's overkill for most personal sites...
  - onion2k 5y ago

oscarcp 5y ago

I was about to that myself this weekend, you just saved me few hours, I'll start using it right away :)

rawoke083600 5y ago

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) find -type f | egrep "html|js" | xargs sed -Ei s/"rcc=([0-9]+)"/rcc=$RANDOM/g 3) ssh-copy over to server 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.

smackeyacky 5y ago
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.
BillinghamJ 5y ago
Perhaps you'd like to package your preprocessor into something to make Personal Home Pages...

tristanperry 5y ago

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.

Shared404 5y ago

While we're all sharing, here's mine: https://git.sr.ht/~evan-hoose/SSSSS https://git.sr.ht/~evan-hoose/SSSSS Is it garbage? Yes. But it's my garbage, and does what I need it to!

Maphistow 5y ago

"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

WA 5y ago

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/ 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.

chimen 5y ago

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

loup-vaillant 5y ago
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.
- account42 5y ago
  In fact, stability is one of the reasons why I use my own static site generator - nothing changes unless I want it to.
deleted 5y ago
[deleted]
bachmeier 5y ago
> 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.
- cxr 5y ago
  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.

franciscop 5y ago

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: --- template: custom.html --- # My normal markdown Since it's a fairly standard tool, parsing it is trivial with npm packages[2] and you don't need to be manually parsing the strings: import fm from "front-matter"; const data = await fs.readFile(...); const { attributes, body } = await fm(data); // attributes: { template: "custom.html" } // body: "# My normal markdown ..." [1] https://jekyllrb.com/docs/front-matter/ https://jekyllrb.com/docs/front-matter/ [2] https://www.npmjs.com/package/front-matter https://www.npmjs.com/package/front-matter

Zababa 5y ago
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.
- franciscop 5y ago
  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).
yakkomajuri 5y ago
Hey, thanks for pointing out the `front-matter` library. I've updated Teeny to use that instead of HTML comments.

fogof 5y ago

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.

schemescape 5y ago
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#discussioncomment-1344106 https://github.com/11ty/eleventy/discussions/1973#discussion...

scary-size 5y ago

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 https://www.project-daily.com/pages/an-experiment_1065.html

Snoddas 5y ago
Interested. I have a few decidedly "non-technical users" in mind. Any way to keep updated on the project?
- scary-size 5y ago
  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.
  - account42 5y ago
    That's quite the excessive obfuscation considering the generic local part that spammers will surely try anyway.

begueradj 5y ago

That is informative and inspiring. Thank you for having shared your initiative.

skinnyasianboi 5y ago

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.

deleted 5y ago

[deleted]

nathell 5y ago

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 https://github.com/nathell/nhp/blob/master/src/nhp/poems.clj

ngcc_hk 5y ago

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.

nico_h 5y ago

I have an 84 line bash script that abuses find, sed and multimarkdown to generate a website with a blog, static pages, navigation and rss feed for the blog. The index page has a header and the last 5 blog entries ((Navigation between the blog entries is plain old basic javascript).(https://github.com/nicolasH/frankensteins https://github.com/nicolasH/frankensteins) You don't have to be on the Node treadmill to create a static site generator. You can use something stable!

wheybags 5y ago
Mine is similar, but I use the C preprocessor for templating (you can run it independently, by running `cpp`)
- cabalamat 5y ago
  I once built a website using the M4 preprocessor. (I wouldn't recommend it.)
  - wheybags 5y ago
    cpp is barely passable, I wouldn't dream of even trying m4 :v
nico_h 5y ago
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.
spaniard89277 5y ago
I just use PicoCMS and I forget about it. Just upload markdown files, that's about it.
Zababa 5y ago
> 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.

donatj 5y ago

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.

petepete 5y ago

When you use Nanoc, it's like building your own with a nice set of tools. https://nanoc.app/ https://nanoc.app/

Ultimatt 5y ago

Didn't see anyone mention Pandoc in the comments so far... https://pandoc.org https://pandoc.org

quink 5y ago
Pandoc plus jinja2 to generate its markdown input makes for a really simple yet very flexible system.

cabalamat 5y ago

>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.

lbriner 5y ago

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?

marginalia_nu 5y ago

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.

alias_neo 5y ago

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/ https://gohugo.io/

schemescape 5y ago
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.
Semiapies 5y ago
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.

pembrook 5y ago

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.

marginalia_nu 5y ago
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.
- pembrook 5y ago
  > 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."

schwartzworld 5y ago

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.

lloydatkinson 5y ago

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/ 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.

nico_h 5y ago
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.

deleted 5y ago

[deleted]

knadh 5y ago

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 https://github.com/knadh/dirmaker

hk1337 5y ago
It's the new "make your own framework".

haroman 5y ago

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.

deleted 5y ago

[deleted]

aazaa 5y ago

>  Many Markdown utilities support front matter, which is designed to solve exactly this problem. --- template: blog other-key: other-value ---

ravenstine 5y ago

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.

z3t4 5y ago

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...

schemescape 5y ago

A static site generator I've been enjoying lately (and using for my blog) is Metalsmith: https://metalsmith.io/ 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/ 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!).

deleted 5y ago

[deleted]

_def 5y ago

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.

archibaldJ 5y ago

will recommend water.css over picocss I feel like this is a design flaw: https://github.com/picocss/pico/issues/13 https://github.com/picocss/pico/issues/13

TedHerman 5y ago

Now I am wondering why anyone would use an existing static website generator. Everyone should write their own.