Zine Installation Guide for macOS

Zine Installation Guide for macOS

This guide walks you through installing (and updating) Zine — a fast static site generator written in Zig — on macOS only.

Zine is currently beta software. Simple and medium-complexity websites work well today.

Official resources:

• Website: https://zine-ssg.io
• Quickstart: https://zine-ssg.io/quickstart/
• Releases: https://github.com/kristoff-it/zine/releases
• Source: https://github.com/kristoff-it/zine

---

1. Overview of the Installation Process

On macOS you typically:

1. Download the correct pre-built binary for your chip (Apple Silicon or Intel).
2. Remove the Gatekeeper quarantine attribute (macOS blocks unsigned binaries by default).
3. Place the binary in a directory that is in your $PATH.
4. (Optional) Create a reusable script so you can update Zine with one command in the future.

You can do everything manually or use the automated script provided at the end of this guide.

---

2. Manual Installation (Step-by-Step)

Step 1 – Detect your architecture

Open Terminal and run:

uname -m

• arm64 → Apple Silicon (M1 / M2 / M3 / M4 …)
• x86_64 → Intel Mac

Step 2 – Download the latest release

1. Go to: https://github.com/kristoff-it/zine/releases/latest
2. Under Assets download the correct file:

Chip	File to download
Apple Silicon	aarch64-macos.zip
Intel	x86_64-macos.zip

Step 3 – Extract the binary

cd ~/Downloads          # or wherever you saved the zip
unzip aarch64-macos.zip # or x86_64-macos.zip

You will get a single executable named zine.

Step 4 – Make it executable and clear Gatekeeper quarantine

macOS marks downloaded files with a quarantine flag. If you try to run the binary you will see:

“zine” Not Opened
Apple could not verify “zine” is free of malware that may harm your Mac or compromise your privacy.

Fix it with:

chmod +x zine
xattr -d com.apple.quarantine zine

Alternative (GUI method):

1. Right-click (or Control-click) the zine file in Finder.
2. Choose Open.
3. Click Open in the confirmation dialog.
   After doing this once, the warning disappears permanently for that binary.

Step 5 – Move it into your PATH

Recommended location:

sudo mv zine /usr/local/bin/

Verify the installation:

which zine
zine --version

You should see something like:

/usr/local/bin/zine
zine 0.14.0

Step 6 – Create a new site (optional)

mkdir my-site
cd my-site
zine init
zine          # starts the live-reload development server

---

3. Recommended Developer Tooling (Optional)

For the best editing experience install these VS Code extensions (all by Loris Cro):

• Ziggy
• SuperMD
• SuperHTML

Other editors: see https://zine-ssg.io/docs/editors/

---

4. Automated Reusable Install / Update Script

The script below does everything automatically:

1. Detects your architecture.
2. Checks whether an old version of Zine is already installed (which zine).
3. Shows the currently installed version (if any).
4. Fetches the latest version number from GitHub.
5. Removes the old binary.
6. Downloads the correct macOS zip.
7. Extracts it, clears the quarantine flag, and installs the new binary to /usr/local/bin.

Create the script

nano ~/install-zine.sh

Paste the following content:

#!/usr/bin/env bash
set -euo pipefail

# -------------------------------------------------
# Install / update Zine (latest release) on macOS
# -------------------------------------------------

REPO="kristoff-it/zine"
INSTALL_DIR="/usr/local/bin"
TMP_DIR=$(mktemp -d)
trap 'rm -rf "$TMP_DIR"' EXIT

# Detect architecture
ARCH=$(uname -m)
case "$ARCH" in
  arm64)  ASSET="aarch64-macos.zip" ;;
  x86_64) ASSET="x86_64-macos.zip" ;;
  *)
    echo "Unsupported architecture: $ARCH"
    exit 1
    ;;
esac

echo "→ Detected architecture: $ARCH"
echo

