Skip to main content
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