Skip to content

URL Configuration Guide

This guide explains how to configure URLs for the Zer0-Mistakes Jekyll theme in different hosting scenarios.

Overview

The URL configuration supports different hosting environments. The recommended approach for forks is a GitHub Pages user site:

  • User site (recommended for forks): https://username.github.io/ — fork into username.github.io, baseurl: ""
  • Project site: https://username.github.io/repository-name/ — requires baseurl: "/repository-name"
  • Custom domain: https://your-custom-domain.com/ — baseurl: ""
  • Local development: http://localhost:4000/

Configuration Files

_config.yml (Production)

Main configuration file used for production builds and GitHub Pages deployment.

_config_dev.yml (Development)

Development overrides that are merged with the main config when running locally.

Hosting Scenarios

Fork the repo as <your-username>.github.io. The site deploys at the domain root — no baseurl needed:

_config.yml (no changes required from upstream defaults):

url: "https://username.github.io"
baseurl: ""  # Empty — user site deploys at root

URLs:

  • Local: http://localhost:4000/
  • Production: https://username.github.io/

See Forking Guide for the full fork guide.

2. GitHub Pages Project Site

For repos with any other name (e.g. zer0-mistakes):

_config.yml:

url: "https://username.github.io"
baseurl: "/zer0-mistakes"

URLs:

  • Local: http://localhost:4000/zer0-mistakes/
  • Production: https://username.github.io/zer0-mistakes/

2. Custom Domain Hosting

For hosting with a custom domain like zer0-mistakes.com:

_config.yml:

custom_domain: "zer0-mistakes.com" # Your custom domain
url: "https://zer0-mistakes.com"
baseurl: "" # Empty for root domain hosting

Development URLs:

  • Local: http://localhost:4000/
  • Production: https://zer0-mistakes.com/

3. GitHub Pages with Custom Domain

For GitHub Pages with a custom domain (CNAME file):

_config.yml:

custom_domain: "zer0-mistakes.com" # Your custom domain
url: "https://zer0-mistakes.com"
baseurl: "" # Empty when using custom domain

Development Commands

Start Development Server

# Using Docker (Recommended)
docker-compose up

# Or using local Jekyll
bundle exec jekyll serve --config _config.yml,_config_dev.yml

Build for Production

# Using Docker
docker-compose run --rm jekyll jekyll build --config _config.yml

# Or using local Jekyll
bundle exec jekyll build --config _config.yml

Migration from Old Configuration

If migrating from the previous complex URL configuration:

  1. Remove old variables: The following variables are no longer needed:
  2. domain and domain_ext
  3. url_test
  4. portfolio

  5. dg_port

  6. Update custom variables: If you have custom Liquid templates that reference the old URL structure, update them to use:

  7. {{ site.url }}{{ site.baseurl }} for full site URL

  8. {{ site.baseurl }} for relative paths

  9. Test thoroughly: After migration, test both local development and production builds to ensure all links work correctly.

Troubleshooting

  • Ensure you're accessing http://localhost:4000/zer0-mistakes/ (with trailing slash)
  • Check that baseurl matches your repository name

Custom domain not working

  • Verify your DNS settings point to GitHub Pages
  • Ensure CNAME file exists in your repository root
  • Update url and baseurl settings as described above

Assets not loading

  • Check that asset paths use {{ site.baseurl }} prefix
  • Verify public_folder setting in config

Best Practices

  1. Always test locally before deploying to production
  2. Use relative URLs with {{ site.baseurl }} for internal links
  3. Keep development and production configs in sync for URL structure
  4. Document any custom URL requirements in your project README

For more information, see the Jekyll documentation on configuration.