Content Organization

Accent CMS supports two ways to organize content on the filesystem. Both are first-class – the same engine discovers and serves them through a single code path. There is no configuration toggle; you choose by how you name your files. This page explains the two models conceptually and how they differ; the linked chapters below cover each one in depth.

The Two Models at a Glance

	Folder pages (Grav-style)	File pages (flat-file)
A page is…	a directory with an index file inside	a markdown file
Best for	media-rich sites, landing pages	documentation, wikis, lightweight sites
Page-local media	files next to the index attach to that page	files in a companion directory attach to the page
Page modules	_hero/default.md composes into the parent	companion directory with _hero.md files or _hero/ subdirectories
Sort order	01., 02. prefix on directories	01., 02. prefix on files or menu.order in frontmatter
Template name	always the index filename stem (default)	the content filename stem (installation, endpoints)
Frontmatter needed	typical	optional – titles derive from # headings

Both models produce the same Page struct internally. Hierarchy, collections, taxonomy, and static builds work identically regardless of storage model.

How the Two Models Differ

The two models answer one question differently: what is a page on disk?

• In the folder model, a page is a directory. The folder name is the URL, an index file (default.md) holds the content, and everything else in the folder – images, modules, child folders – is scoped to that page. Content and its assets travel together.

• In the file model, a page is a single markdown file. The file’s path is the URL, the content is the file, and assets (if any) live in a separate companion directory. There is no wrapper folder and no required frontmatter.

Every other difference follows from that one choice:

• URLs. Folder pages derive the URL from the directory name; file pages derive it from the filename. Both strip numeric ordering prefixes (02.blog/ and 02.blog.md each serve /blog).

• Media scoping. A folder page owns the assets sitting beside its index, so each page namespaces its own cover.jpg. A file page has no folder of its own, so its assets live in a companion directory named after the page.

• Modules. Both models compose pages from _-prefixed modules, but a folder page keeps them inside itself (_hero/) while a file page keeps them in its companion directory (_hero.md).

• Ordering. Both use numeric prefixes (01., 02.) for sort order, on the directory name or the filename respectively, with menu.order frontmatter available as an override.

• Templates and frontmatter. Folder pages almost always use default.md and so share one default.html.jinja, usually with explicit frontmatter. File pages take their template name from the filename stem (falling back to default.html.jinja) and can omit frontmatter entirely – titles come from the first # heading.

Crucially, this is a storage distinction only. Once parsed, a folder page and a file page are the same kind of object; nothing downstream – navigation, collections, feeds, the static build – can tell them apart.

Choosing a Model

You do not have to pick one for the whole site – the models mix freely – but a few guidelines help:

1. Pick one model per site and be consistent where you can. The engine handles mixing, but authors benefit from predictability.

2. Use folder pages for content-heavy sites with images, modules, and structured navigation. The Grav-style model gives you page-local media scoping and composable landing pages.

3. Use file pages for documentation and lightweight sites. The flat-file model matches how developers expect files to work, and README.md rendering parity with GitHub is a strong advantage for open-source projects.

4. Reach for the other model per page when it clearly pays off – a single media-rich landing page in an otherwise flat docs site is fine as a folder.

5. Use --content-dir for existing directories. Point Accent at a project’s docs/ folder or a repository root and it serves immediately, no restructuring needed.

In This Chapter

• Folder Pages (Grav-Style) – the directory-is-the-page model: index files, page-local media, modules, and template selection.
• File Pages (Flat-File) – the file-is-the-page model: URL-from-filename, numeric ordering prefixes, heading-derived titles, and navigation labels.
• Mixing Both Models – how the two coexist in one tree, a task-by-task comparison, and how to avoid URL collisions.
• Serving an Existing Directory – turn any folder of markdown into a site with --content-dir, no restructuring.
• Pages and Document Models – how a page’s location and frontmatter bind it to a document model, and which fields a model may govern.