OilFinderPro Landing Page & Blog

A performance-first, SEO-optimized static site for OilFinderPro, built with Jekyll and hosted on GitHub Pages.

🚀 Project Overview

  • Purpose: Provide a high-performance landing page, blog, and vehicle oil specification database.
  • Tech Stack: Jekyll (Ruby), Liquid, HTML/CSS (Minima theme base), JavaScript (minimal).
  • Core Strategy: Programmatic SEO, mobile-first design, and zero technical debt.

📂 Key Directory Structure

  • _posts/: Blog articles (Markdown).
  • _specs/: Vehicle specification data (Jekyll collection).
  • specs/: Index pages for makes and models.
  • _layouts/: Page templates (e.g., post, vehicle-spec, make_index, model_index).
  • _includes/: Reusable HTML snippets.
  • images/: Static assets (WebP format required for new images).
  • scripts/: Automation and validation scripts (Ruby).
  • css/style.css: Main stylesheet.
  • js/script.js: Main client-side logic.

🛠️ Building and Running

Prerequisites

  • Ruby (check .ruby-version if present, or use current stable).
  • Bundler (gem install bundler).

Commands

  • Install Dependencies: 
    bundle install
  • Run Locally: 
    bundle exec jekyll serve

    The site will be available at http://localhost:4000.

  • Build Site: 
    bundle exec jekyll build
  • Validate Spec Taxonomy: 
    ruby scripts/validate_spec_taxonomy.rb

📜 Development Conventions

SEO & Indexing Rules

  • Clean URLs: Always use trailing slashes (e.g., /blog/my-post/). Avoid .html extensions.
  • Front Matter: Every .md or .html file MUST include:
    • layout: (e.g., default, post, vehicle-spec)
    • title: Keyword-optimized (max 60 chars).
    • description: Benefit-driven (max 155 chars).
    • last_modified_at: Current date.
    • permalink: Explicitly defined (e.g., /blog/my-post/).
  • No JS-Dependency: Core content must be readable without JavaScript.

Visual & Assets

  • Images: Must be in WebP format. Always include width and height attributes to prevent Layout Shift (CLS).
  • Mobile-First: Ensure all layouts are responsive and stack correctly on mobile (390px baseline).

Vehicle Specs (Collections)

  • Files in _specs/ must follow the taxonomy: _specs/{make}/{model}/{year}-{engine}.md.
  • Run ruby scripts/validate_spec_taxonomy.rb before committing changes to specifications.
  • Each make and model requires a corresponding index file in specs/.

Coding Style

  • Follow existing Liquid patterns for templating.
  • Keep CSS modular and prioritize performance.
  • Use _includes/ for repeated UI components.