Organize pages into topic folders

What you'll see

A site starts with a few pages and the author drops every .html and .hash file into a single folder: home.html, about.html, pricing.hash, product-a.hash, product-b.hash, support-faq.html, support-contact.html, and so on. As the site grows, this single folder accumulates dozens of files. Finding the right page means scrolling a long, flat list; the author starts encoding the section into the filename (support-faq, product-a) to claw back some grouping; and the URLs come out flat and meaningless — /support-faq, /product-a — with no shared section path to anchor them.

What's actually happening

A page's path on disk maps directly to its public URL. A hash file at #/Products/Pricing.hash is served at /Products/Pricing, and an HTML file at /Support/Contact.html at /Support/Contact — the extension is dropped and spaces become hyphens. Crucially, this mapping includes the folders: subfolders are part of the URL, not just an organisational nicety for the file tree.

This means folders are a first-class part of your site's URL and information architecture. Docly requires no routing configuration or manifest to make this work — creating the folder and putting the page in it is the entire setup. A folder that contains an Index.hash or Index.html is also served automatically at the folder's clean URL, so a topic folder gives you a natural section landing page at /products/ for free.

A single flat folder throws all of this away. Pages from unrelated sections sit side by side; the file list grows without grouping; section landing pages have nowhere to live; and authors resort to encoding the topic into the filename (support-faq.html, product-pricing.hash) to re-create, by hand and inconsistently, exactly the grouping folders give automatically. The resulting URLs (/support-faq) are flatter and less meaningful than the structured ones (/support/faq) the folder layout produces for free.

What to do

Organise pages into topic folders, one folder per section or subject area. Let the folder name carry the topic and the file name carry the specific page. Add an Index file to each folder for its section landing page. The result is readable, RESTful URLs and a file tree that scales.

Do — topic folders with Index landing pages:

#/Products/Index.hash      ->  /Products/
#/Products/Pricing.hash    ->  /Products/Pricing
#/Products/Compare.hash    ->  /Products/Compare
#/Support/Index.html       ->  /Support/
#/Support/FAQ.html         ->  /Support/FAQ
#/Support/Contact.html     ->  /Support/Contact
#/About/Index.html         ->  /About/
#/About/Team.html          ->  /About/Team

Don't — everything flat in one folder with prefixes:

#/products-pricing.hash    ->  /products-pricing
#/products-compare.hash    ->  /products-compare
#/support-faq.html         ->  /support-faq
#/support-contact.html     ->  /support-contact
#/about.html               ->  /about
#/about-team.html          ->  /about-team   // which section?

The page content itself does not change — the same HTML or hash works regardless of which folder it lives in. Only the path, and therefore the URL, changes.

Link to pages by their clean, structured path, and link to a section by its folder with a trailing slash — never with a filename or extension:

<a href="/Products/">Products</a>
<a href="/Products/Pricing">Pricing</a>
<a href="/Support/FAQ">FAQ</a>

These root-relative links are publish-safe: when a site is mounted under a subfolder, Docly rewrites leading-slash href and src attributes automatically. For URLs your JavaScript builds at runtime, use ~/ paths instead. See Use tilde paths in JavaScript and Omit file extensions in links.

A practical rule of thumb: as soon as two pages belong to the same subject, create a folder for them and give it an Index file. Reserve the site root for genuinely top-level pages (the home page in #/Root), and put everything section-specific in its own topic folder. This mirrors the same principle Docly applies to API endpoints — see Group API endpoints into topic folders.