File Pages (Flat-File)

In the flat-file model, the file is the page. A .md file’s path becomes its URL, titles can be derived from the first heading, and no wrapper directory or frontmatter is required. This matches how developers already expect files to work, and it lets Accent serve an existing docs/ folder or repository without restructuring anything.

Layout

content/
  README.md                   # root page (/)
  getting-started/
    README.md                 # /getting-started
    01.installation.md        # /getting-started/installation (order 1)
    02.configuration.md       # /getting-started/configuration (order 2)
  api/
    index.md                  # /api
    01.endpoints.md           # /api/endpoints (order 1)
  architecture-review.md      # /architecture-review
  changelog.md                # /changelog

Directories here are just folders that group files into URL segments – they are not themselves pages unless they contain an index file.

The filename is the URL

installation.md inside getting-started/ produces /getting-started/installation. The path maps directly to the URL; there are no wrapper directories to manage. Renaming the file renames the page.

Numeric prefixes for ordering

Just like directories, files can use 01., 02., etc. to control sort order. The prefix is stripped from the URL – 01.installation.md becomes /getting-started/installation – and is recorded as menu.order: 1. Files without a prefix are unaffected and sort alphabetically after the prefixed ones.

Two safety guards keep ordinary filenames from being mistaken for ordering prefixes:

  • Digit guard – a digit immediately after the dot means a version number, not a prefix: 1.0-release.md keeps its full name.
  • Space guard – a space after the dot means a natural-language title: 24. Dezember 2026.md is left intact.

In both cases the leading number stays part of the URL and no menu.order is inferred.

Directory indices

A README.md, index.md, or default.md inside a directory maps to that directory’s URL. api/index.md serves /api. Matching is case-insensitive, and when several are present the priority is default.md, then README.md, then index.md.

No frontmatter required

Titles are derived from the first # heading in the content, so adding a page is as simple as:

echo '# New Page' > content/new-page.md

When the first heading matches the page title, it is stripped from the rendered body so the theme does not show a duplicate H1. If you set a different title: in frontmatter, both the navigation title and the body heading are kept. When there is no heading at all, the title falls back to the filename converted from kebab-case to Title Case (api-reference.md -> “Api Reference”).

A page has one title, used for its <h1> and the browser tab. When you want a shorter label in navigation – the breadcrumb, the sidebar, the previous/next links, and the top menu – set menu.title. The full title still drives the heading; navigation uses the short label:

---
title: Getting Started with Accent CMS   # page heading and <title>
menu:
  title: Getting Started                 # breadcrumb, sidebar, prev/next, menu
---

When menu.title is omitted, navigation falls back to title, so existing pages are unaffected.

Template fallback

Each file’s stem becomes its candidate template name: installation.md looks for installation.html.jinja. When no such template exists, Accent CMS falls back to default.html.jinja. This means every page renders without any template setup – you only add a named template when a page needs a distinct layout.

Sort order

Use numeric prefixes on filenames (01.intro.md, 02.setup.md) to order pages with no frontmatter; the prefix sets menu.order automatically and is stripped from the URL. You can also set menu.order explicitly – frontmatter always wins over the file prefix:

---
menu:
  order: 2
---

Pages with neither a numeric prefix nor menu.order sort alphabetically by URL.

Creating a file page

cat > content/about.md << 'EOF'
# About Us

Welcome to our about page.
EOF

This produces a page at /about with zero ceremony – the title comes from the heading.

Add media to it

A file page has no folder of its own, so its assets live in a companion directory named after the page:

content/
  about.md          # the page
  about/
    team-photo.jpg  # media for the about page

Add modules to it

Use the same companion directory, with _-prefixed module files or module directories:

content/
  about.md
  about/
    _team.md            # module file (lightweight, no media)
    _values.md          # module file
    _gallery/           # module directory (when the module needs media)
      default.md
      photo.jpg

Module files (_team.md) are the simplest form – a single file with frontmatter and content. Use a module directory (_gallery/default.md) when the module needs its own assets. If both _team.md and _team/default.md exist, the directory form wins. Modules attach to the page whose URL matches the companion directory, so about.md and about/_team.md associate automatically.

When to choose file pages

  • You want to serve an existing docs/ folder or repository without restructuring.
  • You prefer minimal ceremony – adding a page is echo '# New Page' > new-page.md.
  • Your content is text-heavy with few media assets.
  • You want diffs that show the page name, not a wall of identical default.md files.
  • You want GitHub-compatible rendering – README.md files render on GitHub the same way they do here.

When pages carry significant media or are built from modules, the Folder Pages model scopes assets more cleanly. The two can be mixed freely in one site.