Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/abisai7/diccionario-chapin/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers the coding standards and conventions used in the Chapinismos project. Following these guidelines helps maintain consistency and quality across the codebase.

​
Code Style

​
JavaScript/Astro

The project uses Prettier for automatic code formatting with the following configuration:
  • Indentation: 2 spaces
  • Quotes: Double quotes for strings
  • Semicolons: Enabled
  • Max line width: 100 characters
  • Trailing commas: ES5 style

​
Best Practices

// ✅ Good
const userName = "Juan";
const getUserData = () => {
  return { name: userName };
};

// ❌ Bad
var user_name = "Juan";
function get_user_data() {
  return { name: user_name };
}
Rules:
  • Use const instead of let when possible
  • Variable and function names in camelCase
  • Component names in PascalCase
  • Avoid var - use const or let

​
CSS/Tailwind

The project uses Tailwind CSS with automatic class ordering via prettier-plugin-tailwindcss.

​
Best Practices

<!-- ✅ Good -->
<div class="p-4" style="background: var(--card); border-radius: var(--radius-lg)">
  Contenido
</div>

<!-- ❌ Bad -->
<div style="padding: 16px; background: #141920; border-radius: 16px">
  Contenido
</div>
Rules:
  • Use CSS variables for colors and theme values
  • Prioritize Tailwind classes over custom CSS
  • Maintain consistency with the design system
  • Use defined border-radius variables

​
File Organization

​
Directory Structure

diccionario-chapin/
├── src/
│   ├── components/         # Reusable Astro components
│   ├── content/
│   │   ├── words-es/       # Spanish word entries
│   │   ├── words-en/       # English word entries
│   │   └── config.ts       # Content collection configuration
│   ├── layouts/            # Page layouts
│   ├── pages/              # Application routes
│   ├── styles/             # Global styles
│   └── utils/              # Utility functions
├── public/                 # Static assets
└── ...

​
Naming Conventions

File TypeConventionExample
Astro ComponentsPascalCaseWordCard.astro, SearchBox.astro
JavaScript filescamelCaseslug.js, helpers.js
CSS fileskebab-caseglobal.css, theme-vars.css
Word files (Markdown)kebab-case, no accents, lowercasechapin.md, a-huevo.md
Important: Word filenames must be:
  • All lowercase
  • Without accents (e.g., puchica.md not púchica.md)
  • Use hyphens for spaces (e.g., a-huevo.md)
  • Same filename in both words-es/ and words-en/

​
Commit Conventions

The project follows Conventional Commits specification:

​
Commit Types

  • feat: - New feature or functionality
  • fix: - Bug fix
  • docs: - Documentation updates
  • style: - Formatting changes (no functional changes)
  • refactor: - Code refactoring
  • test: - Adding tests
  • chore: - Maintenance tasks (dependencies, etc.)

​
Commit Message Format

<type>: <description>

[optional body]

[optional footer]

​
Examples from the Project

Here are actual commit messages from the Chapinismos repository: 
# Adding new features
feat: enhance 'a huevo' entry with additional examples for better context and usage
feat: add new Guatemalan words and expressions with meanings, examples, and usage
feat: add FAQ schema component and translations for enhanced SEO and user experience

# Fixing bugs
fix: add script type to avoid duplicated const declarations
fix: slug word
fix: update github repo in schema

# Styling/formatting
style: replace svg icons with lucide icons
styles: update header distribution and fix some ui bugs in mobile

# Chores and maintenance
chore: update dependencies
chore: update astro from v5.16.11 to v5.18.0

​
Writing Good Commit Messages

Do:
  • Use lowercase for the description
  • Be concise but descriptive
  • Start with a verb (add, update, fix, remove)
  • Focus on “what” and “why”, not “how”
  • Reference issues when relevant: fix: resolve search bug (#123)
Don’t:
  • End with a period
  • Use vague messages like “fix stuff” or “updates”
  • Include multiple unrelated changes in one commit

​
Examples

# ✅ Good
git commit -m "feat: agregar palabra 'chilero'"
git commit -m "fix: corregir búsqueda case-sensitive"
git commit -m "docs: actualizar README con nuevas instrucciones"
git commit -m "style: formatear código con prettier"

# ❌ Bad
git commit -m "Added stuff"
git commit -m "Fix."
git commit -m "Updated files and fixed bugs and added features"

​
Word Entry Guidelines

​
Required Fields

Every word entry must include: 
---
word: "Patojo"                    # The word itself
meaning: "Niño o joven..."        # Clear definition
examples:                         # At least 2 examples
  - "El patojo de la tienda..."
  - "Cuando era patojo..."
category: "sustantivo"            # Valid category
---

​
Valid Categories

Spanish (words-es/):
  • "sustantivo" (noun)
  • "verbo" (verb)
  • "adjetivo" (adjective)
  • "expresión" (expression)
  • "modismo" (idiom)
English (words-en/):
  • "noun"
  • "verb"
  • "adjective"
  • "expression"
  • "idiom"

​
Content Quality Standards

All word entries must:
  • Be terms actually used in Guatemala
  • Have clear, understandable definitions
  • Include natural, contextualized examples
  • Avoid offensive or discriminatory language
  • Be appropriate for all audiences
Writing examples:
  • Use realistic, everyday scenarios
  • Show the word in different contexts
  • Make examples relatable and culturally relevant
  • Keep examples concise but complete

​
Code Quality Tools

​
Prettier (Code Formatter)

Format all code before committing: 
# Format all files
pnpm run format

# Check formatting without modifying
pnpm run format:check
Configuration highlights:
  • Automatic Tailwind class ordering
  • Astro file support
  • Consistent code style across the project

​
ESLint (Code Linter)

Run linter to catch potential issues: 
# Run ESLint
pnpm run lint

# Auto-fix issues
pnpm run lint:fix
Configured with:
  • eslint-plugin-astro - Astro-specific rules
  • eslint-plugin-jsx-a11y - Accessibility validation
  • Modern ES6+ rules
  • Best practices enforcement

​
Zod Validation

The project uses Zod for runtime validation of word entries: 
# Validate all content
pnpm run build
If validation fails, you’ll see descriptive error messages indicating:
  • Missing required fields
  • Invalid data types
  • Invalid category values
  • Other schema violations

​
Pre-Commit Checklist

Before committing your changes, ensure:
  1. ✅ Code follows style guidelines
  2. ✅ Run pnpm run format to format code
  3. ✅ Run pnpm run lint to check for issues
  4. ✅ Run pnpm run build to validate content
  5. ✅ Test changes with pnpm run dev
  6. ✅ Commit message follows Conventional Commits
  7. ✅ No console errors or warnings

​
VS Code Configuration

The project includes recommended VS Code settings:
  • Format on save - Automatic Prettier formatting
  • ESLint auto-fix - Fix issues on save
  • Recommended extensions:
    • Astro
    • Prettier
    • ESLint
    • Tailwind CSS IntelliSense

​
Additional Resources

Next, learn about the Pull Request process to submit your contributions!

Build docs developers (and LLMs) love

Get started for freeTalk to us