Plan: New Custom Theme for tekkie.github.io

Plan: New Custom Theme for tekkie.github.io

Context

The site currently uses just-the-docs (a documentation theme) for a personal CV + blog — a mismatch. It has zero custom layouts, CSS, or includes; all styling comes from the theme gem. The theme doesn’t support the typographic ambition in CLAUDE.md, produces a generic docs look, and has no CI/CD (deployment is branch-based, no GitHub Actions). This plan replaces it with a bespoke Jekyll theme that expresses a strong visual identity.

Font Decision

Bricolage Grotesque (variable, 200–800) + JetBrains Mono

  • Bricolage Grotesque at weight 800 for headings: distinctive geometric grotesque with quirky ink-trap details, strong modern personality
  • Bricolage Grotesque 200 for taglines/subtitles: extreme weight contrast within the same family
  • JetBrains Mono for nav, dates, metadata, code: technical precision counterpoint
  • Load via Google Fonts (two-step preconnect pattern)
  • Weights used: body = 400, subtitles = 200, subheadings = 500, headings = 700, hero = 800

Google Fonts import:

https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,200..800&family=JetBrains+Mono:wght@400;700&display=swap

Color palette:

  • Background: #fafaf8 (warm off-white)
  • Text: #1a1a1a
  • Accent: #0d6e6e (deep teal for CTAs, active states, borders)
  • Accent dark: #0a5252 (hover state)
  • Muted: #6b6b6b (dates, meta, secondary)

Files Created

.github/workflows/deploy.yml        GitHub Actions CI/CD
_layouts/base.html                  Root HTML shell
_layouts/default.html               Fallback single-column page
_layouts/home.html                  Hero + feature blocks
_layouts/page.html                  Static pages (contact)
_layouts/post.html                  Blog post reading view
_layouts/blog.html                  Post listing index
_layouts/cv-section.html            CV with sidebar + breadcrumb
_includes/head.html                 <head> contents + Google Fonts
_includes/nav.html                  Sticky nav bar (CSS-only mobile hamburger)
_includes/footer.html               Copyright + social links
_includes/breadcrumb.html           CV hierarchy breadcrumb
_includes/post-card.html            Reusable post preview card
_sass/_variables.scss               Design tokens (colors, fonts, spacing, scale)
_sass/_base.scss                    Reset, html/body defaults
_sass/_typography.scss              All type rules (Bricolage Grotesque + JetBrains Mono)
_sass/_nav.scss                     Navigation bar styles
_sass/_layout.scss                  Container, grid, page structure
_sass/_home.scss                    Hero, feature blocks
_sass/_cv.scss                      CV sidebar, breadcrumb, entries
_sass/_blog.scss                    Post list, post cards
_sass/_post.scss                    Individual post reading styles
_sass/_utilities.scss               .float-right, .text-right, .clearfix, .sr-only
assets/css/main.scss                SCSS entry point (Jekyll processes via front matter ---)

Files Modified

Gemfile

  • Removed: gem "just-the-docs", gem "minima", "~> 2.5"
  • Added to :jekyll_plugins group: gem "jekyll-seo-tag", gem "jekyll-sitemap"
  • Kept: jekyll, jekyll-feed, webrick, platform-specific gems

_config.yml

  • Removed: theme: just-the-docs, search_enabled, search: block, heading_anchors, back_to_top, back_to_top_text, compress_html
  • Changed: url: "" → url: "https://tekkie.ro"
  • Added: permalink: /blog/:year/:month/:day/:title/, sass: block, author: block with name/tagline/location, jekyll-sitemap to plugins

Content front matter layout changes + JTD class removal

File Layout change Notes
index.markdown default → home Stripped JTD classes, rewrote as clean prose + HTML buttons
contact.markdown page → page Already correct
blog/blog.markdown default → blog None
cv/cv.markdown default → cv-section None
cv/education.markdown default → cv-section Replaced .fs-5 .float-right .text-right with <div class="text-right">
cv/experience.markdown default → cv-section None
cv/experience/asml.markdown default → cv-section Stripped float/size classes
cv/experience/ciao-gmbh.markdown default → cv-section Stripped float/size classes
cv/experience/easytobook.markdown default → cv-section Added permalink:
cv/experience/hermes-consulting.markdown default → cv-section Added permalink:
cv/experience/iq-solutions.markdown default → cv-section Added permalink:, fixed nav_order
cv/experience/lola-enterprises.markdown default → cv-section Added permalink:
cv/experience/realmedia-network.markdown default → cv-section Added permalink:
cv/experience/tekkie-consulting.markdown default → cv-section Added permalink:

Architecture

Layout hierarchy

base.html          ← includes head, nav, footer
  default.html     ← centered container, used by 404
  home.html        ← hero + feature blocks + prose
  page.html        ← article container (contact)
  post.html        ← post header + reading body + back link
  blog.html        ← post loop using post-card.html include
  cv-section.html  ← two-column: sidebar nav + breadcrumb + content

Uses input[type=checkbox] + <label> hamburger toggle pattern. Nav links in JetBrains Mono uppercase, brand name in Bricolage Grotesque 800.

CV sidebar

Loops site.pages filtered by parent/grand_parent relationships. Active state uses page.url comparison. Sticky on desktop (top: $nav-height), collapses to static on mobile.

Type scale (3x jumps, extreme weights)

  • Body: 1.125rem / Bricolage Grotesque weight 400 / line-height 1.8
  • Tagline/subtitle: weight 200 (extreme light contrast)
  • H2: 2rem / weight 500
  • H1: 3rem / weight 700
  • Hero name: 7rem desktop → scales down / weight 800

GitHub Actions Deployment

.github/workflows/deploy.yml — uses official GitHub Pages action stack:

  • ruby/setup-ruby@v1 with bundler-cache: true
  • actions/jekyll-build-pages@v1
  • actions/upload-pages-artifact@v3
  • actions/deploy-pages@v4

One manual repo setting required: GitHub Settings → Pages → Source → change from “Deploy from a branch” to “GitHub Actions”.

Build runs on every push and PR to main; deploy only on push to main.

Status: IMPLEMENTED ✓

Build verified clean: bundle exec jekyll build runs without errors. All pages generated at correct URLs: /, /cv/, /cv/education/, /cv/experience/, /cv/experience/asml-gmbh/, /blog/, /contact/

Remaining manual step

Change GitHub Pages source to “GitHub Actions” in repo Settings → Pages.