CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Meu Tarot Online is a static website built with Jekyll, providing free interactive tarot readings, daily card draws, and articles about tarot and spirituality in Portuguese (pt-BR). The site is deployed to GitHub Pages with a custom domain (meutarotonline.com.br) and includes Google AdSense monetization and Analytics.

Key Technologies:

  • Jekyll (Ruby static site generator)
  • GitHub Pages + GitHub Actions (CI/CD)
  • Vanilla JavaScript (ES6)
  • CSS3 with CSS variables
  • Liquid templating language

Essential Commands

# Install Ruby dependencies
bundle install

# Run local development server (live reload at http://localhost:4000)
bundle exec jekyll serve

# Build static site to _site/ directory
bundle exec jekyll build

# Build with future-dated posts included
bundle exec jekyll build --future

# Clean build artifacts before rebuilding
bundle exec jekyll clean

Project Structure & Architecture

Core Pages

  • index.html – Homepage with call-to-action
  • tarot.html – Main interactive tarot reading application
  • card-of-day.md – Daily card oracle display
  • articles.md – Auto-generated blog post listing
  • about.md – Project philosophy and contact info
  • oraculo-humor.md – Humor oracle page
  • _posts/ – Blog articles in Markdown (auto-published based on date)

Template System

  • _layouts/default.html – Base page template (all pages inherit this)
  • _layouts/post.html – Blog post template (inherits from default)
  • _includes/header.html – Navigation with dropdown menus (included in default)
  • _includes/footer.html – Footer component (included in default)

Application Code

  • js/tarot-app.js (43 KB) – Main interactive application:
    • Card database (78 tarot cards with Portuguese names, upright/reversed meanings)
    • Reading spread types (3-card, 5-card relationship, 5-card guidance, daily single card)
    • Card shuffling and randomization logic
    • Modal card detail viewer
    • DOM manipulation for card displays

  • js/sketch.js (41 KB) – Supporting JavaScript utilities

  • css/style.css (32 KB) – Responsive styling:
    • Dark mystical theme (purple/black color scheme)
    • CSS variables for easy theming
    • Responsive design for mobile/tablet/desktop
    • Animations (softTwinkle particle effects, transitions)
    • Glass-morphism effects

Assets

  • images/cartas/ – 78 tarot card PNG images (22 Major Arcana + 4 suits × 14 cards)
  • images/Mesa.png – Hero background image (2.1 MB)

Configuration

  • _config.yml – Jekyll site config (title, URL, plugins, future post support)
  • Gemfile – Ruby dependencies (github-pages gem pulls in Jekyll + plugins)
  • Gemfile.lock – Locked versions for reproducible builds
  • CNAME – Custom domain mapping (meutarotonline.com.br)
  • ads.txt – Google AdSense seller authorization

Build & Deployment

Local Development Workflow

  1. Create or modify Markdown files in _posts/ (or edit static pages)
  2. Run bundle exec jekyll serve
  3. View changes at http://localhost:4000 (live reload enabled)
  4. Commit and push to master branch

Automated Deployment (GitHub Actions)

Workflow: .github/workflows/jekyll-gh-pages.yml

  • Triggers on push to master
  • Builds site with Jekyll
  • Deploys to GitHub Pages automatically
  • Site updates live within seconds

Workflow: .github/workflows/jekyll-docker.yml

  • Runs on push and PR to master
  • Validates build using Docker (Jekyll builder image)
  • Ensures no build errors before merging

Publishing Posts

  • Posts in _posts/ follow Jekyll naming: YYYY-MM-DD-slug-name.md
  • Post date determines publish date (with future: true in config, future-dated posts are included in builds)
  • Posts auto-appear on articles.md listing
  • Posts get automatic SEO tags, feed entries, and sitemap inclusion

Tarot Card Data Structure

Each card in tarot-app.js contains:

{
  name: "Card name in Portuguese",
  image: "images/cartas/cardname.png",
  meaning: "Upright interpretation in Portuguese",
  reversedMeaning: "Reversed interpretation in Portuguese"
}

The 78-card deck is organized as:

  • 22 Major Arcana (0-21)
  • 4 Suits: Wands/Paus, Cups/Copas, Swords/Espadas, Pentacles/Ouros (14 cards each)

SEO & Monetization

SEO Features:

  • jekyll-seo-tag auto-generates meta tags for all pages
  • jekyll-sitemap generates sitemap.xml for search engines
  • jekyll-feed generates RSS feed at feed.xml
  • Each page/post has descriptive Front Matter
  • Language: pt-BR (Brazilian Portuguese)

Google Analytics & AdSense:

  • Analytics GA-4 tag: G-VTSVNSFRZ7
  • AdSense publisher ID: ca-pub-7268118989139833
  • Code in default layout applies to all pages
  • ads.txt file authorizes seller

Key Design Decisions

Color Scheme (CSS Variables):

  • Dark background: #0a0a14
  • Primary text: #e8e8e8
  • Accent/purple: #b0a3d7
  • Mystical, low-light aesthetic optimized for evening users

Fonts:

  • Headers: Cinzel (serif, elegant)
  • Body: Raleway (sans-serif, readable)

Responsive Breakpoints:

  • Mobile-first CSS approach
  • Supports phones, tablets, desktops
  • Touch-friendly card selection

Common Development Tasks

Adding a New Blog Post

  1. Create file: _posts/YYYY-MM-DD-slug.md
  2. Add Front Matter: 
    ---
layout: post
title: "Post Title in Portuguese"
description: "Short SEO description"
date: YYYY-MM-DD HH:MM:SS +0000
---
  3. Write Markdown content
  4. Run bundle exec jekyll serve to preview
  5. Commit and push to master

Adding a New Page

  1. Create .md or .html file in root directory
  2. Add Front Matter with layout (typically default)
  3. Update header.html nav if needed
  4. Test locally and commit

Modifying Tarot Card Data

  • Edit tarot-app.js card object definitions
  • Ensure Portuguese spelling and meanings are accurate
  • Update corresponding card PNG image if changed
  • Clear browser cache after changes (or use bundle exec jekyll clean)

Updating Navigation

  • Edit _includes/header.html
  • Dropdown menus use simple HTML/CSS (no JavaScript framework)
  • Links follow site structure: /, /tarot.html, /card-of-day, etc.

Performance Notes

  • Large assets: Individual card images are ~4MB each; total deck is ~300MB
  • Hero image: Mesa.png is 2.1MB (consider optimizing for faster load)
  • JS files: Combined 84 KB of JavaScript (consider minification if not already minified)
  • Build time: Usually 5-10 seconds locally; GitHub Actions completes deployment within 1-2 minutes

Important Constraints

  1. Language: All content must be in Brazilian Portuguese (pt-BR)
  2. Static site: No backend/database—only static files served by GitHub Pages
  3. Theme system: Using Jekyll’s default “minima” theme—custom CSS layers on top
  4. Ruby version: Must be compatible with GitHub Pages (currently supports Ruby 2.7+)
  5. Plugin limitations: Only GitHub Pages-compatible plugins available

Repository Info

  • Git branch: master (main development branch)
  • Repository: LuigiDeFacci/Site-Tarrot
  • License: MIT
  • Contact: meutarotonline.contato@gmail.com