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.
Directorygivo/
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
_headersand.htaccesshost settings)- …
Directoryscripts/ helper scripts behind the
npm runcommands- …
Directorysrc/
Directoryassets/
Directoryimages/ your images (logo, favicon, sample photos in
photos/, partner logos inpartners/), optimized at build time- …
Directoryconfig/ site-wide settings
- config.toml site name, URL, organization details, forms, header and footer layouts, patterns, SEO, cookies
- fonts.json fonts
- language.json languages
- menu.en.json header and footer links, with the Causes mega menu (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, amounts, and options
Directorysections/ default content of every section
Directoryenglish/
- …
Directoryfrench/
- …
Directoryarabic/
- …
Directoryhomepage/ the 3 homepages
- …
Directorycauses/ one file per cause, with its goal, amount raised, donors, and deadline
- …
Directorydonate/ currency, amounts, monthly tiers, impact lines, and the donation form settings
- …
Directoryevents/ one file per event
- …
Directoryimpact/ the impact and transparency page
- …
Directorygallery/ the photo gallery
- …
Directoryblog/ author/ the stories and their authors
- …
Directoryteam/ reviews/ careers/ faq/ about-us/ contact/ … one folder per page or collection
- …
Directorypages/ legal pages, volunteer, fundraise, tribute, partners, testimonials, the thank-you page, and other single pages
- …
- _file_format.md common page frontmatter fields, explained
Directoryi18n/ small interface text (button labels, form messages, footer text, page-title tagline)
- en.json
- fr.json
- ar.json
Directorylayouts/
- Base.astro the page shell (head, header, call to action, footer, donate bar, cookie banner, scripts)
Directorycomponents/
Directorysections/ one component per section
- …
Directorycards/ cards used inside sections
- …
Directorywidgets/ smaller parts (donation form, impact receipt, contact and volunteer forms, page header, cookie banner, mobile menu)
- …
Directoryglobal/ header, footer, mobile donate bar, logo
- …
Directoryseo/ head tags
- …
Directoryutilities/ images and the back-to-top button
- …
Directoryhelpers/ icon components
- …
Directoryshortcodes/ components you can use inside MDX files
- …
Directorylib/ helper code (campaign figures, plural labels, donations, events and calendar files, organization details, office hours, layouts)
- brandMark.ts the heart mark of the built-in wordmark
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, pattern strength
- patterns.css where the background patterns show
- rtl.css rules for right-to-left pages
- navigation.css the header menus
- 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
What Differs By Edition
The tree above is the Astro edition. The other two editions start from it.
| Edition | Adds | Takes away |
|---|---|---|
| Tina | tina/ (the editor’s configuration, with tina/generated/collections.json for its forms and tina/tina-lock.json), scripts/tina/, src/lib/tina/, src/layouts/components/tina/, .env.example | Nothing. Your content stays in the same files |
| Sanity | sanity.config.ts, sanity.cli.ts, sanity/ (the Studio’s schema, with the demo content in sanity/seed/demo-content.json), scripts/sanity/, src/lib/sanity/, src/sanity-routes/, .env.example | src/content/, src/i18n/, and the menu.<language>.json files. That content is in your Sanity project |
src/config/config.toml, fonts.json, language.json, and social.json are in every edition. In the Sanity edition, a value in Site settings wins over the same value in config.toml. See Theme Editions.
The Three Layers
Givo 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, amounts, goals, links, options | Change copy, lists, causes, amounts, 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/, andarabic/hold the same files. Each language reads only its own folder, so keep them in step when you add or rename a file.npm run check-i18nlists any file that exists in one language only.-index.mdis the content of a list or landing page, for examplesrc/content/causes/english/-index.mdfor/causes/.- Every other file is one entry. Its name becomes the URL unless the file sets
customSlug:src/content/causes/english/clean-water-wells.mdis/causes/clean-water-wells/, andsrc/content/events/english/riverside-charity-run.mdis/events/riverside-charity-run/. - Files that start with
_are ignored.src/content/_file_format.mdexplains the common page frontmatter fields; the full list is thepageschema insrc/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.