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.

Directoryhomio/
- Directory.cursor/ rules for the Cursor editor
  - …
- Directory.github/ instructions for GitHub Copilot
  - …
- Directory.vscode/ recommended VS Code extensions and settings
  - …
- Directory.windsurf/ rules for the Windsurf editor
  - …
- Directorypublic/ files served as they are (favicons, the shared social image, a sample video, and the _headers host settings)
  - …
- Directoryscripts/ helper scripts behind the npm run commands
  - …
- Directorysrc/
  - Directoryassets/
    Directoryimages/ your images (logo, favicon, photos grouped by area), optimized at build time
    …
  - Directoryconfig/ 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
  - Directorycontent/ all text, images, prices, and options
    Directorysections/ default content of every section
    Directoryenglish/
    …
    Directoryfrench/
    …
    Directoryhomepage/ the 4 homepages
    …
    Directorypricing/ prices, visit frequencies, add-ons, and estimator rates
    …
    Directoryservices/ one file per service, with its included list
    …
    Directoryareas/ one file per service area, with its postal codes
    …
    Directoryreviews/ projects/ team/ careers/ blog/ … one folder per page or collection
    …
    Directorypages/ legal pages, booking, how it works, gift cards, referral, and other single pages
    …
    _file_format.md every page frontmatter field, explained
  - Directoryi18n/ small interface text (button labels, form messages, footer text)
    en.json
    fr.json
  - Directorylayouts/
    Base.astro the page shell (head, header, call to action, footer, cookie banner, scripts)
    Directorycomponents/
    Directorysections/ one component per section
    …
    Directorycards/ cards used inside sections
    …
    Directorywidgets/ smaller parts (estimator, booking form, area finder, page header, cookie banner)
    …
    Directoryglobal/ header, footer, mobile action bar, logo
    …
    Directoryseo/ head tags
    …
    Directoryhelpers/ icon components
    …
    Directoryshortcodes/ components you can use inside MDX files
    …
  - Directorylib/ helper code (prices, business details, opening hours, area matching, structured data)
    brandMark.ts the built-in logo mark
  - Directorypages/
    Directory[…lang]/ one file per route (which sections a page shows, in which order)
    …
  - Directorystyles/
    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

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.

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.