Getting started

Nibble is a content management system you run as your own application. These pages cover installing it, writing in it, building a theme for it, and working on it.

Installing

What your machine needs, what the installer asks, and what to do when it finishes.

Content written as files

Turn a folder of Markdown into a collection, the way these pages work.

Schema

Collections, taxonomies, blueprints and the files that declare them.

Views and queries

How a template gets its data, and how a page is rendered.

Editing content

Entries, assets, publishing, forms and SEO in the control panel.

Working on Nibble

Architecture, tests, releases and the invariants that hold.

Quick start

Nibble is installed by cloning it: the repository is the application, and upgrades arrive as releases you merge into your own copy. Plan about ten minutes, most of it spent downloading dependencies.

Installing it

The installer asks a handful of questions, writes your answers into .nibble/install.yml, and leaves you with a site you can run.

./install.sh my-site
cd my-site
bin/dev

Open http://localhost:3100 for the site and http://localhost:3100/admin for the control panel.

Warning

Nibble expects a deploy step. If you were hoping to upload files to shared hosting and run everything from a browser, this is not the CMS for you.

Declaring your first collection

A collection is a file. This one says that posts exist, that they live at /blog/{slug}, and which blueprint gives them their fields.

# schema/collections/posts.yml
schema: 1
title: Posts
route: /blog/{slug}
dated: true
blueprints: [post]
template: posts/show
search: site
sort: published_at:desc

Run bin/rails nibble:check after editing anything under schema/. It tells you what is wrong before the control panel does.

Note

Change a file and the control panel changes with it. There is no migration to write and no button to press: the schema is the source of truth.

Basic usage

Writing the content

Most content belongs in the control panel, where whoever is closest to it can write without asking a developer. Some content does not — documentation, a changelog, reference pages that change in the same pull request as the code they describe. For those, a folder of Markdown can be the collection. These pages are exactly that.

Rendering a page

A view gets its data from a file beside it, then renders it as a Vue component with server-side rendering, so visitors get HTML immediately.

# views/posts/index.yml
params: [page]
posts:
  from: entries:posts
  paginate: { per_page: 12 }

Deploying it

One machine, one SQLite file. Kamal takes the container up, bin/rails nibble:content:markdown runs at start-up so merged pages publish themselves, and a backup is a copy of a file.

Getting help

Reading further

Every section of these pages explains why before how, with complete examples rather than fragments. If you are setting a site up, start with Installing. If you are building a theme, start with Schema.

Reporting something

An issue that says what you expected and what happened is worth more than a patch that guesses. The repository is where that conversation happens.

A CMS your repository owns.