Skip to main content
This guide explains how to add new Guatemalan slang words (chapinismos) to the dictionary. Words are stored as Markdown files with frontmatter in the content collections.

​
File Structure

Words are organized in two collections for bilingual support:
  • src/content/words-es/ - Spanish version of words
  • src/content/words-en/ - English version of words
Each word must have a corresponding file in both collections.

​
Step-by-Step Guide

1

Create the word file

Create a new .md file in both src/content/words-es/ and src/content/words-en/.File naming conventions:
  • Use lowercase letters only
  • Replace spaces with hyphens: pura-vida.md
  • Remove accents: puchica.md (not púchica.md)
  • No special characters allowed
Example:
touch src/content/words-es/patojo.md
touch src/content/words-en/patojo.md
2

Add frontmatter fields

Add the YAML frontmatter at the top of the file with all required fields.Minimal example:
---
word: "Patojo"
meaning: "Niño o joven; persona de corta edad."
examples:
  - "El patojo de la tienda siempre me ayuda."
  - "Cuando era patojo jugaba en la calle."
category: "sustantivo"
---
Complete example with optional fields:
---
word: "¡Aguas!"
meaning: "¡Cuidado! Expresión de advertencia para indicar precaución o peligro."
examples:
  - "¡Aguas con el tráfico! Es peligroso manejar tan rápido."
  - "¡Aguas! Viene un carro a toda velocidad."
  - "¡Aguas con el chucho, muerde!"
category: "expresión"
region: "Guatemala"
synonyms: ["cuidado", "ojo"]
relatedWords: ["trucha"]
featured: true
---
3

Add optional Markdown content

After the frontmatter, you can add additional context, etymology, cultural notes, or usage examples.
---
word: "Chilero"
meaning: "Algo muy bueno, bonito o agradable."
examples:
  - "¡Qué chilero está tu dibujo!"
  - "El viaje estuvo chilero, lo volvería a hacer."
category: "adjetivo"
region: "Guatemala"
featured: true
---

### Definición

"Chilero" is one of the most versatile words in Guatemalan Spanish...

### Uso

The word can be used for:

- **Objetos**: "Qué chilero tu teléfono"
- **Experiencias**: "La fiesta estuvo chilera"
- **Personas**: "Es un tipo chilero"
4

Validate and save

Save both files. Astro will automatically validate the frontmatter against the Zod schema.If validation fails, you’ll see a descriptive error message during build. See Validation Schema for details.

​
Required Fields

All word files must include these fields:
​
word
string
required
The word or phrase in its original form. Can include accents and special characters.Examples:
  • "Patojo"
  • "Púchica"
  • "¡Aguas!"
​
meaning
string
required
Complete definition of the word. Be clear and concise.Example:
meaning: "Niño o joven; persona de corta edad, usado comúnmente en Guatemala."
​
examples
array<string>
required
Array of real usage examples. Include at least 2-3 examples showing different contexts.Example:
examples:
  - "El patojo de la tienda siempre me ayuda a cargar las bolsas."
  - "Cuando era patojo jugaba en la calle con mis amigos."
​
category
enum
required
Grammatical category of the word. Must be one of the valid options.Spanish categories:
  • "sustantivo" (noun)
  • "verbo" (verb)
  • "adjetivo" (adjective)
  • "adverbio" (adverb)
  • "expresión" (expression)
  • "interjección" (interjection)
  • "modismo" (idiom)
English categories:
  • "noun"
  • "verb"
  • "adjective"
  • "adverb"
  • "expression"
  • "interjection"
  • "idiom"

​
Optional Fields

​
region
string
Geographic region where the word is used. Defaults to “Guatemala” if omitted.Example:
region: "Guatemala"
​
synonyms
array<string>
List of similar words or synonyms.Example:
synonyms: ["cuidado", "ojo"]
​
relatedWords
array<string>
List of related words that users might find interesting.Example:
relatedWords: ["trucha", "pilas"]
​
featured
boolean
Marks the word as featured to display on the homepage.
Only mark the 6 most representative or popular words as featured to avoid cluttering the homepage.
Example:
featured: true

​
Bilingual Setup

Each word must exist in both Spanish and English collections:

​
Spanish Version (src/content/words-es/patojo.md)

---
word: "Patojo"
meaning: "Niño o joven; persona de corta edad."
examples:
  - "El patojo de la tienda siempre me ayuda."
  - "Cuando era patojo jugaba en la calle."
category: "sustantivo"
region: "Guatemala"
featured: true
---

Definición en español...

​
English Version (src/content/words-en/patojo.md)

---
word: "Patojo"
meaning: "Kid or young person; commonly used in Guatemala."
examples:
  - "The kid from the store always helps me carry bags."
  - "When I was a kid I played in the street."
category: "noun"
region: "Guatemala"
featured: true
---

Definition in English...
Both files must use the same filename (slug). The category field should use Spanish values in words-es and English values in words-en.

​
Common Mistakes

Validation will fail if:
  • Required fields are missing
  • category uses an invalid value
  • examples is not an array
  • Field types don’t match (e.g., string instead of array)

​
Invalid Category

# ❌ Wrong
category: "nombre"  # Not a valid category

# ✅ Correct
category: "sustantivo"

​
Missing Examples

# ❌ Wrong
examples: "El patojo jugaba"  # Should be an array

# ✅ Correct
examples:
  - "El patojo jugaba"

​
Filename Issues

# ❌ Wrong
Patojo.md          # Uppercase letters
púchica.md         # Accents
que onda.md        # Spaces

# ✅ Correct
patojo.md
puchica.md
que-onda.md

​
Automatic Features

Once you add a word file, the system automatically:
  • Generates SEO-friendly URLs (slugs) from the filename
  • Updates the alphabetical index
  • Includes the word in search results
  • May display it in the homepage ticker
  • Validates the schema on build
No additional configuration needed!

​
Content Guidelines

​
Writing Quality Examples

  • Use natural, conversational language
  • Show the word in different contexts
  • Include cultural context when relevant
  • Keep examples concise and clear

​
Style Conventions

  • Write clearly and concisely
  • Use real, natural examples
  • Include cultural context when relevant
  • Maintain a respectful and educational tone
  • Avoid overly formal or academic language

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us