Postalgic → Help Center → GitHub Pages Setup

Setting Up GitHub Pages

Host your Postalgic blog for free with GitHub Pages

GitHub Pages is a free hosting service that's perfect for Postalgic blogs. It serves static websites directly from your GitHub repository, making it an ideal match for the static sites that Postalgic generates.

Why GitHub Pages?
• Completely free hosting
• Custom domain support
• HTTPS included
• Git-based deployment
• Excellent uptime and performance

Prerequisites

Before starting, make sure you have:

  • A GitHub account (free)
  • The Postalgic iOS app with a configured blog
  • Git configured for publishing in Postalgic (we'll set this up)

Step-by-Step Setup

1

Create a GitHub Repository

  1. Go to GitHub.com and sign in
  2. Click the "New" button or "+" icon to create a new repository
  3. Name your repository (e.g., my-blog or your-username.github.io)
  4. Make sure it's set to Public
  5. Check "Add a README file"
  6. Click "Create repository"
Tip: If you name your repository your-username.github.io, your blog will be available at https://your-username.github.io directly.
2

Enable GitHub Pages

  1. In your new repository, click on "Settings" (in the top navigation)
  2. Scroll down to "Pages" in the left sidebar
  3. Under "Source", select "Deploy from a branch"
  4. Choose "main" as the branch
  5. Select "/ (root)" as the folder
  6. Click "Save"

GitHub will show you the URL where your site will be published (e.g., https://your-username.github.io/my-blog).

3

Create a Personal Access Token

Postalgic needs permission to push to your repository:

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click "Generate new token" → "Generate new token (classic)"
  3. Add a note like "Postalgic Blog Publishing"
  4. Set expiration (recommend 1 year or no expiration)
  5. Check the "repo" scope (this gives full repository access)
  6. Click "Generate token"
  7. Copy the token immediately - you won't see it again!
Important: Store your token securely. You'll need it to configure Postalgic.
4

Configure Git Publishing in Postalgic

  1. Open the Postalgic iOS app
  2. Go to your blog and tap "Publish"
  3. Select "Git" as your publishing method
  4. Fill in the configuration:

Git Configuration Settings:

  • Repository URL: https://github.com/your-username/your-repo-name.git
  • Username: Your GitHub username
  • Password/Token: The personal access token you created
  • Branch: main
5

Configure Your Blog URL

Set your blog's URL to match your GitHub Pages site:

  1. In Postalgic, go to Blog Settings
  2. Update the "Blog URL" field with your GitHub Pages URL
  3. For example: https://your-username.github.io/my-blog
  4. This ensures links in your RSS feed and site navigation work correctly
6

Publish Your First Post

  1. Create a test post in Postalgic
  2. Go to the Publish screen
  3. Tap "Publish Blog"
  4. Postalgic will generate your static site and push it to GitHub
  5. Wait a few minutes for GitHub Pages to build and deploy
  6. Visit your GitHub Pages URL to see your live blog!

Custom Domain Setup (Optional)

You can use your own domain name instead of the GitHub Pages subdomain:

DNS Configuration

  1. In your domain registrar's DNS settings, create a CNAME record
  2. Point your domain (e.g., blog.example.com) to your-username.github.io
  3. For apex domains (e.g., example.com), create A records pointing to: 
    185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

GitHub Configuration

  1. In your repository, go to Settings → Pages
  2. Under "Custom domain", enter your domain
  3. Check "Enforce HTTPS" (after DNS propagates)
  4. GitHub will create a CNAME file in your repository
Note: DNS changes can take up to 24 hours to propagate globally.

Troubleshooting

Common Issues

Authentication Failed

  • Double-check your GitHub username and personal access token
  • Ensure the token has "repo" scope permissions
  • Verify the repository URL is correct

Site Not Updating

  • GitHub Pages can take a few minutes to update after each push
  • Check the "Actions" tab in your repository for build status
  • Clear your browser cache if changes don't appear

404 Page Not Found

  • Ensure GitHub Pages is enabled and pointing to the correct branch
  • Verify your blog URL in Postalgic matches your GitHub Pages URL
  • Check that your repository is public

HTTPS Issues with Custom Domain

  • Wait for DNS propagation (up to 24 hours)
  • Disable and re-enable "Enforce HTTPS" in repository settings
  • Ensure your CNAME record points to username.github.io, not the full repository URL

Benefits of GitHub Pages Hosting

  • Version Control: Every change to your blog is tracked in Git
  • Backup: Your entire blog is safely stored in GitHub
  • Collaboration: Others can contribute to your blog via pull requests
  • Performance: GitHub's CDN ensures fast loading worldwide
  • Security: Static sites are inherently secure with HTTPS included
  • Cost: Completely free for public repositories
Perfect Match: GitHub Pages is specifically designed for static sites, making it an ideal hosting solution for Postalgic blogs.

Next Steps

Once your blog is live on GitHub Pages:

  • Customize your blog's appearance using Postalgic's templating system
  • Learn about markdown formatting for rich content
  • Set up analytics (Google Analytics, Plausible, etc.) by editing your theme templates
  • Share your RSS feed URL so others can follow your blog
  • Consider setting up a custom domain for a more professional appearance