explaining static site generators

most personal websites have some level of consistency to its design from page to page. for example, you might have a navigation bar. this navigation bar links to "home", "about", "links", and "contact" pages. on all of these pages, the navigation bar is visible so you can easily click between each page.

there are few personal websites where every page has a completely different layout and style. (they do exist, though - check out transgender.money for example.) in fact, many websites follow a very specific, consistent format: every page is about the exact same, except for the "main content" of the page!

however, if you're hand-coding a website, it can be hard to replicate changes to the structure of your page to all pages, especially as it grows bigger. if you add a new link to the navigation bar, for example, you'll have to add it to the home page... and the about page... and the links page... and so on.

needless to say, it'll get harder to maintain this website the bigger it grows - for example, if you use a weblog to document your thoughts or a large gallery that needs to be split into multiple pages.

(detour: i hate the word "content" but im not sure what else id use here)

let's think of everything that isn't the content as the "template". your template is largely consistent across pages. what if instead of updating every page individually when you update your template, you keep a single "template" file, and have one "content" file for every page on your website? then, you use a script to take every content file, wrap it in your template, and then output a fully-usable .html file?

a static site generator does this for you. this is nice because if you update the single template file, it'll affect all pages when compiled (all pages converted from content files to final html files.) also, SSGs in general are good for reusing code in general in a nice way. notice how i posted four "example" layouts in a row up there? this was accomplished using a nunjucks macro.

very recently, i took the time to completely revamp the visual theme of PORTFIEND. you can see screenshots of old themes at this article, "pivoting the site design in a new direction". PORTFIEND also has at least 34 pages at this point. can you imagine if i had to update every single page by hand to fit the new theme? the reason i didn't have to was because of my static site generator.

okay, if you just wanted an explanation of SSGs, you can stop right here. the rest of this post gets a little technical about the actual usage of a SSG.

SSGs vs. hand-coding?

many of PORTFIEND's readers do not have a personal website; if that's you, you might be thinking, "i don't know what any of this stuff means" when i think you should probably be thinking "damn, that makes web development sound SO much easier! how do i start?"

believe it or not, there are cases where hand-coding may be more appealing than a static site generator (but in my humble opinion, the SSG is a pretty sweet deal.) using a SSG is a different workflow than hand-coding, and there's a lot more skills you have to learn to use a SSG. they're pretty simple skills, but if you're already struggling to learn html and CSS, maybe learning:

• git (for source file hosting and its "actions" workflow)
• github actions (to remotely update your website)
• api tokens (for neocities)
• SSH, keypair authentication (for remote web server instead of neocities)
• a templating language that may or may not require knowledge of HTML
• command line NPM (for creating the project in your SSG of choice)
• maybe a little bit of javascript (to customize your SSG of choice better)
• the SSG itself (things like data cascade, to take advantage of its advanced features)

...all of this might be a bit much on your plate. in this case, i would recommend hand-coding a simple website, and considering switching to a SSG later. (this is what i did!)

though i'd like to emphasize again, all of these skills are pretty easy. you could probably use a cheat sheet. i could probably make a cheat sheet. remind me sometime.

however, if you've got a decent grasp on html and css, or at least you feel comfortable using it, maybe a SSG isn't so bad to jump into! let me compare the two.

hand-coding

• skills needed: HTML, CSS
• tools needed: a text editor
• work directly with HTML and CSS
• "final" page is 1-to-1 with source
• can edit the website directly on your web host (e.g. neocities.org)
• bare minimum web dev skills
• updating template gets more tedious the bigger your site is
• i find it clunky at bigger site sizes

static site generator

• skills needed: HTML, CSS, content/templating language of choice, basic NPM commands, your SSG of choice
• tools needed: command line, a text editor, NPM
• skills recommended: basic javascript
• work with CSS, as well as HTML and/or a templating language
• templating language gets converted to HTML
• a steeper learning curve
• updating template will always be easy
• better scalability

however, static site generation generally also means moving to a "remote updating" workflow - meaning you develop the website on your own computer, and then upload the "final" files to your server somehow. this is in contrast to hand-coding, which allows you the option to edit the files on the server directly. (but you can use a remote updating workflow on hand-coding too!)

what does updating my website look like, then?

direct updating

• skills needed: none except the ones you use to make the html files
• tools needed: generally the web host provides its own text editor
• go to your website host
• edit the page
• save it
• uses the web host's text editor instead of your own (possible downside)
• so easy

file uploading

• skills needed: ditto
• tools needed: text editor
• allows you to work on your website on your computer, then update it when it's "ready"
• upload the files onto your web host
• downside: neocities uploading fucking sucks sometimes

remote updating

• skills needed: Git, basic GitHub Actions
  • SSH and keypair authentication (potentially but unlikely, only if youre not using neocitie)
• tools needed: GitHub Desktop (maybe), a GitHub account
• allows you to work on your website on your computer, then update it when it's "ready"
• upload your SSG "source" files to a repository
• use a GitHub Action to compile and sync the files to your host
  • this action is a copy-paste but you substitute your own values
  • also you only need to save the action once, it will execute automatically
• every single website update you make from now on involves using Git
  • (if you try to direct update, it will get overwritten if it's not on your git repo)
• you may never have to look at your website host's files directly, you just git commit

what does this workflow look like?

tldr

• make MD file
• commit it to github
• that's it

long explanation

let me use this website as an example:

i have a folder in my computer for PORTFIEND. it is an Eleventy project file (a pretty simple and easy-to-use SSG). it is also linked to a private GitHub repository.

when i want to update PORTFIEND, i open the project in Visual Studio Code and run eleventy --serve. this creates a "live server", which allows me to preview my changes at localhost:8080 in my browser. every time i save a file, it will automatically update the website at this server, and refresh any open pages on the server.

for my content files, i use Markdown. the syntax looks very similar to Discord messages. i'm writing this page in Markdown right now. (i also have Nunjucks loaded as Markdown's templating language, so I can embed HTML and Nunjucks formatting into Markdown files. a little bit cursed.)

for my template files, i use Nunjucks. it is literally just HTML with a few special tags added. those tags allow for filling in and substituting values from other places. for example, the {{content | safe }} tag gets replaced with this MD file.

when i'm done with the page, i will crack open GitHub Desktop, make sure the page file is checked, """write""" a quick "commit message", and then commit it to the repository. then i push the change to GitHub. keep in mind that only the source files are pushed to GitHub; the public files, which are auto-generated by the Eleventy server, are not pushed.

whenever GitHub detects a change in the main branch of my repository, it will immediately execute the GitHub Action. this action runs eleventy, which will do a one-time compile of all source files.

then, because i use a web server (and not Neocities,) the GitHub Action will load a SSH Key from the repository and use it to authenticate with my web host. then the Action synchronizes the newly-compiled files to my web host.

this Action takes about ten seconds in total to a) create an entirely new page on my web server, and b) update every single page on the site to accommodate for this change. the new page, most likely, will be at the top of the "Recently Updated" navigation box, and that box gets updated on all 30+ pages of PORTFIEND. (it also ends up on the Sitemap.)

remember, this whole GitHub Action, that is the actual process of updating portfiend.quest, happened completely automatically! i don't have to open my browser to upload or change the files on the web server. in fact, i don't even have to run Eleventy. if i wanted, i could make a change to a .md file and just git commit it. this actually makes it much faster to make minor site updates compared to direct editing!

final thoughts

i uh. i'll make a follow-up real guide eventually.

it never gets easier to end really long blog posts. LOL!