Skip to main content

​
Overview

Chapinismos is built with Astro 5 and follows a traditional Astro project structure with content collections, file-based routing, and reusable components.

​
Root Directory Structure

chapinismos/
├── api/                    # Serverless API functions
├── public/                 # Static assets (images, fonts, icons)
├── src/                    # Source code (see detailed structure below)
├── astro.config.mjs        # Astro configuration
├── package.json            # Project dependencies
├── tsconfig.json           # TypeScript configuration
├── vercel.json             # Vercel deployment config
└── pnpm-workspace.yaml     # PNPM workspace configuration

​
Source Directory (src/)

src/
├── components/             # Reusable Astro components
│   ├── home/              # Homepage-specific components
│   ├── icons/             # SVG icon components
│   └── schemas/           # JSON-LD structured data components
├── content/               # Content collections (Markdown/MDX)
│   ├── words-es/          # Spanish word entries
│   ├── words-en/          # English word entries
│   └── config.ts          # Content collection schema definitions
├── layouts/               # Page layout templates
│   └── Base.astro         # Main layout wrapper
├── pages/                 # File-based routing
│   ├── [lang]/            # Language-specific routes
│   └── index.astro        # Root redirect page
├── styles/                # Global CSS
│   └── global.css         # Global styles and CSS variables
└── utils/                 # Utility functions and helpers
    ├── categoryColors.ts  # Category color mappings
    ├── i18n.ts            # Internationalization utilities
    └── shareImage.ts      # Social share image generation

​
Detailed Component Structure

​
Core Components (src/components/)

components/
├── Footer.astro              # Site footer
├── Header.astro              # Site header with navigation
├── LanguageSwitcher.astro    # Language toggle (ES/EN)
├── MobileMenu.astro          # Mobile navigation menu
├── Navigation.astro          # Desktop navigation links
├── RelatedWordsSection.astro # Related words display
├── SearchBox.astro           # Search input component
├── ThemeToggle.astro         # Dark/light theme switcher
├── Ticker.astro              # Animated word ticker
└── WordCard.astro            # Word preview card

​
Homepage Components (src/components/home/)

home/
├── AboutSection.astro      # About the project section
├── ContributeSection.astro # Contribution call-to-action
├── FeaturedWords.astro     # Featured words showcase
└── HeroSection.astro       # Homepage hero with search

​
Schema Components (src/components/schemas/)

JSON-LD structured data for SEO: 
schemas/
├── BreadcrumbSchema.astro      # Breadcrumb navigation schema
├── CollectionPageSchema.astro  # Collection page schema
├── FAQSchema.astro             # FAQ schema for word pages
├── FeaturedWordsSchema.astro   # Featured words schema
├── OrganizationSchema.astro    # Organization schema
├── SearchPageSchema.astro      # Search page schema
├── WebsiteSchema.astro         # Website schema
└── WordSchema.astro            # Individual word schema

​
Public Assets (public/)

public/
├── images/               # Image assets
│   └── bg.webp          # Background image
├── apple-touch-icon.png # iOS home screen icon
├── favicon.svg          # Favicon (SVG)
├── favicon.ico          # Favicon (ICO)
├── og-image.svg         # Open Graph share image
├── robots.txt           # SEO robots file
└── site.webmanifest     # PWA manifest

​
Configuration Files

​
astro.config.mjs

Defines Astro build configuration, integrations, and i18n settings. 
import { defineConfig } from "astro/config";
import sitemap from "@astrojs/sitemap";
import vercel from "@astrojs/vercel";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  site: "https://chapinismos.org",
  output: "static",
  adapter: vercel(),
  trailingSlash: "always",
  integrations: [
    sitemap({
      filter: (page) => page !== "https://chapinismos.org/",
      i18n: {
        defaultLocale: "es",
        locales: {
          en: "en-US",
          es: "es-GT",
        },
      },
    }),
  ],
  i18n: {
    defaultLocale: "es",
    locales: ["es", "en"],
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: false,
    },
  },
});

​
src/content/config.ts

Defines the schema for content collections. 
import { defineCollection, z } from "astro:content";

const wordsSchema = z.object({
  word: z.string(),
  meaning: z.string(),
  examples: z.array(z.string()),
  category: z.enum([
    "sustantivo", "verbo", "adjetivo", "adverbio",
    "expresión", "interjección", "modismo",
    "noun", "verb", "adjective", "adverb",
    "expression", "interjection", "idiom",
  ]),
  region: z.string().optional(),
  synonyms: z.array(z.string()).optional(),
  relatedWords: z.array(z.string()).optional(),
  featured: z.boolean().optional(),
});

export const collections = {
  "words-es": defineCollection({ type: "content", schema: wordsSchema }),
  "words-en": defineCollection({ type: "content", schema: wordsSchema }),
};

​
File Organization Conventions

​
Component Naming

  • Use PascalCase for component files: WordCard.astro, HeroSection.astro
  • Group related components in subdirectories: home/, schemas/, icons/
  • Keep component files focused on a single responsibility

​
Content Organization

  • Separate content by language: words-es/, words-en/
  • Use kebab-case for content file slugs: chispa.md, chunche.md
  • Define frontmatter schema in content/config.ts

​
Utility Functions

  • Place shared utilities in src/utils/
  • Use descriptive names: categoryColors.ts, i18n.ts
  • Export pure functions when possible

​
Styles

  • Global styles in src/styles/global.css
  • Component-scoped styles within <style> tags in .astro files
  • Use CSS custom properties for theming

​
Build Output

When you run pnpm build, Astro generates: 
dist/
├── _astro/           # Bundled JS and CSS
├── es/              # Spanish language pages
├── en/              # English language pages
├── index.html       # Root redirect page
└── sitemap-*.xml    # Generated sitemaps

​
Key Directories Explained

DirectoryPurposeExamples
src/components/Reusable UI componentsHeader, Footer, WordCard
src/content/Content collections (MD/MDX)Word definitions
src/layouts/Page layout wrappersBase.astro
src/pages/File-based routingindex.astro, [slug].astro
src/utils/Helper functionsi18n, colors
public/Static assets (copied as-is)Images, fonts, icons

​
Next Steps

Pages & Routing

Learn how file-based routing works

Components

Explore the component architecture

Layouts

Understand layout structure

Content Collections

Work with content collections

Build docs developers (and LLMs) love

Get started for freeTalk to us