Docly Developers
Knowledge base Pitfall By design

A folder takes precedence over a file with the same name

In shortIf a folder and a file share a name (Foo.hash and the folder Foo), the folder wins: /Foo answers 301 to /Foo/, which renders the folder's index.hash, and the file becomes unreachable. Creating the folder takes the page over immediately – build the folder under a temporary name and rename it when it is ready.
Applies to FoldersHash templates

  1. What you'll see

    A single landing page should grow into a section with its own subpages – for example Kunstig intelligens.hash (served at /kunstig-intelligens) should become an overview with pages under /kunstig-intelligens/ai-agent, /kunstig-intelligens/chatbot and so on. The natural step is to create a folder with the same name next to the file and start adding pages to it.

  2. What's actually happening

    Verified with a scratch file and a scratch folder of the same name on a live site:

    • /name answers 301 to /name/.
    • /name/ renders the folder's index.hash. The file with the same name is no longer reachable.
    • /name/subpage renders pages in the folder as normal.

    So the moment the folder exists, it takes the URL over from the file – before you have put anything in it. An empty folder without index.hash turns a working page into a 404.

    The upside: the old address keeps working through the 301, so moving a page into a same-name folder needs no redirect file.

  3. What to do

    Do – build under a temporary name, rename when ready:

    1. Create the folder under a name that is not in use (e.g. kunstig-intelligens-ny), with index.hash and the subpages. Review it at its temporary URL.
    2. Take a copy of the old file (docly get --raw).
    3. Rename the folder to the final name (docly rename). From this moment the folder serves /name/, and /name answers 301 to it.
    4. Delete the old file – it is unreachable anyway, and leaving it invites confusion.
    5. Update the sitemap (/name/ instead of /name) and internal links.

    Don't create the final folder first and fill it afterwards – the live page is gone until index.hash is in place.

    If index.hash lists the folder's pages, derive the folder from the request instead of hard-coding it, so the same file works at the temporary and the final name.

Last reviewed 24 Sep 2026