6 steps to own your content
with a personal static website!
To follow the steps below you will only need three things: (1) an internet connection, (2) a Unix-based shell, and (3) a GitHub account.
Assuming you are reading this article online, you definitely have the first item of the list figured out.
Then, if you are on MacOS or Linux, the Unix-based shell is simply your normal terminal. If you are on Windows, instead, you will need to activate the Linux Bash Shell on your system (here is a bash installation guide by It’s FOSS).
Finally, if you do not have a GitHub account, head over to GitHub and create a new one! A GitHub account is needed to use the free GitHub Pages hosting service, which runs a Jekyll instance to host your website online.
When choosing a username, keep in mind that, depending on the next step, your website will be accessible at one of the following addresses:
Here is an example of how to create a new user.
1. Create a new repository with GitHub pages
GitHub is an interface for
git: a version control system which tracks all changes you
make to your code. Since this is done separately for each project, each lives in a
separate folder, or repository. So, let’s head over to GitHub again and
create a new repository. There, we will store the files of your new
If you want to host your website at
yourUsername.github.io, you should choose that
address as your repository name (replacing
yourUsername with your GitHub username). If
you use a different repository name, instead, your website will be hosted at
Check the Add a README file and Add .gitignore options, selecting
Check out the GitHub documentation for more details on how to create a new repository.
2. Download your new repository
The easiest way to interact with GitHub repositories is to have
git and the GitHub
cli softwares available. This will allow you to download (or, in jergon,
files from the online repository to your local computer, and to upload (or
updated files to the online repository for publishing.
If you do not already have them, check out these two guides to install
Then, download your new repository by running the following command:
gh repo clone yourUsername/repositoryName
Which you can find in the main page of your repository.
3. Install Jekyll
Now that we have prepared an online space where to store our website’s files, we need a software to preview the website locally. This is essential to double-check that any new content is properly displayed, before publishing it on the public web. My tool of choice for this is Jekyll, a static website generator. To set it up, first follow the detailed instructions to install Jekyll’s prerequisites. Then, run the following command:
gem install jekyll bundler
Inside the folder where you downloaded your website’s repository, which is typically accessible via:
4. Pick a Jekyll theme
We are finally at the step of choosing how you want your website to look like. There is a large variety of already available Jekyll themes to choose from, which you can find at the following addresses:
- GitHub Jekyll Theme collection
- Jamstack Themes
- Jekyll Themes (
- Jekyll Themes (
- Jekyll Themes (
After spending some time going through these collections, pick your favorite theme and downlaod it (uncompressed) in your repository folder. Please, note that the theme should be in your repository folder, and not in a subfolder.
Check out this page for more details on Jekyll themes.
5. Initialize your website
It is now time to initialize your website. This is done by customizing the
file, which can be different from theme to theme.
The most essential thing is to set two values of the configuration file:
titlefield, which is the title of your website (e.g., Filopoetica for my website.
urlfield should have the address that will host your website: either
yourUsername.github.io/repositoryName, depending on what you chose in step 1.
So, find the lines with the
title: fields, and edit them to something like
I recommend reading in detail the documentation of the theme you chose, and fill the other relevant fields of the configuration file according to your taste.
To preview your website, change the
localhost:4000 and run the following
command from the repository folder
bundle exec jekyll serve -w.
6. Publish your website online
If everything looks good, let’s upload your new website to the repository and publish it. To upload it, we need to describe the changes we made. We do this in three steps:
Select the changed files you want to upload with
To select all changed files use
git add -A.
- To select all changed files use
Describe the changes with
git commit -m "description".
- In this case, you could use some on the line of "Theme upload" as description.
- Then, let's upload the changes by running
For more details on GitHub in general, check out this GitHub introduction.
Once you have pushed your content to your new repository, let’s publish it! First, head
to Settings (top-right option), and select Pages from the options on the left.
Then, select the
main branch and click the Save button.
Check out the GitHub Pages short introduction for more details on how to set them up on a repository.
GitHub Pages allows to publish your website at a custom domain. I did not cover this topic because the setup depends on your domain provider.
That’s it! If everything went correctly, you should now be able to access your website online and start publishing new content! ☺️
As a final note, remember that the address where your content is published is always available on the Pages section of your repository Settings.
Enjoy your new personal static website!
If you encounter any issues while following this guide, if you want to show your appreciation, or simply leave comment, you can do so by posting content on your webmention-compatible website, or by interacting with the syndicated copies of this content at the links below.