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.

  • 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 _headers and .htaccess host settings)
      • …
    • Directoryscripts/ helper scripts behind the npm run commands
      • …
    • 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.

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

Plumbo 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, prices, links, optionsChange copy, lists, prices, 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/projects/english/-index.md for /projects/.
  • Every other file is one entry. Its name becomes the URL unless the file sets customSlug: src/content/services/english/leak-detection.md is /services/leak-detection/, and src/content/areas/english/north-harbor.md is /areas/north-harbor/.
  • 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...