Configuration (hpy.toml)

hpy-tool uses a configuration file named hpy.toml located in the root of your project directory to manage common settings. This allows you to define project structure without relying solely on command-line arguments.

Finding the Configuration

When you run hpy commands like hpy build or hpy -w, the tool automatically searches for hpy.toml by looking in the specified input directory (or the default src/) and then checking its parent directories upwards until it finds the file or reaches the filesystem root.

The directory containing hpy.toml is considered the **project root**. Paths defined within the configuration file are relative to this root, unless specified otherwise.

File Format

The configuration uses the TOML format. All hpy-tool specific settings must reside within the [tool.hpy] table.

# hpy.toml Example

# This table contains all settings for hpy-tool
[tool.hpy]

# Path to the directory containing your source .hpy files and static directory.
# Relative to the project root (where hpy.toml lives).
input_dir = "src"

# Path to the directory where compiled HTML and copied static assets will be placed.
# Relative to the project root.
output_dir = "dist"

# The name of the directory *inside* input_dir that holds static assets.
# Setting this enables static file handling. Contents are copied to output_dir/.
# This line must be uncommented for static files to be processed.
static_dir_name = "static"

# --- Future settings might be added here ---

Available Settings

• input_dir (string, default: "src")

  Specifies the directory containing your source .hpy files (including _layout.hpy) and your static asset directory (named by static_dir_name). Path is relative to the project root.

• output_dir (string, default: "dist")

  Specifies the directory where the compiled HTML files and copied static assets will be generated. Path is relative to the project root.

• static_dir_name (string, default: "static")

  Defines the name of the directory within input_dir that contains your static assets (e.g., CSS, images, fonts). This setting must be explicitly defined (uncommented) in hpy.toml to enable static asset handling. If enabled, files and directories from // will be copied to // during builds and synced during watch mode.

Precedence Rules

Settings are determined based on the following order of precedence (highest priority first):

1. Command-Line Arguments: Flags like -o or providing a specific SOURCE path on the command line always override any other settings.
2. hpy.toml Settings: If a setting is not provided via a CLI argument, the value defined in the [tool.hpy] table of hpy.toml is used.
3. Built-in Defaults: If a setting is not provided via CLI or hpy.toml, the tool falls back to its built-in defaults (e.g., input_dir = "src", output_dir = "dist").

This allows you to set up standard project conventions in hpy.toml while still having the flexibility to override them for specific commands when needed.