# File Structure

## 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 five places marked in **bold** below.

<FileTree>

- taskly/
  - .cursor/ rules for the Cursor editor
  - .github/ instructions for GitHub Copilot
  - .vscode/ recommended VS Code extensions and settings
  - .windsurf/ rules for Windsurf
  - public/ files served as they are (favicons, the social image, a sample video, and `_headers` and `.htaccess` host settings)
  - scripts/ helper scripts behind the `npm run` commands
  - src/
    - assets/
      - images/ **your images** (logo, avatars, client logos, blog covers, icons), optimized at build time
    - **config/** site-wide settings
      - config.toml site name, URL, forms, SEO, search, cookies, announcement bar
      - 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 section
        - english/
        - french/
      - widgets/ dashboard sample data, cookie banner, announcement bar, layout gallery labels
      - homepage/ the 3 homepages
      - blog/ changelog/ templates/ … one folder per page or collection
    - i18n/ small interface text (button labels, form messages)
      - en.json
      - fr.json
    - layouts/
      - Base.astro the page shell (head, header, footer, scripts)
      - AuthLayout.astro BlogSingle.astro … layouts of the auth screens and detail pages
      - components/
        - sections/ one component per section
        - ui/ small shared parts (Button, Tag, Annotation, CommentPin, PageHeader…)
        - mockups/ the coded product UI (dashboard, calendar, team chat)
        - cards/ forms/ posts/ cards, forms, and blog and changelog parts
        - global/ header, footer, logo, search, cookie banner, announcement bar
        - seo/ meta tags, Open Graph, favicons, structured data
      - helpers/ icon components
      - shortcodes/ components you can use inside MDX posts
    - lib/ helper code (content loading, i18n, SEO, Open Graph images, tint names)
    - pages/
      - [...lang]/ **one file per route** (which sections a page shows, in which order)
    - **styles/**
      - theme.css colors, radii, 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

</FileTree>

### The Three Layers
Taskly 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/templates/english/bug-triage.md` is `/templates/bug-triage/`.
- 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`.

<Aside type="note">
  `.astro/` and `dist/` are created for you when you run the site. Never edit
  them; your changes would be overwritten.
</Aside>

### Image Paths
In content files, an image path that starts with `/images/` points to `src/assets/images/` (or, if the file is not there, to `public/images/`). For example, `avatar: "/images/team/8.png"` is `src/assets/images/team/8.png`. Images in `src/assets/images/` are resized and compressed at build time.

### 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`.