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.

Directorytaskly/
- 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, the social image, a sample video, and _headers and .htaccess host settings)
  - …
- Directoryscripts/ helper scripts behind the npm run commands
  - …
- Directorysrc/
  - Directoryassets/
    Directoryimages/ your images (logo, avatars, client logos, blog covers, icons), optimized at build time
    …
  - Directoryconfig/ 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
  - Directorycontent/ all text, images, and options
    Directorysections/ default content of every section
    Directoryenglish/
    …
    Directoryfrench/
    …
    Directorywidgets/ dashboard sample data, cookie banner, announcement bar, layout gallery labels
    …
    Directoryhomepage/ the 3 homepages
    …
    Directoryblog/ changelog/ templates/ … 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)
    AuthLayout.astro BlogSingle.astro … layouts of the auth screens and detail pages
    Directorycomponents/
    Directorysections/ one component per section
    …
    Directoryui/ small shared parts (Button, Tag, Annotation, CommentPin, PageHeader…)
    …
    Directorymockups/ the coded product UI (dashboard, calendar, team chat)
    …
    Directorycards/ forms/ posts/ cards, forms, and blog and changelog parts
    …
    Directoryglobal/ header, footer, logo, search, cookie banner, announcement bar
    …
    Directoryseo/ meta tags, Open Graph, favicons, structured data
    …
    Directoryhelpers/ icon components
    …
    Directoryshortcodes/ components you can use inside MDX posts
    …
  - Directorylib/ helper code (content loading, i18n, SEO, Open Graph images, tint names)
    …
  - Directorypages/
    Directory[…lang]/ one file per route (which sections a page shows, in which order)
    …
  - Directorystyles/
    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

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.

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.