Skip to content

Project Structure

Every project created by the creation script follows the same folder layout and conventions.

Generated folder tree

my-project/
├── .cursor/
│   └── rules/
│       └── general.mdc            # AI-assisted dev rules
├── .github/
│   └── workflows/
│       └── deploy.yml             # GitHub Actions deploy workflow
├── docs/
│   └── project_steps.md           # Step-by-step implementation plan
├── src/
│   ├── assets/                    # Images, logos, favicons
│   ├── components/                # Astro/React components
│   ├── data/
│   │   ├── config.yaml            # Google IDs, contact info, socials
│   │   ├── front.yaml             # ALL page content, links, image URLs
│   │   └── head.yaml              # SEO metadata (title, description, OG)
│   ├── layouts/
│   │   ├── Base.astro             # HTML shell (head, scripts, body)
│   │   └── SEO.astro              # Meta tags component
│   ├── pages/
│   │   └── index.astro            # Main page
│   ├── styles/
│   │   ├── global.css             # Tailwind directives
│   │   ├── _global.scss           # CSS resets
│   │   └── _breakpoints.scss      # Responsive mixins
│   ├── utils/
│   │   ├── buildtime/
│   │   │   ├── imageUtils.ts      # Astro image processing
│   │   │   ├── index.ts           # Barrel export
│   │   │   ├── s3Utils.ts         # (if S3 integration)
│   │   │   └── meliUtils.ts       # (if Meli integration)
│   │   └── utils.ts               # General utility functions
│   └── files.d.ts                 # YAML module declarations
├── astro.config.mjs
├── tailwind.config.ts
├── .eslintrc.json
├── .prettierrc.json
├── .npmrc
├── package.json
└── tsconfig.json

Data files

All content is managed through three YAML files in src/data/:

head.yaml — SEO metadata

Used by SEO.astro to populate <head> meta tags.

title: 'My Project'
site_name: 'My Project'
url: 'https://www.example.com'
description: 'One-line project description'
keywords: ['keyword1', 'keyword2']
image: '/default-image.png'
locale: 'es_ES'
twitter_username: '@handle'

front.yaml — page content

All text, links, and image URLs used in components must live here. Components import it with:

import front from '../data/front.yaml';

Typical structure:

info:
  logo: '/assets/logo.png'
  business_name: 'Acme Corp'
  email: 'info@acme.com'
  phone: '+598 99 123 456'
  whatsapp:
    number: '+598 99 123 456'
    message: 'Hola, quiero más información.'
  socials:
    facebook: 'https://facebook.com/acme'
    instagram: 'https://instagram.com/acme'

nav:
  links:
    - name: 'Inicio'
      href: ''
    - name: 'Servicios'
      href: 'servicios'
    - name: 'Contacto'
      href: 'contacto'

sections: {}   # Populated during development

config.yaml — service IDs

Stores Google Tag Manager, Analytics, Clarity IDs and contact info.

google:
  tag_manager: 'GTM-XXXXXXX'
  analytics: 'G-XXXXXXXXXX'
  clarity: 'XXXXXXXXXX'

seo:
  enable_indexing: true
  structured_data: true

contact:
  email: 'contacto@example.com'
  phone: '+54 9 11 1234-5678'
  whatsapp: '+54 9 11 9876-5432'

Astro configuration

The generated astro.config.mjs is pre-configured for GitHub Pages staging:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import yaml from '@rollup/plugin-yaml';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  site: 'https://sitios-agencia-digital.github.io',
  base: '/my-project',
  integrations: [react(), tailwind()],
  vite: {
    plugins: [yaml()]
  }
});
  • site — the org's GitHub Pages root.
  • base — the repo name (used as path prefix in staging).
  • When switching to production, update site to the custom domain and set base to "". See Switch staging → prod.

Implementation plan (docs/project_steps.md)

Every generated project includes a step-by-step implementation plan in docs/project_steps.md. This file is used by Cursor (via the .cursor/rules/general.mdc rule) to guide the AI through a structured development workflow:

  1. Step 1 — Project initialization (already done by the script)
  2. Step 2 — Analyze provided HTML structure
  3. Step 3 — Extract content to front.yaml
  4. Steps 4–5 — Create section and reusable components
  5. Step 6 — Font Awesome Pro setup (done by the script)
  6. Steps 7–8 — Implement pages and mobile menu
  7. Steps 9–12 — Content verification, style refinement, accessibility, testing

Steps are marked [x] as they are completed during development.