Falz Docs

Falz

Falz is a file-to-file build tool. It reads a source tree, transforms matching files with pipes, combines content with XML-declared layouts, and writes a new tree such as dist/.

It is useful for static sites, documentation, data exports, code generation, and any job where files go in and files come out. Falz does not assume that the input is Markdown or that the output is HTML: those are just common choices.

A common project folder structure looks like this. Falz adds a .falz/ folder for its configuration and build setup; your existing source files can stay where they are, without restructuring or changing their format.

project/                    source tree
├── about.md
├── posts/
├── .falz/
│   ├── config.yaml         project settings
│   ├── schemes/            layouts, fragments, and scheme assets
│   │   ├── layout.xml      source matching and output rules
│   │   └── page.html       layout template
│   ├── pipes/              custom TypeScript pipes
│   └── types/              generated TypeScript declarations
└── dist/                   generated output

The files and directories above have these roles:

  • about.md and posts/ are your source files and directories, which Falz reads to produce output.
  • .falz/config.yaml defines project settings, including the output directory and layout filename pattern.
  • .falz/schemes/ holds the build's layouts, templates, fragments, and scheme-owned assets. layout.xml declares which source files to match, which pipes to run, and where to write results; page.html is a template that wraps transformed content when referenced by the layout.
  • .falz/pipes/ holds custom TypeScript pipes that transform file contents and can optionally prepare cached data during the index phase.
  • .falz/types/ holds generated TypeScript declarations for the APIs available to custom pipes.
  • dist/ contains generated files written by the build phase.

Never hand-edit dist/. Falz can replace or remove anything there.

Start here

Start with Getting started. The guide keeps growing the same small site, introducing features as the project needs them:

  • Getting started makes the first output, then turns Markdown into pages you can preview.
  • Layouts gives those pages shared navigation and styling, then creates a distinct home for posts.
  • Pipes lets posts carry metadata and choose their own URLs.
  • Index phase lets posts discover one another and render a shared list.
  • Build phase uses the completed site to explain what rebuilds when you change it.

Runnable checkpoints let you compare the project along the way or join the guide later. They are complete versions of the same site, not a separate course.

Prefer a conceptual overview? How it works summarizes the model without interrupting the guide.

Reference

The main commands

falz init
falz build
falz watch --serve --hot-reload
falz index                 # only needed by pipes with index()

Run commands from the project root: the directory containing .falz/.