This post took me a very long time to write, so give me money if you like the below post.
Additional resources are below the two tutorials.
I wanted to make this guide, partially so I can have something to reference myself, but also because I hope other screen reader users can get something out of this.
What are static site generators?
Wikipedia has a wonderful breakdown of static site generators, but I would also like to add that it’s kind of a cross between making static website files by hand and having a generator, well, generate or publish stuff for you.
A static site generator is kind of a mix mash of technologies. It’s combining static HTML files with themes and templates and styles.
Benefits of static site generators.
I can already hear you thinking, why would I want to use a static site generator when WordPress is accessible and because there are a lot of website publishing avenues out there that are accessible, so why should I build my own website using a static site generator and command line/Powershell?
Those are very valid points! I’d like to point out that some of these services that host websites for you already use static site generators. For example, Micro.blog uses Hugo but they host everything for you for a fee. There are others, too, that host static site generators for a fee but Micro.blog is the easiest one.
There’s a difference between the two types of websites I listed above. As of right now, people seem to lump these types of websites into two groups. Dynamic websites, which are websites that operate from a database. For example, WordPress is a dynamic website because it has to fetch that page from a database every time someone goes to a page on that website. The database has to be checked and rendered every time our browser goes to a page or a blog post on the website. Dynamic websites have templates with data that are then rendered to the user. It’s kind of like a stream that needs to be checked every time you want to go somewhere or do something.
Static sites are just the pre made files. There’s no database to check and crawl every time we want to access a page on the website. There’s no extra things clogging up the database. Your accessing that file exclusively when you go to a page on a website.
There are prose and cons for both kinds of websites. For example, dynamic websites are best if you plan to have a lot of changes happen on your website, such as adding or removing authors on a team, having interactive widgets, and more interactive things.
A static website is perfect for personal blogs, small websites without a user forum or complex payment systems or landing pages, personal diary websites, things that really don’t need to change very often. If you publish the occasional blog post or news item or update, and have mostly landing pages on your website, pages that don’t change often, then a static website would be good for you because you don’t have to make sure everything in your database is updated. You could just let those static files sit there until you want to make a change to the files.
If you need to change a category on multiple posts at once, a dynamic website solution like WordPress would be better for you because it operates via a database, so you could make changes in bulk.
Technically speaking, a static site is more secure because there’s no database to break into. There are other differences, but you really don’t need to know this in order to get going with this guide.
This guide will walk you through setting up a static website for the first time with Git and then publishing it for free on Github pages.
Prerequisites and things to know.
Unfortunately, static site generators are just not for fully non-technical people. If you’re willing to learn the basics of a few concepts, you don’t have to be a programmer to use a static site generator but they require that you know the basics of at least a few things. Mainly,
Markdown, which is a lightweight way of writing formatted text. Markdown is far easier to learn than HTML.
Powershell or basic command line commands. Static site generators are interacted with through the command line. Generally, terminals and command line interfaces are more accessible for screen reader users. This command line book on Bookshare helped me a lot, as well as this Powershell book on Bookshare.
Git concepts. Why not Github specifically? Git powers this kind of environment and is used across sites similar to Github. I’d recommend learning through the command line so you can have one interface to work with in case you want to change repository providers later. Here’s a free book on Git that’s also under a Creative Commons license, but also Using the GitHub Command Line Interface by Luke Robinett is a great introduction from a screen reader perspective.
Build Websites with Hugo by Hogan, Brian P is a fantastic introduction to Hugo, but my below post will get you started with making a blog. This book was recommended by a reader, so thank you!
Hugo in Action by Atishay Jain is another getting started resource but both I and a fellow reader thought it’s more for people that don’t mind reading about terms and jumping straight into concepts. Even so, it can really help understand some of the backbones that make up a Hugo website.
For this, we’re going to be using Github and Github pages. We’re going to set up a lot of stuff so we won’t have to do a lot of setup later.
First, make a Github account here and remember your username, because we will need that later.
It should be noted that a lot of the concepts we use in the Hugo section will also come into play in the Zola section, so it’s best if you start with building a Hugo website first before trying Zola.
First, though, Setting up our Git environment.
Installing Git and Github cli
We’re installing git and Github Cli firstso we can publish our websites to repositories and to Github pages.
First, we need to install git. Git is a thing that lets nerds store and track projects. It’s like a version of Dropbox but without the constant syncing in the background. Nerds call it a distributed version control software system , but I can’t remember how the phrase distributed version control software system transformed into git, so let’s just call it git. it’s main focus is keeping projects in repositories.
Because I’ll be writing this static site guide from the point of view of a Windows user, everything in this guide will be ran against Windows. I have absolutely no idea which commands cary over to Macs or Linux but I’ll keep the below commands as broad as I can.
The easiest way to install git on Windows is to use Microsoft’s package manager, called Winget. Get Winget here. Winget is a package manager that hooks into various repositories and fetches packaged downloads based on your OS and system build and upgrades for you, automatically, so you don’t have to browse complicated webpages.
If you don’t have Windows, download git from this page.
The easiest way to use Winget is in a command line/powershell window.
First, open powershell as an administrator.
Then, type or copy and paste the following.
winget install --id Git.Git -e
you will need to install another package manager called Chocolatey. Chocolatey is kind of like Winget but it has more repositories and even more sources. Why am I having you download two package managers? Because one program isn’t on Winget, but another isn’t on Chocolatey, but some are available on both Winget and Chocolatey. It will save you a headache when you’re trying to find something later.
For the ease of simplicity, the below lengthy code string will do three things, one after the other. It will install Chocolatey, then install git, then install Github command line version. To keep this simple, I’ll continue to bundle commands so they run back to back if needed later.
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')); winget install --id Git.Git -e; winget install -e --id GitHub.cli
Now we should connect the Git software we just downloaded to our Github account. There’s other Git providers, but we’re going to be using Github and Github pages for this, so we need to connect everything before we start building.
After all the Git software is installed, run the following command in our powershell window. It’s going to be an interactive command, so you will want to read what will come next before entering the command.
Connect our Git program with Github with the following command.
gh auth login
after you enter that command, you’ll be taken through a series of prompts. The easiest way to connect is with HTTPs, so we’re going to select the below options, in this order.
Press enter to select GitHub account.
Press enter to select HTTPS.
Press Y, to say yes to connecting it with your Github cradentials.
Press enter to authenticate with a web browser.
Powershell is going to tell you to copy a code. Press Control, A, to copy the whole terminal window up to this point. Open up notepad and paste it in. Go back to the Powershell window and hit enter.
Your web browser will open and ask you to login to Github. After logging in, it will ask you for the code. I never could get it to paste correctly when pasting from the Notepad to the box, so alt tab back and forth and just type it in manually.
Hit enter, then hit the authorize or connect button. Go back to our powershell window and hit enter to complete the connection process.
Now you should be good to go! Now we can download our static site generators!
Downloading static site generators.
Now we have to pick our static site generator we want to install. Even though this tutorial will mainly focus on Hugo and Zola, there are many fantastic generators like 11ty. Wikipedia has a good starting list of Static Site generators to check out.
You can see a whole host of static site generators here if you want to try more out later.
Even though 11ty has a very wonderful place of starter projects to bounce off, and they also have a great blog starter project and easy to read getting started guide, I still had some trouble with it. Because I wasn’t able to get 11ty working enough for this guide, our focus is going to be on Hugo and Zola. Both are different static site generators, but working with both will give you a good idea of what to expect when working with other static site generators.
First, we’ll make a website with Hugo. Then, we’ll make a website with Zola. Then, we’ll talk about publishing both websites to Github pages.
Even though this tutorial will focus on publishing to Github pages, I’ll list some other fantastic hosts you can use to publish your static site below the Github pages publishing tutorials for Hugo and Zola.
First, we’re going to download everything we need for Hugo and then install Zola. Some Hugo themes require extra stuff known as dependencies, so to avoid having to download more stuff later, we’re just going to download everything all in one command.
The below command installs stuff from Chocolatey as well as Winget. If you didn’t install Chocolatey, the below command will fail.
Just in case, the install command for Chocolatey is,
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
Now that Chocolatey is installed, copy and paste the whole command below, including the semicolons. The semicolons tell powershell to run the below command sequentially, with one command immediately following the next command.
The below commands will take time to run in order, so wait until you hear the terminal output your location.
choco install sass golang -y; winget install Hugo.Hugo.Extended; choco upgrade golang -y; winget install --id=getzola.zola -e; winget upgrade --all; Choco upgrade all -y
I included the upgrade commands because you can never be to cautious.
Now that we’ve installed the static site generators we’re going to be working with today. Let’s set up our Github repositories before we start making websites.
The reason we’re setting up repositories first is because it’s going to become a lot easier to navigate and push later. It’s also going to be far easier to manage when we start working with other static site generators.
Creating our Github repositories.
Now we’re going to make our repositories for Github. It’s best to have all back end stuff in a private repository or, in this case, repositories. The public repository we will be making will be our fully published website.
By keeping our back end stuff private, this will make it extra hard for someone to try and mess with your files. Even though our public repository will hold our rendered and published items in it, it’s still far safer than having everything under one repository.
It’s also going to be easier to publish our websites because, if only our fully rendered stuff is in our public repository, then we will only need to point Github pages to that repository and not a special folder. It’s also going to make it far easier if we want to change static site generators later but keep our website at the same URL and the same public content all in one designated repository.
For example, if we want to publish what we tried making while trying a different generator, we would just need to publish to that public repository without making a whole new repository. This will become clearer as we get to the publishing stage.
After we’re all done building with our various generators, we’re going to publish them. The websites need to be published, also known as compiled and rendered, after we finish tweaking and building privately.
So we’re going to build and test privately, but then we’re going to publish after we’re happy with our private tests and our private results.
Having one public repository to publish to is going to be far easier in the long run in terms of future development and site rendering and troubleshooting.
To create the necessary repositories, use the below command.
The below command does many things in one command. It creates a folder in you’re my documents folder called Website. It then makes public and private repositories inside of that website folder, then it’s going to download the respective generators into their designated private folders, then open the public repos Github pages settings so you can make a change in here.
In all the below commands, change the word, username, to your github username exactly how you created it when you made your Github account.
New-Item -ItemType Directory -Path "$home\Documents\website"; CD $home\Documents\website; gh repo create Username.github.io --public --clone; gh repo create hugoprivate --private --clone; CD hugoprivate; hugo new site .; git add .; git commit -am "Changed website"; git push --set-upstream origin master; CD ../zolaprivate; git add .; git commit -am "Changed website"; git push --set-upstream origin master;; CD $home/documents/website/username.github.io; git add .; git commit -am "Updated website"; git push; Start-Process "https://github.com/username/username.github.io/settings/pages"
The above code did a lot! We created a folder, went into it, made our repositories, also called repos, private and public, went into our private folders and initialized a new hugo project, backed them up to Github, and then finally navigated to our public repos github pages settings.
Since we have our public repository settings open in a new tab, go down to the github pages heading. Find the next heading that says, build and deployment.
Change the source to deploy from a branch.
Change the branch source to be, main, and make sure to select root for that second button next to the main.
Press save, and now you don’t have to touch these settings again! Now, when we publish your website, using whatever engine we want, it’s going to automatically publish our website when we push our changes later.
The hard part is done! Now Let’s start building your websites!
Building and editing a hugo website.
Hugo has an okay getting started guide, here, but I found it just jumps you right in! My way is below, of course.
In windows explorer, keeping the powershell window open, Go back to our hugo website folder we created earlier. In here, we will see a lot of folders and a lot of files. They all have different purposes, so I’d highly recommend reading this hugo documentation about the folder structure and what the folders and files mean, as well as an overview of the site skeleton.
We’re going to be adding and editing files in this hugo directory, then we’re going to publish our website to Github. Because we already set it up, it’s going to automatically publish our website when we push changes to our public repository.
As of right now, we have a website skeleton. It needs a theme, and it needs some content.
Before we make content, we’re going to change a few things in the hugo.toml file found in the root of our hugo website directory so we don’t have to edit this file again unless we’re changing themes.
The hugo.TOML file is a configuration file for the website instance you just created.
In windows explorer, navigate to the hugo website directory we’re building. You should see a hugo.toml file that isn’t in a folder. Open this file in notepad.
Once hugo.toml is open in notepad, change the following, making sure to keep the tick marks around the words after the equal sign.
Replace the base URL, example dot com, with your public repository website URL like this, making sure to put your github username in the URL instead of having it say, username.
Next, change the site title, keeping the tick marks around your title.
Save then close this settings file.
You can set your theme and publish directory in here, but I’m going to do that for you in a later command.
Now we can start editing our website!
Editing our Hugo website.
First, we’re going to create some content. Then, we’re going to apply a theme.
Hugo doesn’t have a built in way to make pages, yet. The only kind of content we can create straight away are blog posts.
In powershell, After navigating to your hugo development directory in powershell, use the below command to create a new blog post.
hugo new content posts/my-first-post.md
If you got lost, use the below command to go back to your hugo development folder and then make the first blog post.
CD $home/documents/websites/hugoprivate; hugo new content posts/my-first-post.md
Now alt tab to your development folder, go into the content folder, and gaze upon your new blog post! Change post draft status to false, instead of true, then go all the way to the bottom, make an extra line just to be safe, type something, then save and close the document.
Hugo accepts content written in Markdown, so go ahead and type some markdown to practice. Save the text file when you are done by pressing Control, S. Now You’ve saved it, you can close this post.
You can use the hugo new content posts/ command to make as many blog posts as you want. Be sure to add a title of the post to the command, like this.
hugo new content posts/Test-post-two.
Also, be sure to change the draft statuses to false before saving the files, because they won’t render when we publish our hugo website to the world later if drafts is still set to true on a post.
Now, after You’ve made some content, Let’s add a theme to your blog!
Adding a theme to your blog.
Hugo has a huge array of themes to choose from here. I’ve chosen a very simple theme. It doesn’t have bells and whistles, but once you get the hang of switching themes, you can play around with more complex themes.
In powershell, navigate to your hugo directory and paste in the following command. It’s going to download the theme, then add the necessary stuff to your hugo.toml file so you don’t have to open it again unless you want to change themes later.
The below command should only be used on your first time setting up a theme. Do not use the below command to switch themes.
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke; echo "theme = 'ananke'`npublishDir = '../username.github.io'" | set-content -encoding Unicode hugo.toml
the above code downloaded a theme, added it to our themes folder, then added the theme and publish directory in our Hugo TOML file.
Every time you change a theme, you have to also change the theme name in the TOML file before rendering your website. I’d recommend downloading a few themes you like into the themes folder, then just changing the hugo TOML file as needed before rendering the website.
If you want to change the theme, you need to download another theme from the Hugo theme directory, then make sure to edit the theme name in the Hugo TOML file in your hugo development folder so that Hugo knows which theme to use when publishing/rendering your website.
Now that we have some content, and a theme added to our website, we’re actually ready to publish our website to the world now! first, though, Let’s test our website.
Testing our hugo website before publishing.
To test our website, in a powershell window, put,
hugo server.
Now we can visit our website by going to the URL given in the terminal/powershell window. The URL might be different, so copy and paste the whole powershell window and reviewing in a notepad, but the URL is usually, http://localhost:1313/
Now we can publish our website because we have everything set up!
Publishing your hugo website.
Because we set everything up before, we only need one command to publish and deploy our website to github and github pages.
Use the below to first publish the hugo website, then to save all the new files in our public github repository and push it online.
In a powershell window, after navigating to your hugo development folder, run the below command. The below command should be used your first time publishing a website. The second command is for all other times you want to update your website. It will publish all the changes You’ve made to hugo thus far, then push everything to Github so you have a backup, then navigate to your public repository, then push everything online.
hugo; git add .; git commit -am "Changed website"; git push --set-upstream origin master; CD $home/documents/website/username.github.io; git add .; git commit -am "Updated website"; git push
the above should be ran on your first time publishing the website. All other times, you’d want to use the below command to update your website.
hugo; git add .; git commit -am "Changed website"; git push; CD $home/documents/website/username.github.io; git add .; git commit -am "Updated website"; git push
now your website should be live at https://username.github.io/
that’s it! you’re done! You created a Hugo website! Now You’ve created a website, now I can share some shortcut commands I use. I’d recommend keeping the below commands handy.
Delete repo after it has been published to Github. Navigate to the directory in question before running the below delete command.
gh repo delete --yes
quickly make a brand new private hugo website with some content in the current directory and with a theme already picked out and theme name and publish directory already added to the TOML file.
choco install hugo-extended -confirm; New-Item -ItemType Directory -Path "$home\Documents\website"; CD $home\Documents\website; gh repo create hugo --private --clone; CD hugo; hugo new site .; git submodule add -b main https://github.com/1bl4z3r/hermit-V2 themes/hermit-v2; git submodule update --remote; echo "theme = 'hermit-v2'`npublishDir = '../username.github.io'" | set-content -encoding Unicode hugo.toml; hugo new content posts/my-first-post.md; CD ../username.github.io; hugo; git add .; git commit -am "Changed website"; git push --set-upstream origin master; CD $home/documents/website/username.github.io; git add .; git commit -am "Updated website"; git push
Now, we’re gonna make a Zola website.
making a Zola website.
Zola is a static website generator very similar to Hugo, except for that it’s very lightweight, and it doesn’t require any special dependencies. Everything is contained in one package, making this generator extremely portable.
How Zola differs from Hugo, also, is the fact it’s very minimalist. It doesn’t start you off with a lot of templating files or indexes or even starter files like Hugo does, so we’re going to be following their documentation for a lot of this section.
Luckily, a lot of the same concepts carry over from Hugo to Zola, so it should be a matter of closely following their documentation to learn what files they need to index your posts and how to display them and similar. In some ways, though, Zola is far more advanced than Hugo, in terms of setup and publishing to Github pages, but a lot of the same concepts apply including themes and publication.
First, Let’s make our Zola development environment. In powershell, paste the following to make our private Github repo, go into our repo, then make a Zola project inside of that repo with a sample theme.
New-Item -ItemType Directory -Path "$home\Documents\website"; CD $home\Documents\website; gh repo create zolaprivate --private --clone; CD Zolaprivate; Zola init .; git submodule add https://github.com/jieiku/abridge.git themes/abridge; git submodule update --init --recursive; git submodule update --remote --merge; git add .; git commit -am "Changed website"; git push --set-upstream origin master
When it asks you what is the URL of your website, put your public github pages website we made in the Hugo setup portion. Say yes to everything, even syntax highlighting, then the theme should be downloaded and ready to go!Go into the themes folder and find the CONFIG.TOML file inside of the themes folder. Open the TOML file in a text editor, copying everything below the BaseURL and pasting it into our own Config TOML file just below our BaseURL. Hit save, then change one more line in here.
Add the following below the site title.
publishDir = '../username.github.io'
Zola also has additional ways to change the directory when building or serving. In fact, you really should take time to read their whole documentation in addition to this command line pagebecause it is easy to understand. Still, like I said, we’re gonna use some example content.
This way, the hard part is done for you! Now, you just copy some sample content, then we’ll be done.
You can browse other Zola themes here, but see below on speeding up some of this content we’re about to make.
Unlike Hugo, Zola doesn’t have a native way to make posts or pages with one command, so we’ll use the themes templates instead.
If you want to try making your own layout and starting files, Zola walks you through all the steps here. It’s good practice to do so and put stuff in the right place so you have an idea of what it’s doing, where.
This theme author provided us with a lot of sample content though, so follow the instructions given on the theme page to copy some sample content into our website folders, as designated on the theme instructions.
When you’re all done, you’re ready to build and publish! Use the below command to make sure your site turns out okay. Copy the URL it gives you and view it in a web browser.
Zola build; Zola serve
We didn’t need to set up our public repos because that was done for us during the Hugo building above. That’s why the above Zola command is somewhat different. It will still get you a basic theme but, unfortunately, you’ll need to make blog posts by hand. I’ve provided a command below that automates this process a bit, but I hope Zola makes it easier to create blog posts natively.
Here’s my command for making a new blog post.
CD $home/documents/website/zolaprivate/content; echo " +++ntitle = 'My blog post'ndate = 2019-11-27`n+++" | set-content -encoding Unicode post.md
When you’re ready to publish to Github, use the below commands after making sure your Zola site works the way you want it to.
CD $home/documents/website/Zolaprivate; Zola build; git add .; git commit -am "Updated website"; git push; CD $home/documents/website/username.github.io; git add .; git commit -am "Updated website"; git push
Other places to publish your static site.
So now you’ve made a few websites with static site generators, but you can’t stand Github pages. Where do you host your static sites? I can recommend a few places!
In almost all cases, hosting your static site will be very easy. After building your website to a particular folder, not a Github repository, you just zip that folder containing your rendered files and you are good to go with almost all of the below hosts!
Find a number of places to host your static site here, or check out some highlights below.
11ty allows you to use their space to publish your 11ty project online, for free, for now.
Tiiny Web hosting offers free static site hosting.
Netlify is very popular and makes it very easy to host many kinds of static websites.