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

Suricata evasion, starring URL decoding

These days, one of my favourite hobbies is complaining about Suricata. In this blog, I’m going to talk about some of the weirdness in Suricata when processing URL-encoded data! I’m gonna go into deep detail about one technical aspect of Suricata rule creat…

via GreyNoise LabsJune 05, 2025

What Does It Even Mean To Be “Great” Anyway?

I normally don’t like writing “Current Events” pieces (and greatly prefer focusing on what SEO grifters like to call “evergreen content”), but I feel this warrants it. Content warning: Violence, death, mentions of political extremism. What Does “Great” Mea…

via Dhole MomentsJune 03, 2025

Elevate hover/focus effects with transitions across multiple elements

You can elevate hover/focus effects by triggering transitions on more than one element. With the right orchestration, you can create more nuanced effects.

via Rob O'Leary | BlogJune 01, 2025

Generative AI will probably make blogs better

Generative AI will probably make blogs better. Have you ever searched for something on Google and found the first one, two, or three blog posts to be utter nonsense? That's because these blog posts have been optimized not for human consumption, but rather …

via pcloadletterMay 30, 2025

The everlasting now

Continuing the experiment. My first post in this series was manually crafted, but coding a static almost-a-site generator, without having to worry about all the interrelationships on the old site was quick, & in Rust terms at least, relatively easy. This i…

via Mike KreuzerMay 23, 2025

Web3: The new Scarlet Letter on your resume

A premise about my work experience I have been working as a Software Engineer for over 8 years. In my career I have worked in these sectors and for these amounts of time: Embedded systems on Passenger Information Systems and Access Control Systems: 4…

via Christian Visintin BlogMay 21, 2025

Making a custom porteur bag

I just finished my first fully custom sewing project: a porteur bag for bike trips. This is a bag designed to fit on a front rack, in my case a rack called Jack The Bike Rack. On multi-day trips, I want to bring a change of clothes, and need somewhere to p…

via macwright.comMay 18, 2025

Status update, May 2025

Hi! Today wlroots 0.19.0 has finally been released! Among the newly supported protocols, color-management-v1 lays the first stone of HDR support (backend and renderer bits are still being reviewed) and ext-image-copy-capture-v1 enhances the previous screen…

via emersionMay 14, 2025

The British Airways position on various border disputes

My spouse and I are on vacation in Japan, spending half our time seeing the sights and the other half working remotely and enjoying the experience of living in a different place for a while. To get here, we flew on British Airways from London to Tokyo, and…

via Drew DeVault's blogMay 05, 2025

The Date that wasn't

A tale of lakes, dates and random results.

via Technically PersonalMay 03, 2025

Get Weird And Disappear

Pre-script: Reader and now close friend Phil Giammattei could use some help with a horrible brush with cancer in the family. You can support him here. Update: You all crushed Phil's goal, thank you so much for your generosity. Things are obviously Extremel…

via LudicityApril 29, 2025

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

#Rx Writing Challenge 2025

This is a short reflection on my experience of the recent writing challenge I took part in. Over the past two weeks, I have participated in the #RxWritingChallenge 1—a daily, 30-minute writing group starting at 9 AM every morning. Surrounded by fellow doct…

via Ul-lingaApril 05, 2025

My coffee workflow

My coffee workflow by Clement Delafargue on April 1, 2025 Tagged as: coffee, espresso, flair58, v60. It is my first April cools’ and I guess I could start by talking about coffee. If you’ve seen me in person, it won’t be a surprise, I guess. This po…

via Clément Delafargue - RSS feedApril 01, 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

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

Generated by openring-rs

favicon here hometagsblogmicrobio cvtech cvgpg keys