Serving an Existing Directory

Because the file-page model needs no frontmatter and derives titles from headings, Accent CMS can serve an existing directory of markdown as a site without any preparation. This is the fastest way to preview a project’s documentation or turn a folder of notes into a browsable site.

Point --content-dir at any folder

# Serve your project's docs folder
accent serve --content-dir ./docs

# Serve any markdown collection
accent serve --content-dir ~/notes

No restructuring is needed. README.md files become directory indices, titles derive from headings, numeric filename prefixes set the order, and every page renders through the default template.

How it works

Index filenames

Accent recognizes three index filenames (case-insensitive). A file with one of these names maps to its directory’s URL rather than to a child URL:

FilenameConvention
default.mdAccent CMS / Grav
README.mdDocumentation / GitHub
index.mdWeb / static-site

When more than one is present in a directory, priority is default.md, then README.md, then index.md.

Title derivation

When a page has no title: in frontmatter – which is the common case for an existing repository – the title is derived automatically:

  1. The first # heading in the markdown content.
  2. The filename, converted from kebab-case to Title Case, as a fallback when there is no heading.

Template fallback

Each file’s stem becomes its candidate template name; when the theme has no matching template, Accent falls back to default.html.jinja. A folder of plain markdown therefore renders end-to-end with only the default template – no theme work required.

From quick preview to real site

Serving a directory is a starting point, not a dead end. When you want more control, layer it on incrementally:

  • Add a numeric prefix to a filename (01.intro.md) to pin its order.
  • Add a title: or menu.title: to refine navigation labels.
  • Move a page into a folder once it grows media or modules.

Nothing you add invalidates the plain files already there – the two models mix freely.