Imported from hahwul/hwaro-examples (
examples/perihelion/AGENTS.md). Install upstream withnpx skills add hahwul/hwaro-examples --skill perihelion. Copyright stays with the author.
AGENTS.md - AI Agent Instructions for Hwaro Site
This document provides instructions for AI agents working on this Hwaro-generated website.
Project Overview
This is a static website built with Hwaro, a fast and lightweight static site generator written in Crystal.
Essential Commands
| Command | Description |
|---|---|
hwaro build |
Build the site to public/ directory |
hwaro serve |
Start development server with live reload |
hwaro new <path> |
Create new content from archetype |
hwaro deploy |
Deploy the site (requires configuration) |
hwaro build --drafts |
Include draft content |
hwaro serve -p 8080 |
Serve on custom port (default: 3000) |
hwaro build --base-url "https://example.com" |
Set base URL for production |
Directory Structure
.
├── config.toml # Site configuration
├── content/ # Markdown content files
│ ├── index.md # Homepage (single file, no underscore)
│ ├── about.md # Standalone page
│ └── <section>/ # Section directory (posts/, guide/, chapter-1/, …)
│ ├── _index.md # Section landing page (underscore-prefixed)
│ └── *.md # Pages within the section
├── templates/ # Jinja2 templates (Crinja)
│ ├── header.html # Shared <head> + <body> open
│ ├── footer.html # Shared <body>/<html> close
│ ├── page.html # Page template
│ ├── section.html # Section listing template
│ ├── 404.html # Not-found page
│ ├── partials/ # Reusable fragments (nav, search, sidebar)
│ └── shortcodes/ # Shortcode templates
├── static/ # Static assets (copied as-is)
└── archetypes/ # Content templates for `hwaro new`
Notes for AI Agents
- Front matter can be TOML (
+++), YAML (---), or JSON ({...}at file start). Pick one per file and keep delimiters matched. - Rendered content is
{{ content }}in templates (already-safe HTML — no extra| safeneeded). - Custom metadata is
page.extra.field, notpage.params.field. - Always preview with
hwaro servebefore committing. - Validate front matter syntax (TOML, YAML, or JSON) and
config.tomlafter edits. - Use
{{ base_url }}prefix for URLs in templates. - Escape user content with
{{ value | e }}(or| escape) in templates.
Full Reference
For detailed documentation on content, templates, configuration, and more:
- Hwaro Documentation
- Configuration Guide
- Full LLM Reference — comprehensive reference optimized for AI agents
To generate the full embedded AGENTS.md locally, run:
hwaro tool agents-md --local --write