Building this site with an AI agent (step by step)

This site is a GitHub Pages project. Most customization, content work, and troubleshooting were done in the editor together with an AI agent (similar to workflows in Cursor, Copilot Chat, or others). I described the goal, reviewed proposed diffs, ran the site locally, and steered whenever something looked off.

I am currently studying the Astro framework to explore ideas for future iterations.

Reference: Creating a GitHub Pages site - GitHub Docs

Tip: document your progress in a separate notebook or notes file. It helps track decisions and avoid repeating work.

Below is the actual path we followed. This is not a generic tutorial, but the sequence that brought this repository to a shippable state.

1. Start from a working baseline

• Installed Jekyll through the github-pages toolchain.
• Loaded Minimal Mistakes via remote_theme: mmistakes/minimal-mistakes in _config.yml.
• Kept standard plugins (jekyll-paginate, jekyll-feed, etc.) in the Gemfile.
• Synced everything with GitHub.

Outcome: a single source of truth - what is on main is what visitors see after the Pages workflow runs.

2. Install gems and validate locally

• Ran bundle install and used bundle exec jekyll serve to catch Liquid errors and broken includes before pushing.
• On Ruby 3.4 (Windows), removed the optional wdm watcher gem because its native extension often fails on newer Ruby versions. The site still builds; auto-reload is just slightly slower.

Outcome: a repeatable local command that validates changes in minutes.

3. Make the site yours in _config.yml and data files

• Site identity: title, url / baseurl, GitHub username, search toggle, layout defaults.
• Author profile: managed via _data/authors.yml, allowing posts to reference author: and inherit bio, avatar, and social links.

Outcome: shared metadata instead of duplicating author details in every file.

4. Layer a custom look without forking the theme

• _sass/design-tokens.scss
• SCSS overrides (_sass/default.scss, nav.scss, home.scss, grid_layout.scss, footer.scss, post.scss, taxonomy.scss)
• assets/css/custom.scss
• _includes/head/custom.html
• _includes/footer/custom.html

We iterated visually multiple times: try, preview, then refine or revert. The AI helped generate consistent SCSS across files, but final design decisions were manual.

5. Layouts, navigation, and bilingual structure

• Custom layouts in _layouts/ (home.html, posts.html, and category views).
• _data/navigation.yml and _data/translations.yml for navigation and language switching.
• _includes/language-switcher.html connects English and Finnish pages.

Structure:

• Finnish content under /fi/
• Finnish posts use lang: fi, permalink: /fi/..., and lang_ref to link language versions

Outcome: one repository, two languages, with explicit cross-links instead of duplicated sites.

6. Content workflow: posts as small projects

• Each post is a Markdown file in _posts/ with structured front matter.
• Long-form posts were built iteratively: outline, sections, tables, refinement.
• EN/FI versions share content, with localized titles, descriptions, and text.

What worked well

• Concrete prompts worked better than vague ones.
• Letting the agent run terminal checks (build, diff, status) helped catch issues early.
• Treating AI output as a proposal; typography and spacing still need human judgment.

What I still do myself

• Final editorial voice.
• Deciding what not to ship (removing experiments, dependencies).
• Privacy and accuracy. Anything public-facing remains my responsibility.

---

If you are building something similar: start from a stable theme baseline, keep customization layered in _sass and _includes, and use AI as a fast implementation partner while keeping human review on every public change.

Finnish version: Verkkosivuston rakentaminen tekoalyagentilla.