shane logsdon · php · static sites

Pages are files.
Routes are paths.

flat-file turns a directory of Markdown, HTML, and PHP into a website. A file in pages/ is a URL; a subdirectory is a section. One command exports the result as plain HTML for a static host. The same tree can also run as a flat-file CMS on a PHP server.

Build a site

what it is

zero configuration

The whole configuration is the directory layout. There is no database, no admin screen, and no build manifest: the generator reads pages/, finds a parser for each file, renders it, and writes the matching path into dist/.

pages/: The site. Markdown (.md, .markdown), plain HTML, or PHP. pages/index.php becomes /, pages/about.md becomes /about, and a subdirectory becomes a deeper path.
resources/partials/: The layout. Registered as a Plates template folder named partials, so a page can wrap itself in one shared HTML shell.
public/: Static files — CSS, images, fonts — copied through to the build output unchanged, and served as-is by the development server.
dist/: The artifact: one directory per page with an index.html, plus the copied public/ tree. Nothing to run at the other end.

Markdown is converted with CommonMark, so the syntax is CommonMark rather than a site-specific dialect. Layouts come from league/plates, which is why a page is written the way a PHP template is written. The README sums the intent up as: PHP is easy to install, runs nearly everywhere, and is flexible — the generator is an attempt to see how far PHP reaches in this problem domain.

the family

two repositories

flat-file
The generator: flat-file build and flat-file serve, the file parsers, the Plates wiring, and the optional router for running the same pages as a CMS.
flat-file-starter
An example project: two pages, a composer.json, and a Docker build. Read it to see the shape of a flat-file site. Its deployment notes describe a historical Now/Docker setup, and its ^1.0 dependency does not install on current PHP — see requirements.
The project collection
This microsite is itself built by flat-file, from the same pinned revision the collection hub uses.

status

1.0.3 · mit

Four tags exist: 1.0.0 through 1.0.3. All four declare php ~7.1 and CommonMark ^0.17.5, which is also what the README means by “PHP 7.1+”. None of them installs on PHP 8.3 or later.

The revision this site runs is not one of those tags. It is the dev-code-highlight branch, which drops the PHP version pin, moves to CommonMark 2 and Symfony Console 7, and adds syntax highlighting to fenced code blocks. It is the revision pinned in this site's own composer.lock and in the collection hub's, and it is the only revision whose commands are verified on this site. A tagged release on current PHP has not been made.

This site makes no performance claim, publishes no download count, and does not claim that a 1.0.x install works.

where to go

starting point

Getting started
The static-build quick start: a composer.json, two pages, the shared layout, the build output, and the one PHP-version caveat that decides whether the install works at all.
Source on GitHub
The README, the commands, the parsers, and the test suite.
Packagist
Published versions and their declared requirements.

Pages are files.Routes are paths.

Pages are files.
Routes are paths.