Install and Run Luax

Make the Luax binary executable and run your first build. This guide covers Windows, macOS, and Linux.

Install and Run Luax

The Luax Binary

Luax Pro includes a pre-compiled binary that runs on Linux, macOS, and Windows. You do not need to compile anything. The binary is already inside the project folder you extracted in the previous guide.

Make It Executable (Linux / macOS)

Open Terminal, navigate to your project folder, and run:

cd ~/Projects/luaxpro
chmod +x luax
chmod +x luax.sh

The chmod +x command tells your operating system that these files are programs, not text documents.

Run Your First Build

Windows

Open Command Prompt in your project folder and run:

luax.bat build

Or, if you added the Luax binary to your PATH:

luax build

Linux / macOS

./luax.sh build

Or directly:

./luax build

What Happens During a Build

When you run luax build, the engine does five things:

1. Reads data/metadata.yaml to load site-wide settings (title, description, navigation, footer)

2. Scans src/ for all markdown files and parses their frontmatter

3. Renders collections — for each folder in src/ (docs, posts, projects, services), it generates a listing page with pagination

4. Renders individual pages — each markdown file becomes an HTML page using its layout

5. Copies public/ to dist/ and generates sitemap.xml, feed.xml, and robots.txt

You will see output like this:

✔ / (home)
✔ /docs/ (page 1/1)
✔ /docs/welcome/
✔ /docs/installation/
✔ /posts/ (page 1/2)
✔ /posts/optimize-luau-performance/
...
Build complete in 0.012s

Run the Local Development Server

To preview your site in a browser:

Windows

luax.bat start

Linux / macOS

./luax.sh start

This starts a local server at http://localhost:8080. Open that URL in your browser. You should see your homepage.

What If the Build Fails?

If you see an error message, check these common issues:

lua: command not found — Lua is not installed or not in your PATH. Go back to the Lua installation guide.

cannot execute binary file — You are running the wrong binary for your operating system. Download the correct Luax Pro package for your OS.

Permission denied — You forgot chmod +x luax. Run it again.

No such file or directory: src/index.md — You are not in the project root folder. Use cd to navigate to the folder containing build.lua.

Next Step

Your site builds and runs locally. The next guide covers running Decap CMS alongside Luax so you can edit content through a graphical interface.