Who this is for. A developer joining a site that already exists. Afterwards you can recognise the shape of the repository in front of you, know which differences matter, and find your way around it in a few minutes instead of a few days.
There is no single prescribed layout. A repository reflects the year it was started, the build tool its first developer preferred and how much the site has grown. Learn to recognise the shapes, and do not reorganise one you inherit to match another: a layout record in the admin names each page template by its path, so keep every page template at the path its layout names.
Four shapes side by side
Four production repositories, counted by tracked files:
| Large, Twig | Medium, Smarty | Medium, Smarty, gulp | Small, Smarty | |
|---|---|---|---|---|
| Tracked files | about 1,500 | about 700 | about 580 | about 290 |
templates/ | 495 | 392 | 208 | 101 |
| Source | src/ 427, TypeScript and SCSS | src/ 250 | src/ 249 | src/ 129 |
| Build output | dist/ 80 | dist/ 38 | static/ 108 | dist/ 52 |
| Served as is | assets/ 446 | assets/ 2, failover/ 10 | none | none |
| Build configuration | .build/webpack.*.js | webpack.*.js at the root | config/gulp.js with webpack inside | webpack.*.js at the root |
| Engine set by | a tracked .settings.json | the default | the default | the default |
The large repository serves several brands from one codebase, so it carries an assets/ folder of brand images and a stylesheet entry per brand. The medium one keeps a static failover page in the repository. The small one is a plain marketing site. None of them is wrong.
What is the same in all of them
templates/is the largest or close to it, laid out by module, with page templates undertemplates/pages/pages/.- There is one base template that every page extends, and it links the built CSS and JavaScript.
- The build output is committed, and the platform builds nothing.
- There is no application code: What is not in it.
Reading a repository you have not met
- Find the engine. A
.settings.jsonwith{"Globals": {"template": {"engine": "Twig"}}}, or{%tags in the templates, means Twig; otherwise Smarty. Tell whether a site is Smarty or Twig in thirty seconds. - Read
package.json. Itsscriptsblock tells you the build tool, the output folder and which commands exist: Webpack and gulp builds. - Open the base template. Search
templates/for<html; it is usuallytemplates/includes/…/base-template.htmlortemplates/includes/base.html. Follow what it includes, which bundles it links, and where it prints scripts. - Map layouts to templates. In the admin, each layout names its template. The layouts list tells you which files in
templates/pages/pages/are live and which are leftovers. - Read
.gitignorebefore you trust what is committed: Check what is ignored. - Read the history of the build output (
git log -- dist/): long gaps between source changes and output changes mean someone has been deploying from an unbuilt branch.