Skip to content
New: Customize your theme with an AI assistant. Read the guide

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 _headers and .htaccess host settings)
      • …
    • Directoryscripts/ helper scripts behind the npm run commands
      • …
    • Directorysrc/
      • Directoryassets/
        • Directoryimages/ your images (logo, favicon, sample photos in photos/, partner logos in partners/), 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.

EditionAddsTakes away
Tinatina/ (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.exampleNothing. Your content stays in the same files
Sanitysanity.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.examplesrc/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:

LayerFolderDecidesYou edit it to…
Contentsrc/content/What the page says: text, images, amounts, goals, links, optionsChange copy, lists, causes, amounts, buttons, layouts
Pagessrc/pages/[...lang]/Which sections a page shows and in which orderReorder, add, or remove sections
Designsrc/layouts/, src/styles/How each section looks and behavesChange 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. 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/causes/english/-index.md for /causes/.
  • Every other file is one entry. Its name becomes the URL unless the file sets customSlug: src/content/causes/english/clean-water-wells.md is /causes/clean-water-wells/, and src/content/events/english/riverside-charity-run.md is /events/riverside-charity-run/.
  • 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:

ShortcutReal 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.

Type something to search...