favicon here hometagsblogmicrobio cvtech cvgpg keys

How To Deploy A Webpage to GitHub Pages

#webpages #ci #static-site-generators

uncomfyhalomacro | 2024-11-15 | reading time: ~8min

There are many existing documentation about deploying webpages to GitHub pages.

This guide is just a guide for those that are interested in a very manual setup.

There is already a full documentation for GitHub Pages if you want the full doc experience.

Also, readers are expected that they are competent enough to know basic Git commands.

Commands used here are for Bash shell.


Deploying a small HTML file§

If you are not yet familiar with how the CI works, do not worry as you will notice that writing CI workflows as basic as this is not that really difficult.

To start with, you have to do the following as prerequisites.

  1. Create a GitHub Account.
  2. Create a repository.
  3. Clone the new repository locally.

The full commands starting for step 3 are

git clone https://github.com/uncomfyhalomacro/simple-site
cd simple-site

Adjust the URL to your repository. If you prefer SSH, the full commands are

git clone git@github.com:uncomfyhalomacro/simple-site.git
cd simple-site

One can check that the remote for the repository is set properly by running the following command.

git remote -v

By default, it's named as origin. Your output could look like this

origin	git@github.com:uncomfyhalomacro/simple-site.git (fetch)
origin	git@github.com:uncomfyhalomacro/simple-site.git (push)

Now that everything is setup, let's create an index.html at the root directory of the project.

touch index.html

Open and edit it with your editor. I use kakoune.

Copy this simple HTML code below to your new file index.html.

<!DOCTYPE html>
<html lang="en">
<body>
Hello World!
</body>
</html>

This should suffice.

Setting Up Your PERSONAL ACCESS TOKEN§

To setup your Personal Access Token (PAT), you must be logged in to your GitHub account. Then head over to https://github.com/settings/apps.

You should see an option "Personal access tokens". Click that button.

You should get a drop down with some options. Click "Tokens (classic)".

In the upper-right, you can see the "Generate new token" button. Click that.

You should get a drop down with some options. Click "Generate new token (classic)".

You will be redirected to either enter your password or TOTP for 2FA. Please enter what was asked.

Name your TOKEN to whatever you want e.g. "simple-site". Feel free to set the expiration date of the TOKEN.

You will also see a lot of scopes. Just select the one with [ ] repo Full control of private repositories.

This will give full control for both private and public repositories that you have.

Now on the bottom-right, click the "Generate token" button. You will be redirected with a one time copy of the token. Copy or write it down somewhere safe.

⚠️ Be careful not to share your token once it's generated.

Setting Up GitHub Workflows§

Now, in your local repository, create a directory .github/workflows/.

mkdir -p .github/workflows/

Create a new file called pubish.yml at .github/workflows/.

touch .github/workflows/publish.yml

Copy the following code snippet to your publish.yml.

name: Publish
permissions: write-all
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      TOKEN: ${{ secrets.TOKEN }}
    steps:
    - name: Checkout
      uses: actions/checkout@v4
    - name: Publish static site
      run: |
        mkdir -p public
        pushd public
        cp ../index.html index.html
        touch .nojekyll
        git init
        git branch -m gh-pages
        git config --global user.email "youremail"
        git config --global user.name "yourusername"
        git remote add origin "https://yourusername:$TOKEN@github.com/yourusername/simple-site.git"
        git add -A
        git commit -m "update site page"
        git push --force -u origin gh-pages

Ensure you have replaced the following

  • "youremail" should be your email address
  • "yourusername" should be your username e.g. username for GitHub account

Be careful with the indentations as YAML can be quite confusing.

Now before pushing to your remote repository, you have to set your TOKEN as a GitHub secret in your repository. You should head to the link like

https://github.com/yourusername/simple-site/settings/secrets/actions

Replace first the "yourusername" with your username on GitHub before copying it and pasting it on your browser.

You will see two options once you head to the webpage

  • Environment secrets
  • Repository secrets

Choose the one with Repository secrets and click "New repository secret". You will be redirected to a page where you will input your TOKEN. Set the name as "TOKEN". Then paste the value of your PERSONAL ACCESS TOKEN.

Once set, click "Add secret" button.

Lastly, add and commit your local changes and push it to your remote repository.

git add -A
git commit -m 'initial commit'
git push -u origin main

Your site will now be at https://yourgithubusername.github.io/simple-site where yourgithubusername is your GitHub username. You should see a "Hello World!" on your browser.

See the source repository for how we did it at https://github.com/uncomfyhalomacro/simple-site.

Convenient Static Site Generators§

At this point, you already know how to setup and deploy a webpage. However, writing a complex webpage with pure HTML can be tedious.

That's where static site generators come into the picture.

There are many popular static site generators to choose from such as

For this part of the tutorial, you are going to use zola, a simple static site generator written in Rust.

First create a new repository named "ssg-site".

Clone it locally and change directory into the ssg-site directory.

An example command will look like this. This uses SSH as the remote repository. Adjust to your configuration.

git clone git@github.com:yourusername/ssg-site.git

Replace "yourusername" with your GitHub username.

Then you must install zola. Follow installation instructions here.

Initialising Zola§

Run the following command at the root directory of the project.

zola init .

It will ask you the following questions.

For the first question

What is the URL of your site? (https://example.com):

You should input the following format https://yourusername.github.io/ssg-site where "yourusername" is your GitHub username.

The next question will be

Do you want to enable Sass compilation?

Type "Y" then press Enter.

The third question will be

Do you want to enable syntax highlighting?

Type "Y" then press Enter.

The last question will be

Do you want to build a search index of the content?

Feel free to type "Y" or "N". It does not matter yet, unless in the future, you want your site to have a search bar.

You have finally setup your Zola configuration. Now try running the command

zola serve

It should serve your webpage locally at http://127.0.0.1:1111. It might change if another has already parked that port.

But our site is still bland. Let's proceed adding a theme.

Setting Up Zola Theme§

Zola has many cool themes. You can check the theme collection at https://www.getzola.org/themes/.

Let's use anemone, one of my favourite themes in Zola.

At the root directory of your project, run the following command.

git submodule add "https://github.com/Speyll/anemone" themes/anemone

This should create a git submodule in your project.

Now open and edit your config.toml. It should look like the following.

# The URL the site will be built for
base_url = "https://yourusername.github.io/ssg-site"

# Whether to automatically compile all Sass files in the sass directory
compile_sass = true

# Whether to build a search index to be used later on by a JavaScript library
build_search_index = false

theme = "anemone"

[markdown]
# Whether to do syntax highlighting
# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
highlight_code = true

[extra]
# Put all your custom variables here
toc = true
display_author = true
list_pages = true
header_nav = [
  { url = "/", name_en = "/home/"}
]

Replace "yourusername" with your GitHub username. Save the file.

Your webpage will reload and it will be an empty page with a footer. The colors are new as well because of the theme.

Adding some content§

Now that our theme is up, let's add some content. At the root directory of your project, head to content directory. Create a new markdown file _index.md. Now copy and paste this Lorem ipsum to _index.md file.

+++
title = "Lorem Ipsum"
+++

# Lorem Ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
## Dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

### Consectetur adipiscing elit

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Then run the following commands.

cp _index.md 1.md

To understand what these files do, _index.md serves as the "home" page. It will list our posts such as 1.md.

Now try to edit _index.md such as an introduction about yourself and what you do.

Then edit 1.md with your new goals in life or tips and tricks.

Once satisfied, let's finally deploy your site to GitHub Pages.

Deploying to GitHub Pages§

At this point, you can either regenerate a new TOKEN or use the previous one you have created from simple-site. Let's just assume you already have a TOKEN.

First, run this command at the root directory of your project.

echo "public" >> .gitignore

This should ignore the generated public directory. You should always do this because otherwise, you will end up having duplicated files unless you have other plans. The public directory is only created when you run this command.

zola build

Next, add the new TOKEN as a Repository secret. You can repeat the steps you did on how to add a new TOKEN to your repository like in the simple-site.

Here is the fun part. Do the following commands.

mkdir -p .github/workflows/
touch .github/workflows/publish.yml

Then edit your publish.yml file which is located at .github/workflows/ with the following code.

name: Publish
permissions: write-all
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    container: opensuse/tumbleweed:latest
    env:
      TOKEN: ${{ secrets.TOKEN }}
    steps:
    - name: Checkout
      uses: actions/checkout@v4
    - name: Install dependencies
      run: |
        zypper --non-interactive in zola git
    - name: Generate static site
      run: |
        rm -rf themes/
        mkdir -p themes/
        pushd themes/
        git clone --depth 1 https://github.com/Speyll/anemone
        popd
        zola build
    - name: Publish static site
      run: |
        pushd public
        touch .nojekyll
        echo "uncomfyhalomacro.pl" >> CNAME
        git init
        git branch -m gh-pages
        git config --global user.email "youremail"
        git config --global user.name "yourusername"
        git remote add origin "https://yourusername:$TOKEN@github.com/yourusername/ssg-site.git"
        git add -A
        git commit -m "update site page"
        git push --force -u origin gh-pages

Ensure you change "yourusername" to your GitHub username and "youremail" to the email you are using for your GitHub account.

Save the file. Now run the following command to add and commit your changes, then push.

git add -A
git commit -m 'my first blog'
git push -u origin main

Notice that in the YAML file, it uses a custom image. That's because that linux distribution image, Tumbleweed, already has an updated version of zola.

Once your site has been generated in the GitHub actions, you can head over to this link format yourusername.github.io/ssg-site where "yourusername" is your GitHub username.

Feel free to use this or learn and use other SSGs to prettify your blogs and web pages!

FAQ§

I noticed that you didn't use a GitHub action plugin shalzz/zola-deploy-action@master. Why?

If you know the process, then you can trust yourself more than some random plugin. Not saying they could not be trusted but you have to weigh your risks

  1. You already know how to deploy, then you are more sure that you can trust yourself.
  2. Trust is a spectrum.

Therefore, I don't need someone's tool if I already know how to do things. It's for the security side of things since GitHub actions can be a potential attack surface.


Okay that's a wrap. Feel free to reach out to me in my preferred communication channels 🤪

Articles from blogs I follow around the net

Body::poll_progress

This describes a proposal for a cancelation problem with hyper’s request and response bodies. hyper is an HTTP library for the Rust language. Background: what is the Body trait? The Body trait used by hyper is meant to represent a potentially streaming (…

via seanmonstarApril 22, 2025

CVE-2025-32433 - State Machine Err-ly RCE in Erlang/OTP SSH Server

CVE-2025-32433 is a remote code execution vulnerability in the SSH server implementation within Erlang’s OTP libraries (affecting versions legendary CVSS score of 10.0 and became known as a vulnerability for which AI-assisted exploit development process wa…

via GreyNoise LabsApril 22, 2025

AI-powered search summaries led to less clicks to websites

Google claims that links beside AI summaries get more clicks. This goes against intuition. Ahrefs did some analysis on this recently. Who is right?

via Rob O'Leary | BlogApril 21, 2025

Resistance from the tech sector

As of late, most of us have been reading the news with a sense of anxious trepidation. At least, those of us who read from a position of relative comfort and privilege. Many more read the news with fear. Some of us are already no longer in a position to re…

via Drew DeVault's blogApril 20, 2025

Retrospective: Five Years Blogging About Cryptography as a Gay Furry Online

The history of this blog might very well be a cautionary tail (sic) about scope creep. The Original Vision For Dhole Moments Originally, I just wanted a place to write about things too long for Twitter (back when I was an avid Twitter poster). I also figur…

via Dhole MomentsApril 17, 2025

Status update, April 2025

Hi! Last week wlroots 0.19.0-rc1 has been released! It includes the new color management protocol, however it doesn’t include HDR10 support because the renderer and backend bits haven’t yet been merged. Also worth noting is full explicit synchronization su…

via emersionApril 16, 2025

The IndieWeb & that blog roll

The IndieWeb's something I've known about for a while, but never really engaged with. I mean this is very much part of The Indie Web, the very thing, you're reading it right now. But in terms of the camel cased movement, not so much. To me they seemed a bi…

via Mike KreuzerApril 16, 2025

Tidbyt without the company

Remember the Tidbyt? It’s a super low-resolution, internet-connected, wood-paneled display that I wrote a review of it back in 2022. It’s been on my shelf for years now, showing the time, weather, warning me when the UV is going to be high. In 2023 I used …

via macwright.comApril 12, 2025

One does not simply write a SSH config parser (in Rust)

Do you know the feeling when you start a project and you think it will be easy, but then you realize that it is not? This is the story of the implementation of ssh2-config, a Rust library to parse SSH config files. Why did I write this? Because basically…

via Christian Visintin BlogMarch 30, 2025

LLDB's TypeSystems: An Unfinished Interface

Well, it's "done". TypeSystemRust has a (semi) working prototype for LLDB 19.x. It doesn't support expressions or MSVC targets (i.e. PDB debug info), and there are a whole host of catastrophic crashes, but it more or less proves what it needs to: Rust's de…

via Cracking the ShellMarch 28, 2025

Backup Yubikey Strategy

After a local security meetup where I presented about Webauthn, I had a really interesting chat with a member about a possible Yubikey management strategy. Normally when you purchase a yubikey it's recommended that you buy two of them - one primary and one…

via Firstyear's blog-a-logFebruary 28, 2025

Ludic's Guide To Getting Software Engineering Jobs

The steps in this guide have generated A$1,179,000 in salary (updated 13th April, 2025), measured as the sum of the highest annual salaries friends and readers have reached after following along, where they were willing to attribute their success actions i…

via LudicityFebruary 28, 2025

The Adrian Dittmann Story

the evidence, from A to Z, and righting the wrongs

via maia blogJanuary 05, 2025

Awesome Fish functions

Some awesome fish functions that I have accumalated over the years.

via Ishan WritesJanuary 03, 2025

Physics Simulations in Bevy

Bevy is the most popular and powerful game engine in Rust. Because of its flexibility, it can be used not only for games but also for (scientific) physics simulations. In this blog post, I will share my experience using Bevy for physics simulations from sc…

via mo8it.comJuly 19, 2024

Defending myself against defensive writing

I write this blog because I enjoy writing. Some people enjoy reading what I write, which makes me feel really great! Recently, I took down a post and stopped writing for a few months because I didn't love the reaction I was getting on social media sites li…

via pcloadletterMay 27, 2024

The Elegiac Hindsight of Intelligent Machines

This essay was edited out of a chapter of my book, The Intelligence Illusion: a practical guide to the business risks of Generative AI, with minor alterations. “See the choice of dreams”, and then worry about it Very well. This book – this side, Dream …

via Out of the Software Crisis (Newsletter)October 13, 2023

Regex engine internals as a library

Over the last several years, I’ve rewritten Rust’s regex crate to enable better internal composition, and to make it easier to add optimizations while maintaining correctness. In the course of this rewrite I created a new crate, regex-automata, which expos…

via Andrew Gallant's Blog on Andrew Gallant's BlogJuly 05, 2023

Generated by openring-rs

favicon here hometagsblogmicrobio cvtech cvgpg keys