# -------------------------------------------------
# 1. Check if an old version is already installed
# -------------------------------------------------
OLD_PATH=$(which zine 2>/dev/null || true)

if [[ -n "$OLD_PATH" ]]; then
  echo "→ Found existing installation:"
  echo "   Location : $OLD_PATH"
  echo -n "   Version  : "
  "$OLD_PATH" --version 2>/dev/null || echo "(could not read version)"
  echo
else
  echo "→ No existing zine found in PATH"
  echo
fi

# -------------------------------------------------
# 2. Get latest version info
# -------------------------------------------------
echo "→ Checking latest release of $REPO..."
LATEST_JSON=$(curl -sL "https://api.github.com/repos/$REPO/releases/latest")
TAG=$(echo "$LATEST_JSON" | grep -o '"tag_name": *"[^"]*"' | head -1 | cut -d'"' -f4)
DOWNLOAD_URL=$(echo "$LATEST_JSON" | grep -o "\"browser_download_url\": *\"[^\"]*$ASSET\"" | head -1 | cut -d'"' -f4)

if [[ -z "$TAG" || -z "$DOWNLOAD_URL" ]]; then
  echo "❌ Could not find latest release or the $ASSET asset."
  exit 1
fi

echo "→ Latest version available: $TAG"
echo

# -------------------------------------------------
# 3. Remove old version (if found)
# -------------------------------------------------
if [[ -n "$OLD_PATH" ]]; then
  echo "→ Removing old version at $OLD_PATH..."
  if [[ -w "$OLD_PATH" ]]; then
    rm -f "$OLD_PATH"
  else
    sudo rm -f "$OLD_PATH"
  fi
  echo "   Removed."
  echo
fi

# -------------------------------------------------
# Download + install new version
# -------------------------------------------------
echo "→ Downloading $ASSET..."
curl -L --progress-bar -o "$TMP_DIR/$ASSET" "$DOWNLOAD_URL"

echo "→ Extracting..."
unzip -q -o "$TMP_DIR/$ASSET" -d "$TMP_DIR"

BINARY="$TMP_DIR/zine"
if [[ ! -f "$BINARY" ]]; then
  echo "❌ Error: binary 'zine' not found inside the archive."
  exit 1
fi

# Make executable + remove Gatekeeper quarantine
chmod +x "$BINARY"
xattr -d com.apple.quarantine "$BINARY" 2>/dev/null || true

echo "→ Installing to $INSTALL_DIR (may ask for password)..."
sudo mv "$BINARY" "$INSTALL_DIR/zine"

echo
echo "✅ Zine $TAG installed successfully!"
echo
echo "New location : $(which zine)"
zine --version
echo
echo "You can now run:  zine init"

Save and exit (Ctrl+O, Enter, Ctrl+X in nano).

Make the script executable

chmod +x ~/install-zine.sh

Run it

~/install-zine.sh

You can re-run this script whenever you want to update to the newest Zine release.

---

5. Common Issues & Solutions

Problem	Solution
“zine” Not Opened / malware warning	Run xattr -d com.apple.quarantine /path/to/zine or right-click → Open once
command not found: zine	Make sure /usr/local/bin is in your $PATH. Check with echo $PATH
Permission denied when moving binary	Use sudo or install to ~/bin instead
Script fails to find the asset	GitHub API rate limit or temporary network issue – wait a minute and try again
Want to install without sudo	Change INSTALL_DIR="/usr/local/bin" to INSTALL_DIR="$HOME/bin" and create the folder first: mkdir -p ~/bin

---

6. Quick Reference Commands

# Check installed location
which zine

# Check version
zine --version

# Update to latest (using the script)
~/install-zine.sh

# Create a new site
mkdir my-site && cd my-site
zine init
zine          # start live-reload server

---

← Go "encoding/json/v2" Unmarshall Stream   •   Superiority, by Arthur C. Clarke's Works →   or   Back to the Homepage