# File Structure

## File Structure

**Skill level:** Everyone · **Time:** 5 minutes

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

<FileTree>

- consultiz/
  - .cursor/ rules for the Cursor editor
  - .github/ GitHub Copilot instructions and a `verify` workflow for GitHub Actions
  - .vscode/ recommended VS Code extensions and settings
  - .windsurf/ rules for Windsurf
  - docs/
    - section-ownership.md every section component, its content file, and the pages that use it
  - public/ files served as they are (favicons, social image, videos, PDFs, the `.htaccess` file for Apache)
  - scripts/ helper scripts behind the `npm run` commands
  - src/
    - assets/
      - images/ **your images** (logos, photos, icons), optimized at build time
    - **config/** site-wide settings
      - config.toml site name, URL, contact details, forms, SEO, cookies, motion
      - 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
    - **content/** all text, images, and options
      - sections/ default content of every reusable section
        - english/
        - french/
      - homepage/ the three homepages (main, corporate consulting, tax and accounting)
      - solutions/ industries/ solution and industry pages (`-index.md` is the list page)
      - blog/ people/ careers/ … one folder per page or collection
      - _file_format.md the frontmatter fields every page accepts, with comments
    - i18n/ small interface text (labels, form messages, footer text)
      - en.json
      - fr.json
    - layouts/
      - Base.astro the page shell (head, header, footer, scripts)
      - components/
        - sections/ one component per section
        - cards/ cards used inside sections and lists
        - widgets/ smaller parts (forms, page header, breadcrumbs, cookie banner)
        - global/ header, footer, logo, head tags
      - helpers/ icon components
      - shortcodes/ components you can use inside MDX files
    - lib/ helper code (content loading, i18n, SEO, AI files)
    - pages/
      - [...lang]/ **one file per route** (which sections a page shows, in which order)
    - **styles/**
      - theme.css colors, type scale, breakpoints
      - base.css buttons.css … global styles
    - content.config.ts fields allowed in each collection
    - sections.schema.ts fields allowed in each section and page block
    - page-content.schema.ts fields of the solution, industry, and case study pages
  - AGENTS.md CLAUDE.md instructions for AI assistants
  - CHANGELOG.md what changed in each version
  - NEXTJS-TO-ASTRO-GUIDE.md a developer guide to the theme's structure, for React and Next.js developers
  - PUBLIC-VALUES-NEEDED.md the demo values to replace before launch
  - README.md editing map, override rules, and launch notes
  - astro.config.mjs
  - netlify.toml vercel.json vercel.sh wrangler.toml hosting settings
  - package.json package-lock.json

</FileTree>

### The Three Layers
Consultiz 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, images |
| **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 the blog list pages.
- Every other file is one entry, and its name becomes the URL: `src/content/solutions/english/cost-optimization.md` is `/solutions/cost-optimization/`.
- Files that start with `_` are ignored. `src/content/_file_format.md` explains the frontmatter fields every page accepts.

A few folders hold the content of one specialized page rather than a list: `industry-style-01/`, `industry-style-02/`, `solution-style-01/`, and `solution-style-02/`. See [Pages](/consultiz/customization/pages/).

<Aside type="note">
  `.astro/` and `dist/` are created for you when you run the site. Never edit
  them; your changes would be overwritten. `.astro/config.generated.json` is
  made from `config.toml`, so always edit the TOML file.
</Aside>

### 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/faq/FaqCentered.astro` is `src/layouts/components/sections/faq/FaqCentered.astro`.