personal-jekyll-theme: a Jekyll blog theme with a timeline at its centre

A fork of Timeline with a longer feature list

The { Personal } theme is described as a free, responsive Jekyll theme with a minimal aesthetic, aimed at a personal blog and portfolio, with a timeline for telling your story and a blog for sharing thoughts. The visual language is minimal, described in the feature list as modern with white-on-black text, and it ships a dark mode toggle whose preference is saved in localStorage.

Its lineage is documented in the credits, which is unusual to find in a theme and useful for judging what you are adopting. This project is a fork of Timeline by kirbyt, which is itself a mashup of Grayscale by Start Bootstrap and the Agency Jekyll Theme. So the visual base comes from established themes and the work here is the fork's own additions: the tag and category system with its generation scripts, the Docker workflow, the cookie consent banner, the share buttons, the Mermaid support and the conventional-commit release pipeline.

The technical baseline is small and specific. The Ruby badge pins 3.1.1, the licence is Apache 2.0 with the LICENSE file in the repository root, and the default branch is develop. That last detail has a practical consequence for the GitHub Pages instructions: a fork brings the develop branch across, not a tagged release.

The project publishes a live demo at le4ker.github.io/personal-jekyll-theme/, and the documentation is delivered as blog posts on that same demo site rather than as a separate manual.

Docker removes Ruby from your machine entirely

The README offers two development routes and recommends the first. Running the site locally with Docker needs one command:

docker-compose up --build

The site is then available at http://localhost:4000. The compose file in the repository shows what that command actually does. The service is named blog, it builds from the local directory, it pins the platform to linux/amd64, it maps port 4000 on the host to 4000 in the container, and it mounts the working directory into the container so your edits are picked up live.

services:
  blog:
    build: .
    platform: linux/amd64
    ports:
      - "4000:4000"
    volumes:
      - .:/srv/jekyll
    command: bundle exec jekyll serve --host 0.0.0.0 --livereload --force_polling

The Dockerfile explains the rest. It starts from the jekyll/jekyll:4.2.2 image, installs the bundle, and runs two Ruby scripts from bin/ during the build to generate the tags and the categories:

RUN ruby bin/generate_tags.rb && ruby bin/generate_categories.rb

Those two scripts are the mechanical heart of the tagging feature. Categories and tags are not hand-written lists; they are produced from your posts during the build. That is why the generated output lives in the categories/ and tags/ directories in the repository root, alongside feed.xml, sitemap.xml and manifest.json.

The host mount is also why the container workflow suits an author: the same directory is both your source and the served site, so there is no copy step to forget.

Native Ruby development when you want the real toolchain

If you would rather work with the actual Jekyll toolchain, the second option asks for two prerequisites: Ruby 3.1.1, with rbenv or rvm suggested for version management, and Bundler. The installation is two commands:

# Install dependencies
bundle install

# Start the development server with live reload
bundle exec jekyll serve --watch --livereload

Again the site comes up at http://localhost:4000.

The difference between the two routes is not only convenience. The Docker image pins jekyll/jekyll:4.2.2 and a Gemfile.lock, so you get the same Jekyll version every time regardless of what is on your laptop. The native route installs the bundle from the same Gemfile.lock but against your own Ruby 3.1.1, which means your system Ruby version, your Bundler version and your native gems become part of the build. For an author who already has Ruby set up, that is the faster path. For a machine you want to leave untouched, the container is the better one.

The Gemfile and Gemfile.lock are committed at the repository root, so both routes resolve the same dependency set.

Deploying by forking the repository to your own account

The GitHub Pages route is the shortest path in the README, and it works by turning your fork into the site repository. The steps are four.

First, fork the repository. Second, rename the fork to yourusername.github.io, which is the naming convention GitHub Pages expects for a user site. Third, update _config.yml with the two keys that tell Jekyll where it lives:

url: "https://yourusername.github.io"
baseurl: ""

