Getting Started

Creating a Site Repository

You have two options:

Option 1. Using the Starter (Recommended)

Simplifies upgrades, isolates unnecessary files, and lets you focus on writing with minimal configuration.

1. Sign in to GitHub and go to the starter.
2. Click Use this template > Create a new repository.
3. Name the repository <username>.github.io, replacing username with your lowercase GitHub username.

Option 2. Forking the Theme

Convenient for modifying features or UI, but harder to upgrade. Only choose this if you know Jekyll and plan to heavily modify the theme.

1. Sign in to GitHub.
2. Fork the theme repository.
3. Name the repository <username>.github.io, replacing username with your lowercase GitHub username.

Setting up the Environment

With the repository created, set up your development environment one of two ways:

Using Dev Containers (Recommended for Windows)

Dev Containers give you an isolated Docker environment that avoids system conflicts and manages all dependencies inside the container.

Steps:

1. Install Docker:
   • Windows/macOS: Docker Desktop.
   • Linux: Docker Engine.
2. Install VS Code and the Dev Containers extension.
3. Clone your repository:
   • Docker Desktop: start VS Code and clone your repo in a container volume.
   • Docker Engine: clone your repo locally, then open it in a container via VS Code.
4. Wait for the setup to complete.

Setting up Natively (Recommended for Unix-like OS)

On Unix-like systems, a native setup gives the best performance; Dev Containers also work.

Steps:

1. Follow the Jekyll installation guide and make sure Git is installed.
2. Clone your repository locally.
3. If you forked the theme, install Node.js and run bash tools/init.sh in the root to initialize the repository.
4. Run bundle in the repository root to install dependencies.

Usage

Start the Jekyll Server

Run the site locally:

$ bundle exec jekyll serve

With Dev Containers, run this in the VS Code Terminal.

After a few seconds the site is available at http://127.0.0.1:4000.

Configuration

Update _config.yml as needed. Common options:

• url
• avatar
• timezone
• lang

Social Contact Options

Social contacts appear at the bottom of the sidebar. Enable or disable them in _data/contact.yml.

Customizing the Stylesheet

Copy the theme’s assets/css/jekyll-theme-chirpy.scss to the same path in your site, then append your custom styles.

Customizing Static Assets

Static assets configuration arrived in 5.1.0. Their CDN is defined in _data/origin/cors.yml; replace entries to suit the network conditions where your site is published.

To self-host the static assets, see the chirpy-static-assets repository.

Deployment

Before deploying, check _config.yml and set url correctly. For a project site without a custom domain, or to serve under a base URL on a non-GitHub Pages server, set baseurl to your project name with a leading slash, e.g. /project-name.

Now choose one of the following methods.

Deploy Using Github Actions

Prepare the following:

• On the GitHub Free plan, keep the site repository public.

• If you committed Gemfile.lock and your machine isn’t Linux, add the Linux platform:

  $ bundle lock --add-platform x86_64-linux
  

Then configure Pages:

1. On GitHub, open Settings > Pages. Under Build and deployment > Source, select GitHub Actions.
   

2. Push a commit to trigger the workflow. In the Actions tab, watch Build and Deploy run; on success the site deploys automatically.

Visit the URL GitHub provides to see your site.

Manual Build and Deployment

For self-hosted servers, build locally and upload the output.

From the project root, build the site:

$ JEKYLL_ENV=production bundle exec jekyll b

Unless you set another output path, the files land in _site. Upload them to your server.