# chirpy-starter: the files RubyGems cannot ship you

> The chirpy-starter repository exists because a Jekyll theme installed as a gem can only expose a subset of its files, so users of the Chirpy theme never get the full experience. The starter bundles the missing files, adds a continuous deployment workflow, and is refreshed automatically from the theme repository.

**cotes2020/chirpy-starter** — A starter template for Jekyll sites using the Chirpy theme.

- Repository: https://github.com/cotes2020/chirpy-starter
- Website: https://chirpy.cotes.page
- Stars: 1,113 · Forks: 600
- Language: Shell
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/cotes2020-chirpy-starter

## Why a gem install is not the same as the theme

A Jekyll theme distributed as a RubyGems package looks like it gives you the theme, and it does not. The reason is in how Jekyll loads a theme. When Chirpy is installed from RubyGems, Jekyll can only read a subset of the theme's files, which are _data, _layouts, _includes, _sass, and assets, plus a limited set of _config.yml options from the gem. Everything else in the theme is simply not visible to the site.

The result is a specific kind of disappointment. The theme is advertised with features that the gem install does not deliver, and the user is left comparing what they expected against what rendered. The README is blunt about the consequence: users cannot enjoy the full out-of-the-box experience that Chirpy offers.

That is the entire reason this repository exists. cotes2020/chirpy-starter is described as a minimal, ready-to-use template for creating a blog with the Chirpy Jekyll theme, and the framing in the README is that it gets you up and running in minutes with all critical files pre-configured. It is not a new theme, it is not a fork, and it does not change the look of anything. It fills in the gap that the gem packaging leaves.

The project is MIT licensed, its primary language is listed as Shell, and its home page is chirpy.cotes.page. The theme itself is a separate project, with its own repository and its own documentation wiki, and the starter points you there for the usage instructions.

## The four files that make the difference

The missing pieces are listed precisely, and they are the files a Jekyll site has to own rather than borrow:

```shell
.
├── _config.yml
├── _plugins
├── _tabs
└── index.html
```

Each one has a specific job. The _config.yml is the site configuration, and it is the file that decides which theme options apply, so owning it means the full set of options is available rather than the limited subset the gem exposes. The _plugins directory holds the Jekyll plugins the theme relies on, and RubyGems-installed themes cannot ship those because Jekyll does not load plugins from a theme gem. The _tabs directory is the theme's navigation tab content. And index.html is the landing page, which in this theme is generated from those tabs.

The starter bundles those files from the latest Chirpy release, and the README adds a continuous deployment workflow on top, so the stated promise is that you can start writing immediately rather than assembling the pieces yourself.

The repository layout confirms the story. Alongside the four files above there is a _data directory, an assets directory, a _posts directory for your articles, a Gemfile, a .nojekyll file, an .editorconfig, a .devcontainer directory, a .vscode directory, a .github directory, a tools directory, and a .gitmodules file. The .gitmodules entry is worth noticing in a repository like this, since a submodule declaration means some content is tracked by reference to another repository rather than copied in.

## A repository that is regenerated, not hand-edited

The contributing section contains the sentence that changes how you should treat this repository. It is automatically updated with new releases from the theme repository, and the instruction for anyone with an issue or an improvement is to visit the theme repository to provide feedback.

That is a different maintenance model from a normal starter template. There is no fork-and-diverges workflow, and the release script that pulls in theme updates is the mechanism by which the starter stays current. A pull request opened here is not a pull request that will be merged into a living fork, it is feedback that belongs upstream in cotes2020/jekyll-theme-chirpy.

The practical consequence for an adopter is that your site is a working copy of upstream files, and changes you make to the bundled _config.yml, the plugin files, the tabs, or index.html are changes that a later automatic update may conflict with. The design of the theme is that _config.yml is yours to edit, since that is what makes it your site, but the plugin and tab files are more likely to be overwritten. If you need to change a plugin file, the honest path is to make the change in the theme repository and let it come back down through a release, or to keep your modification small and obvious in review.

The last push to this repository was on 2026-06-20, and there are no GitHub releases, which is consistent with a repository whose artefacts are the theme's releases rather than its own tags.

## The devcontainer and the GitHub workflow

