Skip to content

A folder of Markdown can be a collection

0.7.0 lets a collection read its pages from a folder of files. This site's documentation is the first thing built on it.

Mahfuz Shaikh1 min read

A folder of Markdown files beside the addresses they're served at, marked 0.7.0

Some content wants to be a row in a database, written in a Control Plane by whoever is closest to it. Other content wants to be a file: reviewed as a diff, moved with a rename, and impossible to change without someone seeing the change. Documentation is the second kind, which is why 0.7.0 teaches a collection to read a folder.

Name a folder inside content/ in the collection's schema and bin/rails nibble:content:markdown makes the collection match it. A file is a page. A folder's index.md is the page its files sit under. Frontmatter becomes fields, links between files are rewritten to references so they survive a rename, and a page whose file has gone is trashed. It is safe to run twice, so a deploy can run it every time.

The trade is that those pages are read-only in the Control Plane, and each one says which file it came from. That is the point rather than a limitation: two sources of truth for the same page is a bug waiting for a deadline.

A documentation page in the Control Plane, read-only, noting the Markdown file it's written in

How it works, in full

The behaviours that catch people out are written down, including what happens when a folder has no index.

Content written as files