Prioritized Implementation Checklist

Prioritized Implementation Checklist #

P0 - Ruby 3.3.4 and Build Reliability #

• Install Ruby 3.3.4 locally with rbenv, rvm, or another Ruby version manager.
• Update .ruby-version from 2.7.2 to 3.3.4.
• Run ruby -v from repo root and confirm it uses 3.3.4.
• Run bundle install.
• If dependency resolution fails, run bundle update.
• Verify Gemfile.lock updates cleanly.
• Run bundle exec jekyll build.
• Run bundle exec jekyll build --future.
• Run bundle exec jekyll serve --future.
• Manually check homepage, about page, one post page, one tag page, search, theme toggle, and RSS/feed links.
• Update docs/agents.md to explicitly say Ruby 3.3.4.
• Update README.md local setup if needed.

P1 - Fix Current Runtime and HTML Issues #

• Fix invalid HTML in index.html, especially stray </p> tags.
• Fix theme fallback logic in _layouts/default.html so system preference works.
• Make sure theme toggle still persists user choice in localStorage.
• Re-run bundle exec jekyll build --future.
• Re-check homepage rendering after HTML cleanup.
• Re-check one post page and one tag page for layout regressions.

P1 - Make URLs Local and Deployment Safe #

• Audit internal links using site.url.
• Replace internal navigation links with relative_url.
• Keep absolute URLs only where needed for feeds, sitemap, canonical URLs, or social sharing.
• Review index.html, _layouts/post.html, _layouts/tag.html, _layouts/about.html, _layouts/default.html, _includes/head.html, and _includes/share_bar.html.
• Verify local preview works at localhost:4000.
• Verify generated links still work for GitHub Pages root deployment.

P2 - Deployment and Config Cleanup #

• Decide final deployment model: GitHub Pages default build or custom GitHub Actions deploy.
• If keeping current model, document that Actions is build-only.
• If using custom Actions deploy, replace the current workflow with an explicit Pages deploy workflow.
• Align CI command with local verification: bundle exec jekyll build --future.
• Move hardcoded Google Analytics ID from _layouts/default.html into _config.yml, or remove it if unused.
• Confirm Giscus config in _config.yml is still valid.
• Review _config.yml values: url, baseurl, future, published, timezone, lang.

P2 - Project Metadata Cleanup #

• Decide whether Node tooling is needed.
• If Node is not needed, remove the misleading package.json and package-lock.json.
• If Node is needed, create a valid package.json with scripts and dependencies.
• Document the final decision in docs/agents.md.
• Re-run Jekyll build after metadata cleanup.

P3 - SEO and Metadata #

• Add or improve page metadata in _includes/head.html.
• Add canonical URL handling.
• Add Open Graph metadata.
• Add Twitter card metadata.
• Ensure posts consistently use description.
• Check generated homepage and post HTML metadata.
• Re-run bundle exec jekyll build --future.

P3 - Lightweight Quality Checks #

• Keep manual pre-commit checks in docs/agents.md.
• Add CI build validation if not already reliable after Ruby upgrade.
• Consider adding html-proofer for generated HTML and link checks.
• Consider adding markdownlint only if writing consistency becomes important.
• Avoid Node-based lint tooling unless the project becomes a real Node-managed repo.

P4 - Content and Maintenance Polish #

• Update README.md so setup instructions match this repo, not the original template.
• Fix README typos and outdated deployment guidance.
• Document how to create a new post.
• Document how to create a new tag page.
• Normalize image conventions under images/blog_illustration/.
• Replace remote raw GitHub image URLs with local asset paths where practical.
• Review old posts for broken images or obsolete links.

Assumptions #

• Ruby target is 3.3.4.
• Hosting remains GitHub Pages unless explicitly changed.
• The current custom Jekyll theme stays in place.
• No new Node tooling should be added unless there is a clear need.