File Structure

Kivo Theme Documentation

Skill level: Everyone · Time: 5 minutes

What’s In The Download

Directorythemes/
- Directorykivo/ the theme: the Astro project you open and edit
  - …
changelog.html shortcut to the online changelog
documentation.html shortcut to these docs

Inside The Theme Folder

You don’t need to understand every folder. Most changes happen in the five places marked in bold below.

Directorykivo/
- Directory.cursor/ rules for the Cursor editor
  - …
- Directory.github/ instructions for GitHub Copilot
  - …
- Directory.vscode/ recommended VS Code extensions and settings
  - …
- Directory.windsurf/ rules for Windsurf
  - …
- Directorypublic/ files served as they are (favicons, social image, a sample video, and _headers and .htaccess host settings)
  - …
- Directoryscripts/ helper scripts behind the npm run commands
  - …
- Directorysrc/
  - Directoryassets/
    Directoryimages/ your images (logos, photos, icons), optimized at build time
    …
  - Directoryconfig/ site-wide settings
    config.toml site name, URL, forms, SEO, search, cookies, layouts
    fonts.json fonts
    language.json languages
    menu.en.json header and footer links (English)
    menu.fr.json header and footer links (French)
    social.json social media links
  - Directorycontent/ all text, images, and options
    Directorysections/ default content of every section
    Directoryenglish/
    …
    Directoryfrench/
    …
    Directoryhomepage/ the 4 homepages
    …
    Directoryblog/ changelog/ services/ … one folder per page or collection
    …
  - Directoryi18n/ small interface text (button labels, form messages)
    en.json
    fr.json
  - Directorylayouts/
    Base.astro the page shell (head, header, footer, scripts)
    Directorycomponents/
    Directorysections/ one component per section
    …
    Directorycards/ cards used inside sections
    …
    Directorywidgets/ smaller parts (search, forms, page header, switchers)
    …
    Directoryglobal/ header, footer, logo, head tags
    …
    Directoryhelpers/ icon components
    …
    Directoryshortcodes/ components you can use inside MDX posts
    …
  - Directorylib/ helper code (content loading, i18n, SEO, OG images)
    …
  - Directorypages/
    Directory[…lang]/ one file per route (which sections a page shows, in which order)
    …
  - Directorystyles/
    theme.css colors, type scale, breakpoints
    base.css components.css … global styles
  - content.config.ts fields allowed in each collection
  - sections.schema.ts fields allowed in each section
- AGENTS.md CLAUDE.md GEMINI.md SKILLS.md instructions for AI assistants
- README.md quick start, where things live, and a launch checklist
- CHANGELOG.md what changed in each version
- astro.config.mjs
- netlify.toml vercel.json vercel.sh wrangler.toml hosting settings
- package.json package-lock.json

The Three Layers

Kivo 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/ and french/ hold the same files. Each language reads only its own folder, so keep both in step when you add or rename a file.
-index.md is the content of a list or landing page, for example src/content/blog/english/-index.md for /blog/.
Every other file is one entry, and its name becomes the URL: src/content/blog/english/introducing-durable-workflows.mdx is /blog/introducing-durable-workflows/.
Files that start with _ are ignored. src/content/_file_format.md explains most 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/HeroSaas.astro is src/layouts/components/sections/HeroSaas.astro.