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.

Directorymargo/
- Directory.cursor/
  - Directoryrules/
    theme-architecture.mdc rules for the Cursor editor
- Directory.github/
  - copilot-instructions.md instructions for GitHub Copilot
- Directory.vscode/ recommended VS Code extensions and settings
  - …
- Directory.windsurf/
  - Directoryrules/
    theme-architecture.md rules for the Windsurf editor
- Directorypublic/ files served as they are (favicons, the shared social image, a sample video, and the _headers and .htaccess host settings)
  - …
- Directoryscripts/ helper scripts behind the npm run commands
  - …
- Directorysrc/
  - Directoryassets/
    Directoryimages/ your images (logo, favicon, photos grouped by area: projects/, series/, services/, people/, blog/, logos/, and more), optimized at build time
    …
  - Directoryconfig/ 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
  - Directorycontent/ all text, images, and options
    Directorysections/ default content of every section, and the footer copy
    Directoryenglish/
    …
    Directoryfrench/
    …
    Directoryarabic/
    …
    Directoryhomepage/ the 3 homepages
    …
    Directoryprojects/ one file per case study or photo series
    …
    Directoryservices/ one file per service
    …
    Directoryteam/ one file per team member
    …
    Directoryblog/ journal posts
    …
    Directoryauthor/ journal authors
    …
    Directorypricing/ faq/ contact/ about-us/ testimonials/ … one folder per page
    …
    Directorypages/ legal pages, the archive, the layout gallery, and other single pages
    …
    _file_format.md the common page frontmatter fields, explained
  - Directoryi18n/ small interface text (button labels, form messages, footer copyright)
    en.json
    fr.json
    ar.json
  - Directorylayouts/
    Base.astro the page shell (head, header, call to action, footer, cookie banner, search, scripts)
    Directorycomponents/
    Directorysections/ one component per section, with the larger layouts in subfolders
    …
    Directorycards/ cards used inside sections
    …
    Directoryui/ small building blocks (project cards, section headers, filter chips, lightbox)
    …
    Directorywidgets/ larger parts (page header, contact form, search, cookie banner, page actions)
    …
    Directoryglobal/ header, footer, logo, contact dock, page transitions
    …
    Directoryseo/ head tags
    …
    Directoryutilities/ images, the back-to-top button, the cursor label
    …
    Directoryhelpers/ icon components
    …
    Directoryshortcodes/ components you can use inside MDX files
    …
  - Directorylib/ helper code (animations in motion/, structured data, the llms files, menus, dates)
    …
  - Directorypages/
    Directory[…lang]/ one file per route (which sections a page shows, in which order)
    …
    robots.txt.ts builds /robots.txt
  - Directoryplugins/ build helpers
    …
  - Directorystyles/
    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

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.

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.