Born in five files (and a borrowed wardrobe)

I was born with five files. I want that on the record before anyone calls this a website.

Here is the entire founding repository:

.
├── _config.yml
├── Gemfile
├── index.md
├── CNAME
└── .gitignore

That is it. No layouts. No stylesheets. No JavaScript. No logo. The thing you are looking at right now — the navbar, the typography, the spacing, whatever color the links are — none of that lives here. It is rented.

The trick is one line in _config.yml:

remote_theme: bamr87/zer0-mistakes

That line tells GitHub Pages, at build time, to go fetch a whole wardrobe from someone else’s repo and wear it. The jekyll-remote-theme plugin pulls the theme down during the build, dresses up these five files, and ships the result. The site stays tiny because the clothes never get committed here. They show up, do the runway walk, and leave.

# Gemfile — the part that makes the borrowing legal
gem "github-pages", group: :jekyll_plugins
gem "jekyll-remote-theme"

# _config.yml — plugins must be declared or the theme stays naked
plugins:
  - jekyll-remote-theme

It feels like cheating. It is not cheating. It is just renting.

What a remote theme actually hands you

This is the part nobody tells you, so I will, because I learned it the hard way and the hard way is the whole point of this site.

A Jekyll remote theme delivers exactly four directories into your build:

_layouts/    → the page skeletons
_includes/   → the reusable chunks (navbar, footer, head)
_sass/       → the styling
assets/      → CSS, JS, fonts, images the theme needs

That’s the wardrobe. Beautiful. Comprehensive. Wearable on arrival.

Here is what it does not deliver:

_config.yml  → the theme's own settings: NOT yours
_data/       → the theme's navigation, author lists, content: NOT yours
_plugins/    → the theme's custom Ruby: NOT yours

The theme repo has all three. You get none of them. Remote themes ship the clothes and keep the address book, the silverware, and the personality at home.

Which is why the first thing I rendered was a wizard

The very first build of lifehacker.dev did not show a homepage. It showed an onboarding screen — a cheerful little welcome wizard explaining how to configure the site.

I panicked for exactly four seconds. Then I read the theme’s default config and found this:

site_configured: false

The theme ships that flag set to false. When it’s false, the layout shows the welcome-wizard onboarding screen instead of your content. It is a default living inside the theme’s _config.yml — the one file the remote theme does not hand you. So until I set my own value, I inherited the factory setting: “this person has not configured anything yet.”

The fix is one line in my _config.yml, which overrides the theme’s:

site_configured: true

Same story with the navbar showing up nearly empty. The links the theme draws come from its _data/navigation.yml — which, again, did not come with the wardrobe. An empty navbar is not a broken navbar. It is a navbar politely waiting for me to bring my own _data/.

None of this is a bug. It is a fresh site wearing the theme’s default outfit with absolutely none of its own data packed.

When this goes wrong: if you see an onboarding screen, a blank navbar, or unstyled-looking defaults, check whether you’ve overridden the theme’s _config.yml values and created your own _data/ files. The theme’s copies exist; they’re just not in your repo. Look at the theme repo on GitHub to see what keys and data files it expects, then re-create the ones you need locally.

The furnished-apartment problem

The cleanest way I can describe a remote theme is this.

You move into a furnished apartment. The furniture is gorgeous and it is not yours — and it only teleports in when guests arrive. The moment the build runs, the couch appears. The moment the build ends, it vanishes back to the landlord’s repo.

But the apartment comes with no silverware, no address book, and no personality. Those you bring yourself, in your own _config.yml and your own _data/. The theme furnishes the room. You still have to move in.

I am, as of this writing, mostly someone else’s clothes held together by one config file and optimism. I think that’s a fine way to be born.

---

Next field note: the build broke, loudly, in front of everyone, and the error message was lying to me. Read about it in the next entry.

If you want the full inventory of what this site is wearing and who made it, that lives in the colophon.