# 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>

- margo/
  - .cursor/
    - rules/
      - theme-architecture.mdc rules for the Cursor editor
  - .github/
    - copilot-instructions.md instructions for GitHub Copilot
  - .vscode/ recommended VS Code extensions and settings
  - .windsurf/
    - rules/
      - theme-architecture.md rules for the Windsurf editor
  - public/ files served as they are (favicons, the shared social image, a sample video, and the `_headers` and `.htaccess` host settings)
  - scripts/ helper scripts behind the `npm run` commands
  - src/
    - assets/
      - images/ **your images** (logo, favicon, photos grouped by area: `projects/`, `series/`, `services/`, `people/`, `blog/`, `logos/`, and more), optimized at build time
    - **config/** site-wide settings
      - config.toml site name, URL, header and footer layouts, forms, search, animations, SEO, cookies
      - fonts.json fonts
      - language.json languages
      - 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, and the footer copy
        - english/
        - french/
        - arabic/
      - homepage/ the 3 homepages
      - projects/ one file per case study or photo series
      - services/ one file per service
      - team/ one file per team member
      - blog/ journal posts
      - author/ journal authors
      - pricing/ faq/ contact/ about-us/ testimonials/ … one folder per page
      - pages/ legal pages, the archive, the layout gallery, and other single pages
      - \_file_format.md the common page frontmatter fields, explained
    - i18n/ small interface text (button labels, form messages, footer copyright)
      - en.json
      - fr.json
      - ar.json
    - layouts/
      - Base.astro the page shell (head, header, call to action, footer, cookie banner, search, scripts)
      - components/
        - sections/ one component per section, with the larger layouts in subfolders
        - cards/ cards used inside sections
        - ui/ small building blocks (project cards, section headers, filter chips, lightbox)
        - widgets/ larger parts (page header, contact form, search, cookie banner, page actions)
        - global/ header, footer, logo, contact dock, page transitions
        - seo/ head tags
        - utilities/ images, the back-to-top button, the cursor label
      - helpers/ icon components
      - shortcodes/ components you can use inside MDX files
    - lib/ helper code (animations in `motion/`, structured data, the llms files, menus, dates)
    - pages/
      - [...lang]/ **one file per route** (which sections a page shows, in which order)
      - robots.txt.ts builds `/robots.txt`
    - plugins/ build helpers
    - **styles/**
      - theme.css colors, type scale, radii
      - rtl.css rules for right-to-left pages
      - navigation.css the header menus
      - base.css components.css motion.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
  - 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
Margo 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 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/projects/english/ceramic-forms.md` is `/projects/ceramic-forms/`, and `src/content/services/english/web-design.md` is `/services/web-design/`.
- 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`.