Skip to content
Get packs

Guide · Open source

How to use jekyll-theme-chirpy: setup and writing guide

Updated · written with AI from the project's own documentation and checked against our catalogue data

jekyll-theme-chirpy is an MIT-licensed Jekyll theme for building a technical blog. It gives you a ready-made layout with dark and light modes, syntax highlighting, math and Mermaid diagram support, search and a table of contents. This guide covers what you need installed, how to get the repository, how posts are written, and where to find the full documentation.

Chirpycotes2020/jekyll-theme-chirpy · ★ 10.3k · MIT

Quick start

  1. 1Install Ruby and RubyGems. Install Ruby and RubyGems on your computer, since Jekyll depends on them.
  2. 2Install Jekyll. Install Jekyll so you can build and preview the site locally.
  3. 3Clone the repository. Run git clone https://github.com/cotes2020/jekyll-theme-chirpy.git to download the theme files.
  4. 4Read the wiki. Open the project wiki for the setup, development and upgrade steps the README points to.
  5. 5Write a post in Markdown. Create your post as a Markdown file and add code, math or Mermaid diagrams where needed.
  6. 6Check the demo. Compare your result with the live demo to confirm the layout and features work as expected.

What you need before you start

Chirpy is a theme for Jekyll, a tool that turns text files into a static website. Because of that, you need Jekyll and its Ruby tooling on your machine before the theme can run. The project lists Ruby and RubyGems, plus Jekyll, as prerequisites.

The README assumes some technical comfort. If you have never used a command line or Ruby before, expect a learning curve during setup.

  • Ruby and RubyGems
  • Jekyll
  • Git, to clone the repository

Get the theme source code

The README's install instruction is to clone the repository from GitHub. Run the command below in the folder where you want your site to live. It creates a folder containing the theme files.

git clone https://github.com/cotes2020/jekyll-theme-chirpy.git

Learn setup, development and upgrades in the wiki

The project's documentation is kept in its GitHub wiki. The README points there for how to use, develop, and upgrade the project, so use it as the reference for configuration steps beyond cloning.

The live demo at cotes2020.github.io/chirpy-demo is linked from the README. Browsing it shows you the layout and features before you commit to the theme.

Write posts in Markdown

You write each post as a Markdown file and the theme handles the look and layout. You do not need to design pages or write HTML for ordinary posts. Features the README lists for content include pinned posts, hierarchical categories, trending tags, an auto-generated table of contents, and last modified dates.

For technical content, the rich text features matter most: syntax highlighting for code, mathematical expressions, Mermaid diagrams and flowcharts, and embedded media.

  • Syntax highlighting for code blocks
  • Mathematical expressions
  • Mermaid diagrams and flowcharts
  • Embedded media

Check the features you will rely on

The theme also includes responsive layout, localized UI language, dark mode images, built-in search, support for multiple comment systems, Atom feeds, PWA support, integrated web analytics and SEO features. Confirm the exact settings for each in the wiki, since the README only lists them.

  • Responsive layout with dark and light modes
  • Built-in search
  • Multiple comment systems
  • Atom feeds
  • PWA support
  • Integrated web analytics

What people use it for

  • A developer publishing a technical blog about code without designing a site from scratch
  • A writer who needs code highlighting, math expressions or Mermaid diagrams in articles
  • A team hosting a documentation-style blog for free on static hosting

Frequently asked questions

Is jekyll-theme-chirpy free?

Yes, it is licensed under the MIT License, as stated in the README. The license file is in the repository's LICENSE file on GitHub.

What do I need installed to use jekyll-theme-chirpy?

The project lists Ruby and RubyGems, plus Jekyll, as prerequisites. You also need Git to clone the repository with the command in the README.

Do I need to know how to code to use Chirpy?

The README says it assumes some technical comfort, and it points to a wiki and Jekyll setup for configuration. If you want a visual builder with no code, Chirpy is not designed for that.

Can I use Chirpy for a site with user accounts or a database?

No. Jekyll produces static pages, so Chirpy is not suited to a dynamic app with user accounts or databases.

Does Chirpy support math and diagrams?

Yes. The README lists mathematical expressions and Mermaid diagrams and flowcharts among its rich text features.

What are alternatives to jekyll-theme-chirpy?

Comparable projects named in the analysis are Jekyll Now, Minimal Mistakes, Hugo Stack and Docusaurus. Pick based on whether you want a Jekyll theme specifically and how much technical setup you accept.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Chirpy suits developers and technical writers who already know Jekyll or Ruby and want a polished blog with code, math and diagram support, hosted for free on static hosting. If you want a no-code site builder or a dynamic app with accounts and databases, choose a different tool.

Install options & downloads