What Is the Docs Collection?
The src/docs/ folder contains all documentation pages. Each .md file becomes a page at /docs/. For example:
src/docs/welcome.md→/docs/welcome/src/docs/installation.md→/docs/installation/src/docs/run-decap-local.md→/docs/run-decap-local/
Every docs file uses layout: docs-single.lax in its frontmatter so it inherits the documentation layout with navigation, search, and footer.
Via Decap CMS
1. Open http://localhost:8080/admin/
2. Click Docs Pages in the left sidebar
3. You will see a list of existing docs pages
4. Click any page to edit its title, description, or body
5. Click New Docs Page to create a new one
6. Fill in:
- Title — the page heading and browser tab title
- Description — the meta description for SEO
- Body — the markdown content
7. Click Publish
The new file is saved to src/docs/ automatically. The slug is generated from the title.
Via Code
Create a new file in src/docs/. For example, src/docs/deployment.md:
layout: docs-single.lax
title: Deploy Your Site
description: Learn how to deploy a Luax Pro site to Netlify, Vercel, or Cloudflare Pages.
image: /images/luax-logo.webp
## Deployment Options
Luax Pro outputs static HTML files to the `dist/` folder. You can deploy that folder to any static host.
## Netlify
1. Push your project to GitHub
2. Connect the repo to Netlify
3. Set build command to `luax build`
4. Set publish directory to `dist`
5. Click Deploy
## Vercel
1. Import your GitHub repo to Vercel
2. Set output directory to `dist`
3. Click Deploy
Linking a New Doc in the Controller
After creating the file, you need to add it to the src/docs.md sections so it appears on the docs landing page:
sections:
- title: Getting Started
items:
- title: Why Lua SSG
url: /docs/welcome/
- title: Install Lua 5.4
url: /docs/installation/
- title: Deployment
items:
- title: Deploy Your Site
url: /docs/deployment/
Without this entry, the new doc is accessible at its URL but does not appear on the docs landing page.
Searching New Docs
The docs search bar (/js/docs-search.js) fetches /sitemap.xml and filters URLs containing /docs/. When you add a new file to src/docs/, Luax automatically includes it in sitemap.xml on the next build. The search picks it up without any code changes.
File Naming Rules
Use lowercase letters and hyphens. Do not use spaces, underscores, or uppercase:
Good: update-metadata.md, run-decap-local.md, installation.md
Bad: Update Metadata.md, run_decap_local.md, Installation.md
The filename becomes the URL slug. update-metadata.md becomes /docs/update-metadata/.
Ordering Pages
Luax Pro does not have a built-in order field like Docusaurus. The order of documentation pages is controlled by two things: the filename of each markdown file, and the docs_use_sidebar flag in data/metadata.yaml.
Filename Prefix Controls Order
Every doc file in src/docs/ should start with a number prefix that reflects its position in the reading flow. For example:
src/docs/01-welcome.md
src/docs/02-installation.md
src/docs/03-download-luax.md
src/docs/04-install-luax.md
src/docs/05-run-decap-local.md
src/docs/06-login-decap.md
src/docs/07-update-metadata.md
src/docs/08-update-home.md
The number prefix forces both the automatic listing and the sidebar to render in the intended order. Without a prefix, files are sorted alphabetically by filename, which may not match your intended flow (for example, installation would appear before welcome).
Two Ordering Modes
The docs_use_sidebar flag in data/metadata.yaml controls which ordering method the /docs/ landing page uses:
docs_use_sidebar: true — The landing page reads docs_sidebar and renders one card per item, in the exact order you list them. Use this when you want full manual control, custom group headings, and custom link labels.
docs_use_sidebar: false — The landing page ignores docs_sidebar and instead loops every file in src/docs/, sorted alphabetically by filename. Use this when you want zero maintenance. The number prefix (01-, 02-, 03-) ensures the automatic order matches your intended flow.
Reordering Docs
When docs_use_sidebar: true — Edit data/metadata.yaml, move items within their group in the docs_sidebar array, or move them to a different group. Save and rebuild.
When docs_use_sidebar: false — Rename the markdown file. For example, to move installation before welcome, rename 01-welcome.md to 02-welcome.md and 02-installation.md to 01-installation.md. The automatic listing follows the new numeric order.
Custom Sidebar via Metadata
The sidebar on detail pages always reads docs_sidebar from data/metadata.yaml. Even when docs_use_sidebar: false, the sidebar is populated from docs_sidebar. This means you can have automatic card listing on the landing page but still show a curated sidebar on every detail page.
If you want to use the custom sidebar:
1. Set docs_use_sidebar: true in data/metadata.yaml
2. Define your groups and items in docs_sidebar
3. Each group has a title and an items array
4. Each item has a title, url, and optional description
5. Save and rebuild
If you want to use the automatic loop:
1. Set docs_use_sidebar: false in data/metadata.yaml
2. Name your files with numeric prefixes (01-, 02-, 03-)
3. Keep docs_sidebar populated if you want the detail page sidebar to show anything
4. Save and rebuild
Common Mistake: Missing Layout
If you create a new file and forget layout: docs-single.lax, it will not render with the documentation layout. It will use the default page.lax layout instead, which has no docs navigation and no sidebar. Always include the layout field at the top of every doc file:
layout: docs-single.lax
title: Your Page Title
description: Your meta description.
image: /images/luax-logo.webp
Next Step
Docs collection is understood. The next guide covers the services collection.