CLAUDE.md

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

Overview

This is a Jekyll-based static website for Artes do Sul, a Brazilian digital agency and portfolio site. The site features a blog, project showcase, tools collection, and study materials focused on technology, development, business strategy, and product management. The project uses the Hydejack Pro theme and is built with Portuguese content.

Key Technologies

  • Jekyll 4.3 - Static site generator
  • Hydejack Pro Theme - Premium Jekyll theme (local installation at ./#jekyll-theme-hydejack)
  • Ruby with Bundler for dependency management
  • kramdown-math-katex for math rendering
  • Node.js/Puppeteer for screenshot automation in assets/ia/

Build & Development Commands

Local Development

# Start development server with live reload
bundle exec jekyll serve
# or use the batch file (Windows)
start.bat

The development server runs at http://localhost:4000 by default.

Production Build

# Prefer clean + build on Windows (avoids Errno::EINVAL rewriting docs/)
bundle exec jekyll clean
bundle exec jekyll build
# or use the batch file (Windows) — already runs clean then build
build.bat

Important: The output directory is configured as docs/ (not the default _site/), as specified in _config.yml. This is for GitHub Pages / static deploy compatibility.

Exclude: projeto/ and guias/ are excluded in _config.yml so they do not conflict with projeto.md / generated pages. Do not use exclude pattern projeto without a trailing slash (it also matches projeto.md).

Dependencies

# Install Ruby dependencies
bundle install

# For screenshot automation in assets/ia/
cd assets/ia
npm install
npm run capture        # Capture all screenshots
npm run capture:single # Capture single screenshot

Architecture & Content Structure

Site Configuration

  • Main config: _config.yml - Controls site metadata, theme settings, navigation menus, and Jekyll plugins
  • Base URL: https://artesdosul.com
  • Language: Portuguese (pt-BR)
  • Output directory: docs/ (for GitHub Pages deployment)

Content Organization

Collections

Jekyll collections are the primary content structure:

  1. _posts/showcase/ - Project showcase entries (markdown files with frontmatter)
    • Layout: showcase
    • Categories: showcase
    • Contains project descriptions, links, and metadata
    • Example tags: apps, projeto, website, javascript, laravel, fitness
  2. _featured_categories/ - Main content categories (Tools, DevOps, Estudos)
    • Permalink: /:name/
    • SEO type: WebPage
  3. _featured_tags/ - Topical tags for filtering content
    • Permalink: /tag-:name/
    • Output as individual pages
  4. _projects/ - Project collection (if used)
    • Permalink: /projects/:path/

Key Content Sections

  • /showcase/ - Portfolio/projects gallery
  • /estudos/ - Study materials on product management, strategy, leadership
  • /tools/ - Curated tool collections (AI, development, security)
  • /devops/ - Web development tutorials and guides
  • /about/, /mission/, /vision/, /values/ - About pages

Recent Projects Display

  • _includes/projetos.md - HTML/markdown include for homepage recent projects section
  • Manually curated list of featured projects with thumbnails
  • Uses responsive card grid layout with Hydejack’s .project-card component

Assets & Interactive Tools

AI Tools Showcase (assets/ia/)

This directory contains a complete PWA (Progressive Web App) showcasing AI-powered interactive tools:

  • index.html - Main showcase page with filterable project gallery
  • Screenshots: Stored in screenshots/ directory
  • PWA features:
    • manifest.json - App manifest
    • service-worker.js - Offline support
    • icon-192.png, icon-512.png - App icons
  • Automation:
    • capture-screenshots.js - Puppeteer script to capture tool screenshots
    • package.json - Node dependencies for automation

Each AI tool links to Google Gemini shared conversations/apps and includes:

  • Interactive analysis dashboards (governance, politics, economics)
  • Creative tools (branding, palettes, content generation)
  • Educational platforms (UX heuristics, software engineering)

Image Assets

  • /assets/img/ - Project images, logos, thumbnails
  • /assets/img/projects/ - Project-specific images
  • Naming convention: {project-name}.webp for modern web format

Theme & Styling

Hydejack Theme Configuration

The site uses Hydejack Pro theme with extensive customization in _config.yml:

  • Accent color: rgb(255, 127, 80) (coral/orange)
  • Theme color: #691345 (deep purple)
  • Fonts:
    • Headings: Roboto Slab
    • Body: Noto Sans
    • Code: Fira Code
  • Dark mode: Dynamic (follows OS setting) with toggle icon
  • Features enabled:
    • Table of Contents (ToC)
    • Search functionality
    • Cookie consent banner
    • Dynamic push state (SPA-like navigation)

Custom Styling

  • Custom SASS in _sass/ directory (theme override)
  • Accent image: /assets/img/horizon-scanning-poligon.webp

Jekyll Plugins

Active plugins (see _config.yml and Gemfile):

  • jekyll-feed - RSS/Atom feed generation
  • jekyll-seo-tag - SEO meta tags
  • jekyll-sitemap - XML sitemap
  • jekyll-paginate - Blog pagination (10 posts per page)
  • jekyll-redirect-from - URL redirects
  • jekyll-relative-links - Convert relative links
  • jekyll-optional-front-matter - Allow posts without frontmatter
  • jekyll-readme-index - Use README.md as index
  • jekyll-titles-from-headings - Extract titles from headings
  • jekyll-include-cache - Performance optimization
  • jekyll-compose - Helper for creating posts/drafts

Content Creation Workflow

Creating New Showcase Projects

  1. Add new markdown file to _posts/showcase/ with date prefix: YYYY-MM-DD-{slug}.md
  2. Use frontmatter template: ```yaml — title: “Project Name” description: “Brief description” date: YYYY-MM-DDTHH:mm:ss.sssZ image: path: /assets/img/{project-image}.webp

    or remote OG image URL, e.g. https://example.com/og-image.webp

    categories: showcase category: showcase tags: [apps, projeto, website, javascript] links:

    • title: Project Link url: https://example.com/ layout: showcase — ```
  3. Add project card to the top of _includes/projetos.md for homepage display
  4. Add project image to /assets/img/ (preferably WebP) or use a stable remote OG/hero URL
  5. Run build.bat (or clean + build) before deploy

Ecosistema Selva: hub at https://selva.artesdosul.com/ — related hubs are listed in that project’s data/ecosystem.json and mirrored in showcase + projetos.md.

Adding New Tools/Articles

  • Tools: Add markdown to relevant section or create in tools/ directory
  • Studies: Add to estudos/ or as blog post
  • Use Jekyll’s optional frontmatter plugin - frontmatter is optional for simpler pages

Deployment

Hosting

  • Canonical site: https://artesdosul.com (and www) on VPS/shared host via FTP manual (upload de docs/)
  • Mirror: Vercel — https://artesdosul.vercel.app/ and https://www.artesdosul.xyz/ (auto on push)
  • Do not point artesdosul.com apex at Vercel: many *.artesdosul.com subdomains/apps live on the VPS
  • Config url in _config.yml remains https://artesdosul.com

Deploy sync

  1. Vercel rebuilds mirrors automatically on push (uses committed docs/)
  2. artesdosul.com: após build.bat, commit docs/ e envie por FTP manualmente (sem GitHub Action — sync anterior truncava arquivos)
  3. Local build.bat → commit docs/ → push (Vercel) + FTP manual (.com)

Versionamento e sync

  • SemVer: VERSION, site.version / site.version_date em _config.yml, _data/version.yml
  • Endpoint: /version.json — após deploy compare Vercel, .xyz e .com (mesmo version / date)
  • Em cada release: bump versão + CHANGELOG.md + offline.cache_version se assets mudarem

Build Output

  • Output directory: docs/
  • This directory is committed to Git for static hosting / Vercel static output
  • Excluded from build (see _config.yml):
  • scripts/, projeto/, guias/, .jekyll-cache, vendor/
  • Node modules and theme source files
  • Ignored by Git: .history/, .arquive/
  • Validate workflow checks docs/ (not _site)
  • GitHub Pages workflow (jekyll.yml) is manual-only (workflow_dispatch) to avoid conflicting deploys

Environment Notes

  • Windows-specific gems are included (wdm, tzinfo-data)
  • Math rendering requires Node.js runtime for KaTeX compilation
  • LSI option (use_lsi: true) is enabled for better related posts

Special Features

Multi-language Support

While the main language is Portuguese (pt-BR), the site structure supports eventual internationalization through Jekyll’s i18n capabilities.

Analytics & SEO

  • Google Analytics: G-VS0MJC571N
  • Google site verification configured
  • Full SEO meta tags via jekyll-seo-tag

Two menu systems defined in _config.yml:

  1. Main menu (menu:) - Top navigation
  2. Footer menu (legal:) - Footer links

Working with Interactive AI Tools

When modifying the AI tools showcase in assets/ia/:

  1. Update project data: Edit the projectsData object in index.html
  2. Add screenshots: Place in screenshots/ directory with naming: screenshot_{filename}.png
  3. Categories: Use one of: análise, painel, ferramenta
  4. Regenerate screenshots: Run npm run capture in assets/ia/ directory
  5. PWA updates: Increment cache_version in service-worker.js when making significant changes

Repository Conventions

  • Git strategy: Main branch is main
  • Commit messages: Portuguese is acceptable given the Brazilian audience
  • File naming: Use kebab-case for URLs/files, maintain existing naming patterns
  • Image optimization: Prefer WebP format for modern browsers, provide fallbacks for critical images