Who this is for. A developer who has cloned a site's repository for the first time. After this page you will know what each part of it is for, which parts you must never edit by hand, and where to start reading.
What you will find
Names vary from site to site, but the parts do not.
| Folder or file | What it holds | What the platform does with it |
|---|---|---|
templates/ | The Smarty or Twig templates: page layouts, usually under templates/pages/pages/, components, includes and module templates | Reads them when it renders. Never served as files |
src/, or a similar name | The source of the front end: SCSS, JavaScript, fonts and images | Nothing: the build reads it |
The build output, usually dist/ or static/ | Compiled CSS and JavaScript, and the fonts and images the build copies | Serves the files as they are. Generated and committed: never edit by hand |
assets/, on some sites | Files kept and served as they are, outside the build | Serves them |
translations/, on some sites | XLIFF files named <domain>.<language>.xlf that replace the platform's own interface wording | Reads them in preference to its own |
package.json, the lock file and the build configuration: .build/, webpack.*.js or config/gulp.js | The toolchain | Nothing; package.json and the lock files are never served |
favicon.ico, robots.txt and similar at the top level | Files expected at the site's root | Serves them at the root |
.settings.json, on some sites | Site settings that Core dna controls | Reads them; they take precedence over the admin. Never served |
Each environment has its own folder of these files on the server, and a deploy makes the tracked files in it match the branch. When a path and file type are allowed, the platform serves a file from that folder directly, at the same path: dist/app.css in the repository is /dist/app.css on the site. What is never served lists the exceptions.
What is generated
The build output is the one generated folder, and the one that most often goes wrong. It is committed because the server does not build anything, and it is replaced in full at every build, so a change made there by hand is lost the next time anyone builds. The build output is committed and served covers what that means for commits and merges.
Reading a repository you have not met
- The README, for the branch mapping and anything unusual.
package.json, for the build commands: Finding and running the build.- The base template, usually under
templates/includes/, that every page extends: where the stylesheets and scripts are loaded, and what the page shell contains. templates/pages/pages/beside the admin's layout list (Customization › Layouts), to see which layout uses which template. A template no layout names is either a partial, a fixed-path template such as an error page, or left over.- The components folder, for the blocks editors assemble pages from.