# File Structure

## File Structure

**Skill level:** Everyone · **Time:** 5 minutes

### Inside The Theme Folder
You don't need to understand every folder. Most changes happen in the places marked in **bold** below.

<FileTree>

- homio/
  - .cursor/ rules for the Cursor editor
  - .github/ instructions for GitHub Copilot
  - .vscode/ recommended VS Code extensions and settings
  - .windsurf/ rules for the Windsurf editor
  - public/ files served as they are (favicons, the shared social image, a sample video, and the `_headers` host settings)
  - scripts/ helper scripts behind the `npm run` commands
  - src/
    - assets/
      - images/ **your images** (logo, favicon, photos grouped by area), optimized at build time
    - **config/** site-wide settings
      - config.toml site name, URL, business details, forms, estimator, booking, SEO, cookies
      - fonts.json fonts
      - language.json languages
      - menu.en.json header and footer links (English)
      - menu.fr.json header and footer links (French)
      - social.json social media links
    - **content/** all text, images, prices, and options
      - sections/ default content of every section
        - english/
        - french/
      - homepage/ the 4 homepages
      - pricing/ prices, visit frequencies, add-ons, and estimator rates
      - services/ one file per service, with its included list
      - areas/ one file per service area, with its postal codes
      - reviews/ projects/ team/ careers/ blog/ … one folder per page or collection
      - pages/ legal pages, booking, how it works, gift cards, referral, and other single pages
      - \_file_format.md every page frontmatter field, explained
    - i18n/ small interface text (button labels, form messages, footer text)
      - en.json
      - fr.json
    - layouts/
      - Base.astro the page shell (head, header, call to action, footer, cookie banner, scripts)
      - components/
        - sections/ one component per section
        - cards/ cards used inside sections
        - widgets/ smaller parts (estimator, booking form, area finder, page header, cookie banner)
        - global/ header, footer, mobile action bar, logo
        - seo/ head tags
      - helpers/ icon components
      - shortcodes/ components you can use inside MDX files
    - lib/ helper code (prices, business details, opening hours, area matching, structured data)
      - brandMark.ts the built-in logo mark
    - pages/
      - [...lang]/ **one file per route** (which sections a page shows, in which order)
    - **styles/**
      - theme.css colors, type scale, breakpoints, radii
      - base.css components.css … global styles
    - content.config.ts fields allowed in each collection
    - sections.schema.ts fields and layouts allowed in each section
  - AGENTS.md CLAUDE.md GEMINI.md SKILLS.md instructions and recipes for AI assistants
  - CHANGELOG.md what changed in each version
  - IMAGE-CREDITS.md source and license of every sample photo
  - README.md requirements, commands, and the "Before you launch" list
  - astro.config.mjs
  - netlify.toml vercel.json vercel.sh wrangler.toml hosting settings
  - package.json package-lock.json

</FileTree>

### The Three Layers
Homio keeps three jobs apart. Knowing which layer you need saves a lot of searching:

| Layer       | Folder                        | Decides                                            | You edit it to…                          |
| ----------- | ----------------------------- | -------------------------------------------------- | ---------------------------------------- |
| **Content** | `src/content/`                | What the page says: text, images, prices, links, options | Change copy, lists, prices, buttons, layouts |
| **Pages**   | `src/pages/[...lang]/`        | Which sections a page shows and in which order     | Reorder, add, or remove sections         |
| **Design**  | `src/layouts/`, `src/styles/` | How each section looks and behaves                 | Change markup, styles, or behavior       |

Global settings sit beside them in `src/config/`.

### How Content Folders Are Named
Every content folder has one subfolder per language, and a few file name rules:

- `english/` and `french/` hold the same files. Each language reads only its own folder, so keep both in step when you add or rename a file. `npm run check-i18n` lists any file that exists in one language only.
- `-index.md` is the content of a list or landing page, for example `src/content/projects/english/-index.md` for `/projects/`.
- Every other file is one entry. Its name becomes the URL unless the file sets `customSlug`: `src/content/services/english/deep-cleaning.md` is `/services/deep-cleaning/`, and `src/content/areas/english/north-harbor.md` is `/areas/north-harbor/`.
- Files that start with `_` are ignored. `src/content/_file_format.md` explains the common page frontmatter fields; the full list is the `page` schema in `src/content.config.ts`.

<Aside type="note">
  `.astro/` and `dist/` are created for you when you run the site. Never edit
  them; your changes would be overwritten.
</Aside>

### Path Shortcuts In Code
Component files import each other through shortcuts defined in `tsconfig.json`:

| Shortcut          | Real folder                 |
| ----------------- | --------------------------- |
| `@/components/*`  | `src/layouts/components/*`  |
| `@/shortcodes/*`  | `src/layouts/shortcodes/*`  |
| `@/helpers/*`     | `src/layouts/helpers/*`     |
| `@/*`             | `src/*`                     |

There is no `src/components/` folder: `@/components/sections/HeroSection.astro` is `src/layouts/components/sections/HeroSection.astro`.