Building a website with Zola and Github Pages

27th Sep 2024
2 min read

Building a static website is easier than ever with tools like Zola and GitHub Pages. In this post, I'll walk you through the process of creating your own site and publishing it for free.

Prerequisites

Rust (for installing Zola)
Git
A GitHub account

1. Install Zola

First, install Zola using Cargo:

cargo install zola

Verify the installation:

zola --version

2. Create a New Zola Site

Generate a new site:

zola init mysite
cd mysite

Follow the prompts to set up your site.

3. Add Content and Customize

Edit config.toml to set your site title and other settings.
Add pages and posts in the content/ directory.
Choose or customize a theme from Zola Themes.

4. Build the Site

To preview locally:

zola serve

Visit http://127.0.0.1:1111 in your browser.

To build the static files:

zola build

The output will be in the public/ directory.

5. Push to GitHub

Initialize a git repository and push your code:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

6. Deploy with GitHub Pages

You can use GitHub Actions to automatically deploy your site. Add a workflow file at .github/workflows/deploy.yml:

name: Deploy Zola site to GitHub Pages

on:
    push:
        branches:
            - main

jobs:
    build-deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - name: Install Zola
                run: cargo install zola
            - name: Build site
                run: zola build
            - name: Deploy to GitHub Pages
                uses: peaceiris/actions-gh-pages@v4
                with:
                    github_token: ${{ secrets.GITHUB_TOKEN }}
                    publish_dir: ./public

Commit and push this file.

7. Configure GitHub Pages

Go to your repository's Settings > Pages.
Set the source to gh-pages branch (created by the workflow).
Your site will be live at https://yourusername.github.io/your-repo/.

Conclusion

With Zola and GitHub Pages, you can quickly build and deploy a fast, modern static website. Happy building!