Confused about directory structure

Hello all!

In 2017 I build silverstripe site with a lot of custom page types (build in SS V. 3.3)
In spring this year I’ve tried to upgrade to SS V 4.0 which ends up in a desaster…
Now I decided to completely rebuild the old code to new version.
I’m confused about the directory structure, due to many different decriptions.

shows an other structure as discribed under

Same differences in naming the config file (*.yml) of custom configuration:
app.yml, mysite.yml, config.yml. Waht is the right one?

As a first test I have placed a simple in /app/templates .
This is used but style sheets and images are not found.
Documentation says to put style sheets in /app/css and images in /app/mages etc.
Further on in documentation appears an other “template” directory named
/themes//templates (this equals v3 hierarchy)
But nothing works for me (I always modified theme.yml accordingly)

Has someone an idea, how I can restart my project with correct directory structure and naming convention?

BTW: what’s about namespaces in “SpecialPage.php”/“SpecialPageController.php”?
Is it

namespace SilverStripe\app;


thank you!

Hi @elruo, I don’t think you have to use /app for your project code, that’s just the new convention. You’ll just need to make sure that this entry in your project configuration matches the name of your project folder::

  project: app # could be 'mysite' or whatever you want

Likewise app.yml is just convention, you can have many config files and name them whatever you like.

For your css and images, it sounds like you are making use of the public directory, which is great, but if you do that then any assets which are not under the public directory but need to be publicly accessible need to be ‘exposed’ by adding an entry to your composer.json file and running composer vendor-expose. See

Namespacing your own code is optional. Personally I don’t do it, because it’s simpler not to, and I don’t work in a team so no one can tell me off :grinning_face_with_smiling_eyes:. You can put your own code in whatever namespace you like - but it should be semantic, so you might want to use your company name or the project name as your top level namespace for user code.

Hello @JonoM,
thank you for your answers and descriptions!

Yes, I know, many defintions are conventions. I’m a fan of these and try to stick on it.
Okay, in detail I have two configs in my “_config” direcory:


content of “app.yml” is

Name: myproject
  project: app

content of theme.yml is

Name: mytheme
    - 'customer_z'
    - '$default'
  default_locale: 'de_DE'

Directory “/themes” holds two sub-directories “simple” and “customer_z”.
I’ve expected, the framework/cms takes the styles/images/javascript from


defined by above configuration and references in “” like

<link href="$Themedir/css/styles.css" rel="stylesheet" />

But somethings is wrong here and I can’t figure out what it is.
Tested a lot of combinations in config-files, references in “*.ss” and so on. :frowning:

What’s wrong? Are the assets not being found by the browser (ie. 404 errors)? If so, then did you expose them as described in the link Jono posted?

If that’s not it, are you seeing some other error somewhere?

Hello again!

I’ve double checked all pathes and did a composer vendor-expose again.
There were no errors reported and my theme appears in its messages too:

Exposing web directories for silverstripe-recipe silverstripe/installer with method auto:
  - themes/customer_z/css
  - themes/customer_z/images
  - themes/customer_z/javascript

Sorry for my vague description in my first post.
Here what happens:
the start page uses correct styles etc. from theme directory and default from /app/templates. In all other page types not:
the is always used the default layout with styles from

<link rel="stylesheet" type="text/css" href="[/resources/vendor/silverstripe/framework/client/styles/debug.css?m=1552959273" />

And now I realized what goes wrong: in backend I choose i.e. one of my pages types SpecialPage which is shown as “Special Page (Silverstrip\Azt\SpecialPage)”.
After saving the page (no errors shown) it was resetted to “Virtual Page (Silverstripe\CMS\Model\VirtualPage)”!

Strange, I never got that behavior in SS 3.