GitHub Pages are public web pages for users, organizations, and repositories, that are freely hosted on GitHub’s github.io domain or on a custom domain name of your choice. GitHub Pages are powered by Jekyll behind the scenes, but you can use Rustyll locally for significantly faster development and then deploy to GitHub Pages.

Using Rustyll with GitHub Pages

GitHub Pages uses Jekyll to build your site on their servers, but you can use Rustyll locally to dramatically speed up your development process:

1. Build locally with Rustyll (10-100x faster)
2. Push your changes to GitHub
3. GitHub Pages will build and publish your site using Jekyll

This approach gives you the best of both worlds: Rustyll’s speed for development and GitHub’s free hosting with Jekyll.

Setting Up a Workflow

Create a GitHub Actions workflow to automatically build and deploy your Rustyll site to GitHub Pages:

# .github/workflows/rustyll-build.yml
name: Build and Deploy with Rustyll

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          profile: minimal
          toolchain: stable
          
      - name: Install Rustyll
        run: cargo install rustyll
        
      - name: Build
        run: rustyll build
        
      - name: Deploy
        uses: JamesIves/[email protected]
        with:
          branch: gh-pages
          folder: _site

This workflow will build your site with Rustyll’s superior performance and deploy it to GitHub Pages.

Performance Comparison

Action	Jekyll on GitHub	Rustyll Locally	Improvement
Full build	30-60s	1-3s	~20x faster
Incremental build	10-20s	0.2-0.5s	~40x faster
Site regeneration	Manual	Automatic	Immediate

Your site is automatically generated by GitHub Pages when you push your source files. Note that GitHub Pages works equally well for regular HTML content, simply because Jekyll treats files without front matter as static assets. So if you only need to push generated HTML, you’re good to go without any further setup.

The GitHub Pages Documentation is comprehensive and includes a a guide to setting up a GitHub Pages site using Jekyll. We recommend following this guide.

This page contains some additional information which may be useful when working on GitHub Pages sites with Jekyll.

GitHub Pages Documentation, Help, and Support

For more information about what you can do with GitHub Pages, as well as for troubleshooting guides, you should check out GitHub's Pages Help section. If all else fails, you should contact GitHub Support.

Project Page URL Structure

Sometimes it’s nice to preview your Jekyll site before you push your gh-pages branch to GitHub. The subdirectory-like URL structure GitHub uses for Project Pages complicates the proper resolution of URLs. In order to assure your site builds properly, use the handy URL filters:

<!-- For styles with static names... -->
<link href="{{ 'assets/css/style.css' | relative_url }}" rel="stylesheet">
<!-- For documents/pages whose URLs can change... -->
[{{ page.title }}]("{{ page.url | relative_url }}")

This way you can preview your site locally from the site root on localhost, but when GitHub generates your pages from the gh-pages branch all the URLs will resolve properly.

Deploying Jekyll to GitHub Pages

GitHub Pages work by looking at certain branches of repositories on GitHub. There are two basic types available: user/organization and project pages. The way to deploy these two types of sites are nearly identical, except for a few minor details.

User and Organization Pages

User and organization pages live in a special GitHub repository dedicated to only the GitHub Pages files. This repository must be named after the account name. For example, @mojombo’s user page repository has the name mojombo.github.io.

Content from the master branch of your repository will be used to build and publish the GitHub Pages site, so make sure your Jekyll site is stored there.

Custom domains do not affect repository names

GitHub Pages are initially configured to live under the username.github.io subdomain, which is why repositories must be named this way even if a custom domain is being used.

Project Pages

Unlike user and organization Pages, Project Pages are kept in the same repository as the project they are for, except that the website content is stored in a specially named gh-pages branch or in a docs folder on the master branch. The content will be rendered using Jekyll, and the output will become available under a subpath of your user pages subdomain, such as username.github.io/project (unless a custom domain is specified).

The Jekyll project repository itself is a perfect example of this branch structure—the master branch contains the actual software project for Jekyll, and the Jekyll website that you’re looking at right now is contained in the docs folder of the same repository.

Please refer to GitHub official documentation on user, organization and project pages to see more detailed examples.

Source files must be in the root directory

GitHub Pages overrides the "Site Source" configuration value, so if you locate your files anywhere other than the root directory, your site may not build correctly.

Running and Testing Locally

Running Rustyll locally gives you significant speed advantages. Here’s how to configure your environment:

# Install Rustyll
cargo install rustyll

# Run with the baseurl set to match GitHub Pages
rustyll serve --baseurl=""

# For even faster development with live reload
rustyll serve --baseurl="" --livereload --incremental

This will run the Rustyll server on your local machine at http://localhost:4000. Refer to server options for available options.

Optimizing Build Speed with Rustyll

To get the most out of Rustyll when working with GitHub Pages:

1. Use Rustyll’s parallel builds locally:

   rustyll build --threads auto
   

2. Enable incremental builds for faster feedback:

   rustyll serve --incremental
   

3. Create a local config override to keep GitHub Pages compatibility:

   # _config_dev.yml
   baseurl: ""
      
   # Rustyll performance options (local only)
   threads: auto
   parallel: true
   cache:
     enabled: true
     strategy: aggressive
   

   Then run:

   rustyll serve --config _config.yml,_config_dev.yml
   

4. For complex sites, consider setting up a continuous integration pipeline with GitHub Actions to deploy pre-built sites.