What Is a Controller?
In Luax Pro, every folder inside src/ that contains a collection also has a controller file at src/. For example:
| Controller file | Controls collection |
|---|---|
src/docs.md | src/docs/ |
src/posts.md | src/posts/ |
src/projects.md | src/projects/ |
src/services.md | src/services/ |
The controller file does not contain an article. It contains settings for the collection: title, description, layout, pagination size, and — for some collections — custom sections, navigation, or hero fields.
How Controllers Differ from Items
Controller (src/docs.md) — one file per collection. Defines how the listing page looks and behaves. Edited through the Site Settings collection in Decap CMS.
Items (src/docs/welcome.md, src/docs/installation.md) — many files per collection. Each one is a single page. Edited through the Docs Pages, Blog Posts, Projects, or Services collection in Decap CMS.
If you want to change the docs page heading, edit src/docs.md. If you want to change the welcome article content, edit src/docs/welcome.md.
Via Decap CMS
1. Open http://localhost:8080/admin/
2. Click Site Settings in the left sidebar
3. You will see these controllers listed as single files:
- Metadata (
data/metadata.yaml) - Index (
src/index.md) - About (
src/about.md) - Contact (
src/contact.md) - Docs (
src/docs.md) - FAQ (
src/faq.md) - Home (
src/home.md) - Privacy (
src/privacy.md)
4. Click any controller to edit its fields
5. Click Publish when done
Note: src/posts.md, src/projects.md, and src/services.md are not in the Site Settings list because they use layout: collections.lax and only need a title, description, and pagination. Those three fields are set directly in the markdown file, not through Decap CMS.
Via Code
Here is the controller file for each collection:
src/docs.md — docs controller with custom hero and sections:
layout: docs-single.lax
title: Luax Pro Documentation
description: Complete guide to installing, configuring, and deploying Luax Pro.
pagination: 24
src/posts.md — blog controller:
title: Roblox Luau Engineering Blog
description: Deep dives into Luau script performance and DataStore reliability.
layout: collections.lax
pagination: 6
src/projects.md — projects controller:
title: Shipped Roblox Games & Case Studies
description: Filter our portfolio across simulators, obstacle courses, and tycoons.
layout: collections.lax
pagination: 6
src/services.md — services controller:
title: Roblox Development & Luau Services
description: Modular engineering packages and full-game production for studios.
layout: collections.lax
pagination: 6
The `pagination` Field
The pagination field controls how many items appear per page on the listing. For example, pagination: 6 means each page shows 6 items, and Luax generates /posts/, /posts/page/2/, /posts/page/3/, and so on.
If you have 7 blog posts and pagination: 6, Luax generates two pages: page 1 with 6 posts, page 2 with 1 post.
The `layout` Field
The layout field tells Luax which template to use for the listing page:
collections.lax— generic card grid with pagination. Use for posts, projects, services.docs.lax— documentation layout with search bar and section cards. Use for docs.
If you change layout: collections.lax to layout: docs-single.lax on the posts controller, your blog listing will render with the docs layout. Probably not what you want, but it is possible.
Adding a New Collection
To add a new collection:
1. Create a folder src/
2. Create a controller src/ with layout: collections.lax, title, description, and pagination
3. Add markdown files to src/ with layout: page.lax or a custom layout
4. Luax automatically generates /, /, and so on
No code changes needed. The collection system is automatic.
Common Mistake: Wrong Layout
If your docs controller uses layout: collections.lax instead of layout: docs-single.lax, the docs listing page will render without the search bar or section cards. Always match the layout to the collection type.
Next Step
Controllers are understood. The next guide covers adding and editing docs collection items.