Skip to content
A Jekyll theme with responsive web design that focuses on text presentation.
CSS HTML JavaScript Python Shell Ruby
Branch: master
Clone or download
Latest commit 29fd4cf Jan 25, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Optimize workflow. Jan 25, 2020
_data Update label in posts. Jan 13, 2020
_includes Update label in posts. Jan 13, 2020
_layouts Fixed related URL. Jan 13, 2020
_posts Updated the Docs. Jan 23, 2020
_scripts Move the CI to Github Actions. Jan 23, 2020
assets Beautified the ToC. Jan 14, 2020
docs Updated the Docs. Jan 23, 2020
tabs Added more project info in files. Jan 13, 2020
tools Updated the CI config. Jan 20, 2020
.gitignore Added a new script tool to compress JS. Jan 13, 2020
.travis.yml Move the CI to Github Actions. Jan 23, 2020
Gemfile Updated seo-tag settings. Jan 13, 2020
LICENSE Updated the Docs. Jan 23, 2020
_config.yml Updated README and tutorial. Jan 13, 2020
index.html Updated seo-tag settings. Jan 13, 2020
robots.txt Added more project info in files. Jan 13, 2020
sitemap.xml Code optimization. Jan 13, 2020

Jekyll Theme Chirpy

Build Status GitHub license

Language: English | 简体中文

A minimal, portfolio, sidebar, bootstrap Jekyll theme with responsive web design and focuses on text exhibition. It will help you easily record, manage and share your knowledge and experience.

You will get the following features:

  • Auto Dark Mode
  • Posts' Last Modified Date
  • Table of Contents
  • Automatically Recommend Related Posts
  • Syntax highlighting
  • Two Level Categories
  • Search
  • Atom Feeds
  • Disqus Comments
  • Google Analytics
  • GA Pageviews (Advanced)
  • SEO Tag
  • Performance Optimization

Live Demo »


Table of Contents



Follow the Jekyll Docs to complete the installtion of basic environment (Ruby, RubyGem, Bundler and Jekyll). In order to use the script tools to save time, we also need to install Python(version 3.5 or abover) and ruamel.yaml.

In addition, if your machine is running Debian or macOS, make sure you have the GNU coreutils installed. Otherwise, get it by:

  • Debian
$ sudo apt-get install coreutils
  • macOS
$ brew install coreutils

Jekyll Plugins

Fork Chirpy from GitHub, then clone your forked repo to local:

$ git clone

replace the USER above to your GitHub username.

The first time you run or build the project on your machine, perform the installation of Jekyll plugins. Go to the root of repo and run:

$ bundle install

bundle will automatically install all the dependent Jekyll Plugins that listed in the Gemfile.


Directory Structure

The main files and related brief introductions are listed below.

├── _data
├── _includes      
├── _layouts
├── _posts          # posts stay here
├── _scripts
├── .travis.yml     # remove it
├── .github         # remove this, too
├── assets      
├── tabs
│   └──    # the ABOUT page
├── .gitignore
├── 404.html
├── Gemfile
├── _config.yml     # configuration file
├── tools           # script tools
├── docs
├── feed.xml
├── index.html
├── robots.txt
└── sitemap.xml

As mentioned above, some files or directories should be removed from your repo:

  • .travis.yml
  • .github


Basically, go to _config.yml and customize the variables as needed, some of them are typical options:

  • Avatar

    avatar defines the source image location. The sample image is /assets/img/sample/avatar.jpg. It should be replaced by your own one. Notice that a huge image file will increase the load time of your site, so keep your avatar size as samll as possible(may be will help).

  • TimeZone

    To ensure that the posts' release date matches the city you live in, please modify the field timezone correctly. A list of all available values can be found on TimezoneConverter or Wikipedia.

Run Locally

You may want to preview the site before publishing, so just run the script tool:

$ bash tools/

Open a modern brower and visit at http://localhost:4000.

Few days later, you may find that the file modification(e.g. edits to a post) does not refresh in real time by using Don't worry, the advanced option -r (or --realtime) will solve this problem, but it requires fswatch to be installed on your machine. Type -h for more information.

Deploying to GitHub Pages

Before the deployment begins, ensure the url in file _config.yml has been set to https://<username> the custom domain, if you have. e.g. What's more, if you prefer to the Project site, change baseurl of file _config.yml to your project name, starting with a slash. e.g. /project.

Option 1: Built by GitHub Pages

By deploying the site in this way, you're allowed to push the source code directly to the remote.

Note: If you want to use any third-party Jekyll plugins that not in this list, stop reading the current approach and go to Option 2: Build locally.

1. Rename the repository to:

Site Type Repo's Name
User or Organization <username>
Project any one except <username>, let's say project

2. Commit the changes of the repo first, then run the initialization script:

$ bash tools/

Note: The Recent Update requires the posts' latest git-log date, so make sure the changes in _posts have been committed before running this command.

it will automatically generates the Latest Modified Date and Categories / Tags page for the posts.

3. Push the changes to origin/master then go to GitHub website and enable GitHub Pages service for the repo.

4. Check it out:

Site Type Site URL
User or Organization https://<username>
Project https://<username>

Option 2: Build Locally

For security reasons, GitHub Pages runs on safe mode, which means the third-party Jekyll plugins or custom scripts won't work. If you want to use any another plugins that not in the whitelist, you have to generate the site locally rather than on GitHub Pages.

1. Browse to GitHub website, create a brand new repo named:

Site Type Repo's Name
User or Organization <username>
Project any one except <username>, let's say project

and clone it.

2. In the root of the source project, build your site by:

$ bash tools/ -d /path/to/local/project/

The generated static files will be placed in the root of /path/to/local/project. Commit and push the changes to the master branch on GitHub.

3. Go to GitHub website and enable Pages service for the new repository.

4. Visit at:

Site Type Site URL
User or Organization https://<username>
Project https://<username>

and enjoy!


For more details and the better reading experience, please check out the tutorial in demo site. In the meanwhile, a copy of the tutorial is also available on the Wiki.


The old saying: "Tow heads are better than one. Five heads are better than two." So, welcome to report bugs, improve code quality or submit a new feature. For more information, see contributing guidelines.


This theme is mainly built with Jekyll ecosystem, Bootstrap, Font Awesome and some other wonderful tools(their copyright information can be found in the relevant files).

🎉Thanks to all the volunteers who contributed to this project, their github ID is on this list. Also, I won't forget the guys who submitted the issues(or unmerged PR), they reported bugs, shared ideas or inspired me to write more readable documentation.


If you enjoy this theme or find it helpful, please consider becoming my sponsor, I'd really appreciate it! Click the button ❤️Sponsor at the top of the Home Page and choose a link that suits you to donate. This will encourage me and help me maintain this project.


This work is published under MIT License.

You can’t perform that action at this time.