The.devcontainer directory is a modern touch on an otherwise traditional Jekyll project. A devcontainer gives you a defined environment, with the toolchain, the editor, and the extensions pinned in a configuration file, so a contributor's local setup matches the one the project expects. The repository also carries a.vscode directory, which is the conventional way to share editor settings, and a.nojekyll file, which tells GitHub Pages not to run its own Jekyll processing, a necessary detail when the build output is produced by your own workflow rather than by the platform.

The.github directory holds the continuous deployment workflow the README mentions. The specifics are not spelled out in the README, so the providers, the trigger, and the deployment target have to be read from the workflow file itself, and that is the first thing to check after cloning if you host somewhere other than the default.

The Gemfile is the dependency manifest, and the _posts directory is where articles go, which is the part of the layout you will actually touch daily. The tools directory is where helper scripts live, and the assets directory holds the static files the theme expects.

For the actual setup steps, the README does not give commands. It points to the theme's documentation wiki at the cotes2020/jekyll-theme-chirpy repository, which is where the install and run instructions live, and that is the right place to look since the theme is the thing that defines the toolchain.

## Against the plain gem, and against building from the theme

There are two reasonable alternatives, and both are worse in specific ways.

The first is to add the gem to your Gemfile and use the theme as Jekyll sees it. The difference in approach is that the gem gives you the files Jekyll allows, and only those. You get layouts, includes, sass, assets, and a partial set of configuration options, and the features that depend on the missing files are simply unavailable. The benefit is a dependency declared in your Gemfile rather than a directory of files copied from a repository, and if the missing features are not ones you need, that is a perfectly reasonable trade.

The second is to clone the theme repository itself and build from it. That gives you everything the theme contains, including the parts the starter does not bundle, but it also means you are tracking the theme's development branch rather than its releases, and you own the whole thing. For someone who wants to modify the theme, that is the correct starting point. For someone who wants to write a blog, it is a larger surface than the starter offers.

The starter sits between the two. It gives you the release version of the files, in a site layout, with the deployment workflow already configured, and it keeps itself in step with the theme without you doing anything. What it costs is the automatic update behaviour described earlier, where your edits to the bundled files can collide with an upstream refresh.

The choice comes down to one question: do you need the features that require _plugins, _tabs, and index.html? If the answer is yes, the gem install cannot give them to you and the starter is the shortest path. If the answer is no, the gem is less machinery.

## Conclusion

Adopt chirpy-starter if you want the full Chirpy feature set rather than the gem subset, and if you are comfortable with a repository that is regenerated from an upstream theme. Do not adopt it if you would rather depend on the gem and accept the limited file set. Verify first that the continuous deployment workflow in the .github directory targets the hosting you use, since the README describes the workflow without listing its providers.

## FAQ

### Why do I need chirpy-starter instead of installing the Chirpy theme gem?

When Chirpy is installed through RubyGems, Jekyll can only read a subset of the theme files, namely _data, _layouts, _includes, _sass, and assets, plus a limited set of _config.yml options. The starter bundles _config.yml, _plugins, _tabs, and index.html so the full theme works.

### Where do I find the setup and usage instructions for chirpy-starter?

The README points to the theme's documentation wiki in the cotes2020/jekyll-theme-chirpy repository, and it does not print setup commands itself. The starter bundles the files from the latest Chirpy release along with a continuous deployment workflow.

### How is chirpy-starter kept up to date?

The repository is automatically updated with new releases from the theme repository, and the README says feedback and improvements belong in the theme repository rather than here. The last push to the repository was on 2026-06-20, and there are no GitHub releases.

### Can I change the files that chirpy-starter bundles?

The README says the repository is automatically updated with new releases from the theme, so local edits to the bundled files can be overwritten by an upstream refresh. For changes to a plugin or tab file, the theme repository is the place to contribute them.

### What licence is chirpy-starter published under?

MIT, as stated in the README and with the LICENSE file linked from it. The theme itself is distributed separately as the jekyll-theme-chirpy gem.

## Sources

- [cotes2020/chirpy-starter on GitHub](https://github.com/cotes2020/chirpy-starter)
- [Issues](https://github.com/cotes2020/chirpy-starter/issues)
- [License: MIT](https://github.com/cotes2020/chirpy-starter/blob/main/LICENSE)
- [Project website](https://chirpy.cotes.page)
- [README](https://github.com/cotes2020/chirpy-starter/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cotes2020-chirpy-starter