# 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 five places marked in **bold** below.
- ecozen/
- .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 social image, a sample video, and `_headers` and `.htaccess` host settings)
- scripts/ helper scripts behind the `npm run` commands
- src/
- \_\_tests\_\_/ the theme's unit tests
- assets/
- images/ **your images** (logos, photos, team portraits), optimized at build time
- **config/** site-wide settings
- config.toml site name, URL, contact details, forms, SEO, cookies
- fonts.json fonts
- language.json languages and their text direction
- menu.en.json header and footer links (English)
- menu.fr.json header and footer links (French)
- menu.ar.json header and footer links (Arabic)
- social.json social media links
- **content/** all text, images, and options
- sections/ default content of every section
- english/
- french/
- arabic/
- homepage/ the 4 homepages
- services/ projects/ careers/ blog/ … one folder per page or collection
- i18n/ small interface text (button labels, form messages, footer text)
- en.json
- fr.json
- ar.json
- layouts/
- Base.astro the page shell (head, header, footer, cookie banner, scripts)
- components/
- sections/ one component per section
- cards/ cards used inside sections
- widgets/ smaller parts (quote form, newsletter form, form setup notice, calculator, page header, cookie banner, mobile menu panel)
- global/ footer, logo, section titles
- header/ header layouts, top bar, announcement strip, menus, language switch
- footer/ the four footer layouts, the call-to-action band, the AI row, the theme credit, and their line art
- seo/ head tags
- utilities/ small shared parts (optimized image, count-up number)
- helpers/ icon components
- shortcodes/ components you can use inside MDX files
- lib/ helper code (content loading, i18n, SEO, the AI files, the calculator formula, and the `[site]` and `[forms]` setup checks)
- pages/
- [...lang]/ **one file per route** (which sections a page shows, in which order), plus `llms.txt` and `llms-full.txt`
- [...path].md.ts the Markdown copies of pages
- robots.txt.ts `robots.txt`
- 404.astro the default 404 page
- plugins/ build plugins
- **styles/**
- theme.css colors, type scale, breakpoints
- base.css components.css navigation.css rtl.css … global styles
- types/ TypeScript types
- content.config.ts fields allowed in each collection
- sections.schema.ts fields allowed in each section
- AGENTS.md SKILLS.md CLAUDE.md GEMINI.md instructions for AI assistants
- README.md CHANGELOG.md setup notes and what changed in each version
- astro.config.mjs
- netlify.toml vercel.json vercel.sh wrangler.toml hosting settings
- package.json package-lock.json
### What Differs By Edition
The tree above is the Astro edition. The [other editions](../../features/editions/) change these parts:
| Part | Astro | Tina | Sanity |
| ---- | ----- | ---- | ------ |
| `src/content/`, `src/i18n/`, `src/config/menu.*.json` | Yes | Yes. The text pages and the listing pages of services, projects, and blog are `.mdx` instead of `.md` | Not in the zip: this content is in your Sanity project |
| `tina/`, `scripts/tina/`, `scripts/cms/`, `src/lib/tina/`, `src/layouts/components/tina/`, `public/admin/` | No | Yes | No |
| `sanity/`, `sanity.config.ts`, `sanity.cli.ts`, `scripts/sanity/`, `src/lib/sanity/`, `src/sanity-routes/`, `src/middleware.ts` | No | No | Yes |
| `.env.example` | No | Yes | Yes |
### The Three Layers
Ecozen 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, links, options | Change copy, lists, 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/`, `french/`, and `arabic/` hold the same files. Each language reads only its own folder, so keep them all in step when you add or rename a file.
- `-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/careers/english/electrician.md` is `/careers/electrician/`, and `src/content/services/english/service-01.mdx` (with `customSlug: "residential-solar"`) is `/services/residential-solar/`.
- Files that start with `_` are ignored. `src/content/_file_format.md` explains most 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`.