Fourth, commit. The README states that once the GitHub Action succeeds, the site is live at https://yourusername.github.io. The build badge in the README points at a workflow named release.yml, so the publishing pipeline runs in GitHub Actions rather than on a machine you maintain.

Two details deserve attention. The baseurl value is empty for a user site, but the key exists precisely because a project site served from a subpath needs it filled in, and forgetting it is the classic reason a forked Jekyll site renders with broken asset paths. And the default branch of this repository is develop, so what your fork actually deploys is the develop branch unless you change the branch in the workflow settings or merge into the branch the action watches.

The 404.html file at the repository root is a second sign of a Pages-focused project, since GitHub Pages serves that file for missing paths.

Everything the author configures lives in _config.yml

The configuration table is short and that is the point. The README says all site configuration is managed through _config.yml, and the key settings are listed in a single table.

Two of the entries are the deployment keys, url and title, with title described as the site title displayed in the header. The next group is personal: author for your name, description for the site description used for SEO, and me-img for your profile image. The last two are content: background-img for the header background image, events for the timeline entries, and social for social media links.

The mapping is direct. The events list feeds the timeline that is the theme's distinguishing feature, so a milestone with an image, a date and a description is a data entry in _config.yml rather than a layout change. The social list feeds the share buttons and the links in the header.

The repository layout shows how a Jekyll theme is put together. _layouts/ and _includes/ hold the HTML templates, _sass/ the styling, _posts/ the blog entries, and bin/ the two generator scripts. The pages are plain top-level files, index.html, blog.html, timeline.html, about.html and contact.html, and the supporting output includes feed.xml for RSS, sitemap.xml for search engines and manifest.json for the progressive web app metadata.

The README does not document how to add a new page type, change a layout, or extend the generator scripts, so anything beyond the eight listed keys means reading Liquid templates.

What the theme covers, and the conventions it imposes

The feature list is broader than the minimal aesthetic suggests. On the design side there is the dark mode toggle, a fully responsive layout for mobile, tablet and desktop, and a customisable header with dynamic text and a profile image. The timeline supports images, dates and descriptions per milestone.

The blogging side has an archive page, hashtags and categories, comments through Cusdis with dark and light theme sync, social share buttons for X, Facebook, LinkedIn, Reddit and Hacker News, syntax highlighting for code blocks, Mermaid diagram support and an RSS feed. On the operational side there is Google Analytics integration, automatic sitemap generation, SEO-friendly meta tags, a cookie consent banner and email harvesting protection.

The project also imposes a contribution convention, which matters if you plan to fork and maintain it. It uses Conventional Commits to generate release notes automatically, the allowed types being feat, fix, docs, style, refactor, perf, test, build, ci, chore and revert, and there is a local git hook you can install to enforce the format before each commit:

sh .githooks/setup.sh

That script makes git validate your commit messages. Combined with the release workflow, it explains the version history: v10.3.2 on 2026-01-04, v10.4.0 on 2026-01-17 and v10.4.1 on 2026-03-01. The last push was on 2026-09-26, so commits continue after the newest tag.

For an author who only wants a blog, none of this matters. For anyone extending the theme, the Conventional Commits rule is a constraint on your own workflow, and the Apache 2.0 licence is permissive enough to modify and redistribute with the notice kept.

Editorial conclusion

personal-jekyll-theme fits a developer who wants one personal blog and portfolio site running on GitHub Pages without writing Liquid templates, and who is comfortable forking a repository and configuring _config.yml. It is the wrong choice for a multi-author publication with per-page layouts, a non-GitHub Pages host that expects a different build, or a team that needs the theme's default branch develop to behave like a released version. Before you build on it, note that the repository default branch is develop while the newest release is v10.4.1 from 2026-03-01, check that your _config.yml events and social entries render the way you expect, and confirm the Ruby 3.1.1 toolchain matches your build environment.

Frequently asked questions

Official sources

1. le4ker/personal-jekyll-theme on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases