Clever Paths

Hammer's clever path resolution automatically finds your assets and files, making it easy to reference resources without worrying about exact paths.

Introduction

Hammer uses intelligent path resolution to locate files across your project. Instead of worrying about relative paths or keeping track of where files are located, you can reference them by name and Hammer will find them automatically.

Clever paths help you:

  • Reference files without worrying about paths
  • Move files without breaking links
  • Keep your code clean and readable
  • Work faster with less path management

Basic Usage

To reference an asset, use the @path directive:

<img src="<!-- @path logo.png -->" alt="Logo">

Hammer will automatically search for logo.png across your project and resolve it to the correct path.

How Path Resolution Works

When Hammer encounters a @path directive, it searches for the file in this order:

  1. Current directory: Checks the same directory as the current file
  2. Assets folders: Searches common asset directories (assets/, images/, img/, etc.)
  3. Project root: Looks in the root of your project
  4. Recursive search: Scans subdirectories to find the file
Tip: If multiple files with the same name exist, Hammer uses the closest match to your current file location.

Examples

Images

<img src="<!-- @path hero-image.jpg -->" alt="Hero">

Relative Paths

You can also use relative paths for better organization:

<img src="<!-- @path assets/images/logo.png -->" alt="Logo">
Note: For stylesheets and JavaScript files, use the @@stylesheet and @@javascript directives instead of @@path.

Using relative paths is recommended for larger projects because it:

  • Improves build performance
  • Ensures correct file selection when multiple files share the same name
  • Makes file relationships more explicit

Best Practices

Organizing Assets

  • Place images in an assets/images/ or img/ directory
  • Keep CSS files in assets/css/ or css/
  • Store JavaScript files in assets/js/ or js/
  • Use descriptive, unique filenames to avoid conflicts

Using Relative Paths

  • Use relative paths in larger projects for clarity
  • Specify paths relative to your project structure
  • Keep paths consistent across your project
  • Group related assets in the same directory

Performance

  • Relative paths resolve faster than filename-only references
  • Organize files logically to minimize search time
  • Avoid duplicate filenames when possible

Next Steps

Now that you understand clever paths, learn about: