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 Shaikh

Some content wants to be a row in a database, written in a control panel 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 panel, 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.

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