Getting started

Start with one text file. Once you can see how it reaches the output directory, turn the same project into a small website. The following chapters keep growing this site; the runnable examples provide complete checkpoints if you want to compare files or join later.

Install from source

From the Falz repository:

make falz
install -m 755 bin/falz ~/.local/bin/falz
falz --version

Use another directory on your PATH if preferred. Create a separate directory for the site:

mkdir tiny-site
cd tiny-site
falz init

Run subsequent commands from tiny-site, the directory containing .falz/. The generated .falz/config.yaml is ready to use:

output: dist
pipes:
  - md

Unspecified settings use defaults. You can leave them alone for now; Configuration documents them when needed.

A file goes in, a file comes out

The generated .falz/schemes/layout.xml contains:

<Layout tpl="{{body}}">
  <Content name="body" src="*.txt" to="{FILENAME}.txt"/>
</Layout>

Create a source file and build:

printf 'Hello, Falz.\n' > hello.txt
falz build

Open dist/hello.txt: it contains the same text.

The content rule matches hello.txt. With no pipe selected, its bytes pass through unchanged. Those bytes fill the {{body}} slot in the inline template, and {FILENAME} becomes hello in the destination.

This is already a complete Falz build. The copy example contains this exact checkpoint.

The project has three parts

The successful build gives us a useful way to read the project:

tiny-site/
├── hello.txt                source: the files being processed
├── .falz/
│   ├── config.yaml          project settings
│   └── schemes/
│       └── layout.xml       scheme: rules and supporting files
└── dist/
    └── hello.txt            output: generated files

Source and scheme are separate. Your documents stay in the source tree; templates and build rules live in .falz/schemes/. Falz skips .falz/ and the output directory when scanning source files.

A source file only produces output if a layout rule matches it. The rule chooses its pipe and destination, so neither input format nor output format is fixed. We will use Markdown and HTML for this guide, but the same arrangement works for data exports or code generation.

Never edit dist/ by hand. Change the source or scheme and build again.

Give the text a presentation

Keep working in the same directory. Remove the text source:

rm hello.txt

Create about.md:

# About

This page came from **Markdown**.

Also create index.md, so the site has a home page:

# Tiny site

Welcome to my site. Read [about it](/about.html).

Create .falz/schemes/page.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Tiny site</title>
  </head>
  <body>
    <main>{{body}}</main>
    <script src="/falz-hotreload.js"></script>
  </body>
</html>

Replace .falz/schemes/layout.xml:

<Layout src="page.html">
  <Content name="body" src="*.md" pipe="md" to="{FILENAME}.html"/>
</Layout>

falz build

Now about.md becomes dist/about.html and index.md becomes dist/index.html. The built-in md pipe converts each document to HTML; the template supplies the surrounding page.

The old dist/hello.txt may remain: incremental builds do not prune disappeared entries by default. Run falz clean orphans output to remove it. Later, Build phase explains automatic cleanup and the state Falz tracks.

See changes as you write

falz watch --serve --hot-reload

Open the printed URL, usually http://localhost:8080/. Watch performs an initial build and rebuilds when relevant files change. The script we added reloads the browser after a successful rebuild. If the default port is busy, the server selects a nearby port and prints it.

Both pages now share their outer HTML, but they have no shared navigation or styling. In Layouts, we will add those without repeating them in every source document.