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.
Directoryplumbo/
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, photos grouped by area), optimized at build time
- …
Directoryconfig/ site-wide settings
- config.toml site name, URL, business details, forms, estimator, booking, 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, prices, and options
Directorysections/ default content of every section
Directoryenglish/
- …
Directoryfrench/
- …
Directoryarabic/
- …
Directoryhomepage/ the 4 homepages
- …
Directorypricing/ rate cards, add-ons, maintenance plans, and the pricing page
- …
Directoryservices/ one file per service, with its included list
- …
Directoryareas/ one file per service area, with its postal codes
- …
Directoryindustries/ commercial sectors
- …
Directoryreviews/ projects/ team/ careers/ blog/ … one folder per page or collection
- …
Directorypages/ legal pages, booking, how it works, emergency, specials, referral, and other single pages
- …
- _file_format.md every page frontmatter field, explained
Directoryi18n/ small interface text (button labels, form messages, footer text)
- en.json
- fr.json
- ar.json
Directorylayouts/
- Base.astro the page shell (head, header, call to action, footer, cookie banner, scripts)
Directorycomponents/
Directorysections/ one component per section
- …
Directorycards/ cards used inside sections
- …
Directorywidgets/ smaller parts (estimator, booking form, area finder, page header, cookie banner, mobile menu)
- …
Directoryglobal/ header, footer, mobile action 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 (prices, business details, opening hours, area matching, structured data)
- brandMark.ts the built-in logo mark
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, breakpoints, radii
- 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
Plumbo 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, prices, links, options | Change copy, lists, prices, 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/projects/english/-index.mdfor/projects/.- Every other file is one entry. Its name becomes the URL unless the file sets
customSlug:src/content/services/english/leak-detection.mdis/services/leak-detection/, andsrc/content/areas/english/north-harbor.mdis/areas/north-harbor/. - 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.