Keep index.hash out of content folders

1. What you'll see

   A developer — or an AI code-generation tool — scaffolds a Docly site and gives every content folder its own listing template: Customers/index.hash, Products/index.hash, News/index.hash. Each copy works, so nothing looks wrong. But the same template now exists once per folder, every layout change is a multi-file edit across all of them, and every new folder either gets yet another copy pasted in — or renders with no listing at all.

2. What's actually happening

   index.hash never needs to live inside a content folder. When Docly resolves a request for a file inside a folder, it looks in this order: the requested path itself, then #/Root/<path> (and #/Root/<path>/Index), then #/Folder/<name> — and the first match wins. Parent folders are not searched. That fallback chain means one #/Folder/index.hash is automatically the listing template for every folder in the workspace, and #/Root/index.hash is served at / as the site's home page.

   The #/Root/ tree also mirrors the content tree, so you can be as specific as you like without ever putting a file in the content folder itself. A template at #/Root/Customers/level2/index.hash applies to only the Customers/level2 folder — it overrides the shared default for that path alone, while every other folder keeps falling back to #/Folder/index.hash. This is the clean way to give one folder a bespoke listing: the override lives in the developer-only #/ tree, addressed by path, rather than as a file dropped next to the data.

   Placing index.hash files inside the content tree therefore buys nothing, and costs three things:

   • Duplication and drift. The template is copied once per folder. A layout change becomes a find-and-replace across the workspace, and the one folder that gets missed renders subtly differently from the rest.
   • Exposure to non-developer users. The #/ tree is invisible to everyone without developer access, but an index.hash sitting next to data files shows up in directory listings, search and pickers for admin users and content editors — who can edit, move or delete it. See Separate code from content for non-developer users.
   • Inconsistent new folders. When per-folder copies are the mechanism, a new folder without one has no listing until someone remembers to paste the template in. With #/Folder/index.hash, every new folder is covered from the moment it is created.
3. What to do

   Keep index.hash in the developer-only #/ tree:

   • Home page → #/Root/index.hash. Served at /.
   • Folder listings → one #/Folder/index.hash. Inherited by every folder that does not provide its own.

   Before — one copy per folder, next to the data:

   Customers/
     ├── index.hash         ← copy 1
     └── Acme Corp.docly
   Products/
     ├── index.hash         ← copy 2, already drifting
     └── Widget.docly
   News/
     └── 2026-07-01.docly   ← new folder, no listing yet

   After — one template, every folder covered:

   Customers/
     └── Acme Corp.docly
   Products/
     └── Widget.docly
   News/
     └── 2026-07-01.docly
   
   #/                       ← invisible to non-developer users
     ├── Folder/
     │   └── index.hash     ← listing for all three folders
     └── Root/
         └── index.hash     ← home page, served at /

   Need one folder to look different? Address it by path inside the #/Root/ tree, which mirrors the content tree: put the bespoke template at #/Root/Customers/level2/index.hash and it applies to only that folder, while every other folder keeps inheriting #/Folder/index.hash. The override stays in the developer-only #/ tree — invisible and untouchable to non-developer users — instead of sitting next to the data.

   A folder-local index.hash inside the content folder does the same job, because the folder itself is checked first, but it drops the template back into the content tree where content editors and admins can see, move or delete it. Reserve that for cases where the override genuinely belongs to the content (for example, a one-off page a content owner maintains). Otherwise prefer the path-addressed #/Root/ override, or make the shared #/Folder/index.hash smarter — branching on folder name or schema — over scattering override files where non-developer users can touch them.

   See The Root folder and The Folder folder for the full resolution rules.

Last reviewed 04 Jul 2026