Nibble Guides

These guides follow one site from an empty directory to production: the marketing site of Tidewater, a small startup that sells invoicing software. Tidewater needs what most young companies need from a website — landing pages that marketing can change without a developer, a blog, a help centre that lives beside the product’s code, and a form that books a demo.

Every guide uses that same site in its examples, so the collection you declare in one is the one you render in the next.

Start here

Pick the route that matches your job. Each is a short list, in reading order.

• I write content. You need nothing technical. Editing content, then Write and organise pages and posts, then Save, preview and publish.
• I administer the site from the Control Plane, without a terminal. Administering from the Control Plane, then Users and roles.
• I run the server. Installing Nibble, then Configuration, Deploying, Backups and Upgrading.
• I build the site. Getting Started with Nibble, then Modelling content.
• I build the theme. Building a theme, then Views and layouts, Content in views, Queries and Forms in your theme.

Getting started

• Start here — what Nibble is, who it suits, and how these guides are organised.
• Getting Started with Nibble — build Tidewater’s site end to end.
• Installing Nibble — what your machine needs and every question the installer asks.

Modelling content

• Modelling content — the three layers of schema, and the commands that write and check them.
• Collections — kinds of content, and the URLs they live at.
• Blueprints and fields — the form an editor fills in, and how fields are laid out.
• Taxonomies — authors, topics and other terms entries relate to.
• Globals and navigation — site-wide settings and menus.
• Forms — the demo request form, from YAML to a page.
• Content as files — Tidewater’s help centre, written as Markdown.
• Form delivery — emailing submissions and sending them to another system.
• Form spam and privacy — bots, retention, encryption, limits and schedules.
• Translating a form — a form’s text per locale.
• Every form key — each key a form file accepts.
• Changing the schema — renaming and removing fields once content exists.
• Scheduled tasks — figures from an API, a feed of jobs, and your own Ruby, on a schedule.

Building a theme

• Building a theme — what a theme holds and how a page is rendered.
• Views and layouts — which view renders which page, and the frame around it.
• Content in views — what a page receives, and what each field looks like.
• Queries — asking for the content a page needs.
• Theme components — rich text, images, blocks, pagination, SEO and menus.
• Forms in your theme — drawing a form and every field.
• Styling and the page shell — theme.css, Tailwind, dark mode, links and head tags.
• SEO, sitemaps and feeds — what search engines and feed readers receive.

Editing content

• Editing content — finding your way around.
• Write and organise pages and posts
• Save, preview and publish
• Add and edit categories and tags
• Upload and manage images and files
• Restore something you deleted
• Build and arrange the site’s menus
• Change the site’s settings
• Find and handle form submissions
• Fix search results, share cards and broken links
• Add analytics and custom code
• Connect an AI app and approve its changes
• Set up your account and sign in safely

Running a site

• Running a site — the guides, and a site’s first week.
• Configuration — config/nibble.yml, environment variables and credentials.
• Users and roles — adding people and deciding what each may do.
• Administering from the Control Plane — what an administrator without a terminal can do.
• Utilities — cache, search, jobs, health, backups and the audit log.
• Webhooks — telling another application when content changes.
• Check messages — every message nibble:check prints, and how to fix it.
• Deploying — Kamal, secrets, the first deploy and what each deploy checks.
• Backups — what is backed up, where, and how to restore it.
• Upgrading — taking a release, and how to undo it.
• Content packages — keeping content as YAML, and importing it.
• Commands — every command in one place.
• Agent access — deciding what connected AI apps may touch.
• The nibble command — starting a site and working on content from a terminal.

Extending Nibble

• Extending Nibble — the seams a site adds its own behaviour through.
• Ruby hooks and events
• Customising the Control Plane
• Emails
• The management API and MCP
• Building with an agent
• The Content API — reading the same content from somewhere else.

Reference

• Reference — look-up pages for blueprints and forms.
• Fieldtypes and field options
• Validation rules
• Conditions

Contributing

• Contributing to Nibble — working on Nibble itself.
• Architecture
• Invariants
• Tests and checks
• Releases