# Hwaro
Fast and lightweight static site generator built with Crystal

Base URL: https://hwaro.hahwul.com

This is documentation for Hwaro, an open-source static site generator. Content is provided under the MIT license.

---

Title: Hwaro Documentation
URL: https://hwaro.hahwul.com/
Source: content/index.md

Hwaro(화로) is a fast, lightweight static site generator built with Crystal.

---

Title: Deploy
URL: https://hwaro.hahwul.com/deploy/
Source: content/deploy/_index.md

Deploy your Hwaro site to any static hosting provider.

## Build for Production

```bash
hwaro build
```

This generates static files in `public/`. You can optionally minify output:

```bash
hwaro build --minify
```

This performs conservative optimization — HTML comments and trailing whitespace are removed, JSON/XML whitespace is compacted. All code blocks and content structure are preserved.

## General Steps

1. Build the site: `hwaro build`
2. Upload `public/` directory to your host (or use `hwaro deploy`)
3. Configure your domain

## Built-in Deploy Command

Hwaro includes `hwaro deploy` for deploying to configured targets:

```bash
hwaro deploy              # Deploy to default target
hwaro deploy --target s3  # Deploy to specific target
hwaro deploy --dry-run    # Preview changes
```

See [Deploy Configuration](/deploy/config/) for full target setup, matchers, and options.

## Platform Guides

See the platform-specific guides below for step-by-step deployment instructions.

---

Title: Cloudflare Pages
URL: https://hwaro.hahwul.com/deploy/cloudflare-pages/
Source: content/deploy/cloudflare-pages/index.md

Deploy your Hwaro site to Cloudflare Pages for fast global delivery.

## Quick Start

### Generate Config

```bash
hwaro tool platform cloudflare
```

This creates a `wrangler.toml` with project settings and site bucket configuration.

### Deploy via Dashboard

1. Go to [Cloudflare Dashboard](https://dash.cloudflare.com) > **Workers & Pages**
2. Click **Create application** > **Pages** > **Connect to Git**
3. Select your repository
4. Set build configuration:
   - **Build command**: `hwaro build`
   - **Build output directory**: `public`
5. Click **Save and Deploy**

### Deploy via Wrangler CLI

```bash
# Install Wrangler
npm install -g wrangler

# Build the site
hwaro build

# Deploy
wrangler pages deploy public --project-name my-site
```

## Manual Configuration

If you prefer to configure manually, set these in the Cloudflare Pages dashboard:

| Setting | Value |
|---------|-------|
| Build command | `hwaro build` |
| Build output directory | `public` |

Or create `wrangler.toml`:

```toml
name = "my-site"
compatibility_date = "2024-01-01" # Use current date when deploying

[site]
  bucket = "./public"
```

## Redirects

Cloudflare Pages uses a `_redirects` file in the output directory. Create `static/_redirects` with redirect rules for your page aliases:

```
/old-url/ /posts/new-post/ 301
/legacy/post/ /posts/new-post/ 301
```

Aliases are defined in page frontmatter:

```markdown
---
title: New Post
aliases:
  - /old-url/
  - /legacy/post/
---
```

When using `hwaro tool platform cloudflare`, the generated `wrangler.toml` includes comments listing these redirects so you can copy them into `static/_redirects`.

## Custom Domain

1. Go to **Workers & Pages** > your project > **Custom domains**
2. Click **Set up a custom domain**
3. Follow DNS configuration instructions
4. Update `base_url` in `config.toml`:

```toml
base_url = "https://www.yourdomain.com"
```

## Preview Deployments

Cloudflare Pages automatically creates preview deployments for every branch push. Preview URLs follow the pattern: `<branch>.<project>.pages.dev`.

## See Also

- [Platform Config Generator](/start/tools/platform/) — Detailed generator options
- [CLI Reference](/start/cli/#tool) — All tool commands
- Other platforms: [Netlify](/deploy/netlify/) | [Vercel](/deploy/vercel/) | [GitHub Pages](/deploy/github-pages/)

---

Title: Deploy Configuration
URL: https://hwaro.hahwul.com/deploy/config/
Source: content/deploy/config.md

Configure deployment targets for the `hwaro deploy` command in `config.toml`.

## Global Options

```toml
[deployment]
target = "prod"
source_dir = "public"
confirm = false
dry_run = false
max_deletes = 256
workers = 10
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| target | string | — | Default target name to deploy to |
| source_dir | string | "public" | Directory containing the built site |
| confirm | bool | false | Prompt for confirmation before deploying |
| dry_run | bool | false | Show what would be deployed without making changes |
| force | bool | false | Force deployment even if no changes detected |
| max_deletes | int | 256 | Safety limit on file deletions (-1 disables the limit) |
| workers | int | 10 | Number of concurrent workers |

## Targets

Define one or more deployment targets:

```toml
[[deployment.targets]]
name = "prod"
url = "file:///var/www/mysite"

[[deployment.targets]]
name = "s3"
url = "s3://my-bucket"
# Auto-generates: aws s3 sync {source}/ s3://my-bucket --delete

[[deployment.targets]]
name = "custom"
url = "s3://my-bucket"
command = "aws s3 sync {source}/ {url} --delete --exclude '.git/*'"
# Custom command overrides auto-generation
```

**Auto-generated commands by URL scheme:**

| Scheme | Command | Requires |
|--------|---------|----------|
| `file://` | Built-in directory sync | — |
| `s3://` | `aws s3 sync {source}/ {url} --delete` | AWS CLI |
| `gs://` | `gsutil -m rsync -r -d {source}/ {url}` | Google Cloud SDK |
| `az://` | `az storage blob sync --source {source} --container {url}` | Azure CLI |

If a `command` field is set, it always takes priority over auto-generation.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| name | string | — | Target identifier |
| url | string | — | Destination URL (`file://`, `s3://`, `gs://`, `az://`) |
| include | string | — | Glob pattern for files to include |
| exclude | string | — | Glob pattern for files to exclude |
| strip_index_html | bool | false | Remove `index.html` from URLs |
| command | string | — | Custom command (overrides auto-generation) |

Custom commands support placeholders:

| Placeholder | Description |
|-------------|-------------|
| `{source}` | Source directory (default: `public`) |
| `{url}` | Target URL |
| `{target}` | Target name |

## Matchers

Configure per-file deployment settings using pattern matchers:

```toml
[[deployment.matchers]]
pattern = "^.+\\.css$"
cache_control = "max-age=31536000"
gzip = true

[[deployment.matchers]]
pattern = "^.+\\.html$"
cache_control = "max-age=3600"
gzip = true
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| pattern | string | — | Regex pattern to match file paths |
| cache_control | string | — | Cache-Control header value |
| content_type | string | — | Override Content-Type header |
| gzip | bool | false | Gzip compress matched files |
| force | bool | false | Always upload matched files |

## See Also

- [CLI Reference](/start/cli/) — All deploy command-line options
- [Features: Deployment](/features/deployment/) — Quick overview

---

Title: Docker
URL: https://hwaro.hahwul.com/deploy/docker/
Source: content/deploy/docker/index.md

Deploy your Hwaro site using Docker.

## Official Image

The official Docker image is available at `ghcr.io/hahwul/hwaro`.

```bash
docker pull ghcr.io/hahwul/hwaro:latest
```

## Multi-stage Build

You can use a multi-stage build to compile your site and serve it with a lightweight web server like Nginx.

Create a `Dockerfile` in your project root:

```dockerfile
# Stage 1: Build the site
FROM ghcr.io/hahwul/hwaro:latest AS builder

WORKDIR /site
COPY . .

# Build the site
RUN hwaro build

# Stage 2: Serve with Nginx
FROM nginx:alpine

# Copy built assets from builder stage
COPY --from=builder /site/public /usr/share/nginx/html

# Expose port 80
EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]
```

### Build and Run

```bash
# Build the image
docker build -t my-hwaro-site .

# Run the container
docker run -d -p 8080:80 my-hwaro-site
```

Visit `http://localhost:8080` to see your site.

## CLI Usage

You can run Hwaro commands directly using the Docker image without installing Crystal or Hwaro locally.

```bash
# Build the site
docker run --rm -v $(pwd):/site -w /site ghcr.io/hahwul/hwaro build

# Interactive shell
docker run --rm -it -v $(pwd):/site -w /site ghcr.io/hahwul/hwaro /bin/sh
```

## See Also

- [Deploy Configuration](/deploy/config/) — Target setup and matchers
- [CLI Reference](/start/cli/) — All build/deploy options
- Other platforms: [GitHub Pages](/deploy/github-pages/) | [Netlify](/deploy/netlify/) | [Vercel](/deploy/vercel/)

---

Title: GitHub Pages
URL: https://hwaro.hahwul.com/deploy/github-pages/
Source: content/deploy/github-pages/index.md

Deploy your Hwaro site to GitHub Pages for free hosting.

## Prerequisites

- GitHub repository
- Hwaro site ready to build

## Method 1: GitHub Actions (Recommended)

Use the official [`hahwul/hwaro`](https://github.com/hahwul/hwaro) action to build and deploy without installing Hwaro manually.

### Create Workflow

You can auto-generate the workflow file using:

```bash
hwaro tool platform github-pages
```

Or create `.github/workflows/deploy.yml` manually:

```yaml
---
name: Hwaro CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Build Only
        uses: hahwul/hwaro@main
        with:
          build_only: true

  deploy:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Build and Deploy
        uses: hahwul/hwaro@main
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
```

### Action Inputs

| Input | Description | Default |
|-------|-------------|---------|
| `build_dir` | Directory containing the Hwaro site | `.` (repository root) |
| `build_only` | Only build without deploying | `false` |
| `token` | GitHub token for deployment | — |

If your Hwaro site is in a subdirectory (e.g., `docs/`), set `build_dir`:

```yaml
- name: Build and Deploy
  uses: hahwul/hwaro@main
  with:
    build_dir: "docs"
    token: ${{ secrets.GITHUB_TOKEN }}
```

### Configure GitHub Pages

1. Go to repository **Settings** → **Pages**
2. Under "Build and deployment", select **Deploy from a branch**
3. Choose `gh-pages` branch, `/ (root)` folder
4. Push to `main` branch to trigger deployment

### Set Base URL

Update `config.toml`:

```toml
# For user/org site (username.github.io)
base_url = "https://username.github.io"

# For project site (username.github.io/repo)
base_url = "https://username.github.io/repo"
```

## Method 2: Deploy via `hwaro deploy`

Create a deploy script `scripts/deploy-ghpages.sh`:

```bash
#!/bin/bash
set -e

SOURCE_DIR="${1:?Usage: deploy-ghpages.sh <source-dir>}"
REMOTE_URL=$(git remote get-url origin)
TMPDIR=$(mktemp -d)

cp -r "$SOURCE_DIR"/. "$TMPDIR"
touch "$TMPDIR/.nojekyll"

cd "$TMPDIR"
git init -b gh-pages
git add -A
git commit -m "Deploy to GitHub Pages"
git push --force "$REMOTE_URL" gh-pages

rm -rf "$TMPDIR"
```

```bash
chmod +x scripts/deploy-ghpages.sh
```

Add the target to `config.toml`:

```toml
[[deployment.targets]]
name = "github-pages"
command = "scripts/deploy-ghpages.sh {source}"
```

Then build and deploy:

```bash
hwaro build
hwaro deploy github-pages

# Preview without deploying
hwaro deploy github-pages --dry-run
```

### Configure GitHub Pages

1. Go to repository **Settings** → **Pages**
2. Under "Build and deployment", select **Deploy from a branch**
3. Choose `gh-pages` branch, `/ (root)` folder
4. Click **Save**

## Method 3: Manual Branch Deploy

```bash
hwaro build

# Create orphan branch
git checkout --orphan gh-pages

# Remove all files
git rm -rf .

# Copy built site
cp -r public/* .

# Commit and push
git add .
git commit -m "Deploy site"
git push origin gh-pages --force

# Return to main branch
git checkout main
```

## Custom Domain

### Configure DNS

Add a CNAME record pointing to `username.github.io`:

| Type | Name | Value |
|------|------|-------|
| CNAME | www | username.github.io |
| A | @ | 185.199.108.153 |
| A | @ | 185.199.109.153 |
| A | @ | 185.199.110.153 |
| A | @ | 185.199.111.153 |

### Add CNAME File

Create `static/CNAME`:

```
www.yourdomain.com
```

### Update Config

```toml
base_url = "https://www.yourdomain.com"
```

### Enable HTTPS

1. Go to repository **Settings** → **Pages**
2. Check **Enforce HTTPS**

## Troubleshooting

### 404 Errors

- Check `base_url` matches your GitHub Pages URL
- Ensure CNAME file is in `static/` directory
- Wait a few minutes for deployment to complete

### Assets Not Loading

- Verify `base_url` has no trailing slash
- Check asset paths use `{{ base_url }}` prefix

### Build Failures

- Review Actions logs for error messages
- Check that `build_dir` points to the correct directory

## Example Repository Structure

```
my-site/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── content/
├── templates/
├── static/
│   └── CNAME
├── config.toml
└── README.md
```

## See Also

- [Deploy Configuration](/deploy/config/) — Target setup and matchers
- [CLI Reference](/start/cli/) — All deploy command options
- Other platforms: [GitLab CI](/deploy/gitlab-ci/) | [Netlify](/deploy/netlify/) | [Vercel](/deploy/vercel/)

---

Title: GitLab CI
URL: https://hwaro.hahwul.com/deploy/gitlab-ci/
Source: content/deploy/gitlab-ci/index.md

Deploy your Hwaro site using GitLab CI/CD.

## Quick Start

Auto-generate the config file:

```bash
hwaro tool platform gitlab-ci
```

## Configuration

Or add `.gitlab-ci.yml` to your repository manually:

```yaml
image: ghcr.io/hahwul/hwaro:latest

pages:
  script:
    - hwaro build
  artifacts:
    paths:
      - public
  only:
    - main
```

This configuration uses the official Hwaro Docker image to build your site and deploys the `public` directory to GitLab Pages.

## See Also

- [Deploy Configuration](/deploy/config/) — Target setup and matchers
- [CLI Reference](/start/cli/) — All deploy command options
- Other platforms: [GitHub Pages](/deploy/github-pages/) | [Netlify](/deploy/netlify/) | [Vercel](/deploy/vercel/)

---

Title: Netlify
URL: https://hwaro.hahwul.com/deploy/netlify/
Source: content/deploy/netlify/index.md

Deploy your Hwaro site to Netlify with automatic builds and global CDN.

## Quick Start

### Generate Config

```bash
hwaro tool platform netlify
```

This creates a `netlify.toml` with build settings, redirects from aliases, and cache headers.

### Deploy via Git

1. Push your repository to GitHub, GitLab, or Bitbucket
2. Go to [Netlify](https://app.netlify.com) and click **Add new site** > **Import an existing project**
3. Connect your repository
4. Netlify will auto-detect `netlify.toml` settings
5. Click **Deploy site**

## Manual Configuration

If you prefer to configure manually instead of using the generator, create `netlify.toml`:

```toml
[build]
  command = "hwaro build"
  publish = "public"

[build.environment]
  # Set environment variables as needed
```

## Redirects

Page aliases defined in frontmatter are automatically included as 301 redirects when using `hwaro tool platform netlify`:

```markdown
---
title: New Post
aliases:
  - /old-url/
  - /legacy/post/
---
```

Generates:

```toml
[[redirects]]
  from = "/old-url/"
  to = "/posts/new-post/"
  status = 301

[[redirects]]
  from = "/legacy/post/"
  to = "/posts/new-post/"
  status = 301
```

## Custom Domain

1. Go to **Site settings** > **Domain management**
2. Click **Add custom domain**
3. Follow the DNS configuration instructions
4. Update `base_url` in `config.toml`:

```toml
base_url = "https://www.yourdomain.com"
```

## Deploy Previews

Netlify automatically creates deploy previews for pull requests. Preview builds use a temporary URL, so override the base URL using a deploy context:

```toml
[context.deploy-preview]
  command = "hwaro build --base-url $DEPLOY_PRIME_URL"
```

`$DEPLOY_PRIME_URL` is a Netlify-provided environment variable containing the unique preview URL (e.g., `https://deploy-preview-42--your-site.netlify.app`).

## See Also

- [Platform Config Generator](/start/tools/platform/) — Detailed generator options
- [CLI Reference](/start/cli/#tool) — All tool commands
- Other platforms: [Vercel](/deploy/vercel/) | [Cloudflare Pages](/deploy/cloudflare-pages/) | [GitHub Pages](/deploy/github-pages/)

---

Title: Vercel
URL: https://hwaro.hahwul.com/deploy/vercel/
Source: content/deploy/vercel/index.md

Deploy your Hwaro site to Vercel with zero-config deployments.

## Quick Start

### Generate Config

```bash
hwaro tool platform vercel
```

This creates a `vercel.json` with build settings, redirects from aliases, and cache headers.

### Deploy via Git

1. Push your repository to GitHub, GitLab, or Bitbucket
2. Go to [Vercel](https://vercel.com) and click **Add New** > **Project**
3. Import your repository
4. Vercel will auto-detect `vercel.json` settings
5. Click **Deploy**

## Manual Configuration

If you prefer to configure manually, create `vercel.json`:

```json
{
  "buildCommand": "hwaro build",
  "outputDirectory": "public"
}
```

## Redirects

Page aliases defined in frontmatter are automatically included as 301 redirects when using `hwaro tool platform vercel`:

```markdown
---
title: New Post
aliases:
  - /old-url/
---
```

Generates:

```json
{
  "redirects": [
    {
      "source": "/old-url/",
      "destination": "/posts/new-post/",
      "statusCode": 301
    }
  ]
}
```

## Custom Domain

1. Go to **Settings** > **Domains**
2. Add your custom domain
3. Follow DNS configuration instructions
4. Update `base_url` in `config.toml`:

```toml
base_url = "https://www.yourdomain.com"
```

## Preview Deployments

Vercel automatically creates preview deployments for every push to non-production branches. No additional configuration is needed.

## See Also

- [Platform Config Generator](/start/tools/platform/) — Detailed generator options
- [CLI Reference](/start/cli/#tool) — All tool commands
- Other platforms: [Netlify](/deploy/netlify/) | [Cloudflare Pages](/deploy/cloudflare-pages/) | [GitHub Pages](/deploy/github-pages/)

---

Title: Features
URL: https://hwaro.hahwul.com/features/
Source: content/features/_index.md

Hwaro ships with a comprehensive set of built-in features — no plugins required. All features are configured through `config.toml` and work out of the box once enabled.

## At a Glance

**SEO & Discovery** — Sitemap, RSS/Atom feeds, robots.txt, OpenGraph, Twitter Cards, structured data (JSON-LD), and auto-generated OG images.

**Content** — Syntax highlighting, search index generation, pagination, markdown extensions (footnotes, task lists, math, mermaid), series, and related posts.

**Performance** — Incremental builds, streaming builds for large sites, asset pipeline with minification and fingerprinting, image processing with responsive variants and LQIP placeholders, and cache busting.

**Files & Environment** — Environment variables, environment-specific config overrides, auto-includes for CSS/JS, and content file publishing.

**Platform** — Multilingual support, image processing, PWA, AMP, and built-in deployment to multiple targets.

---

Title: AMP
URL: https://hwaro.hahwul.com/features/amp/
Source: content/features/amp.md

Hwaro can automatically generate AMP (Accelerated Mobile Pages) versions of your content alongside the regular pages.

## How It Works

1. Regular pages are rendered normally
2. After rendering, Hwaro reads each page's HTML and creates an AMP-compliant version
3. AMP pages are written under a configurable path prefix (default: `/amp/`)
4. A `<link rel="amphtml">` tag is injected into the canonical page's `<head>`

## Configuration

```toml
[amp]
enabled = true
path_prefix = "amp"
sections = ["posts"]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Enable AMP page generation |
| path_prefix | string | "amp" | URL prefix for AMP pages |
| sections | array | [] | Sections to generate AMP for (empty = all) |

## What Gets Converted

The AMP converter automatically applies these transformations:

| Original | AMP Version |
|----------|-------------|
| `<html>` | `<html amp>` |
| `<img>` | `<amp-img layout="responsive">` |
| `<video>` | `<amp-video layout="responsive">` |
| `<iframe>` | `<amp-iframe layout="responsive">` |
| `<script>` (inline) | Removed |
| `style="..."` attributes | Removed |
| `onclick` handlers | Removed |

Additionally injected:
- AMP boilerplate CSS
- AMP runtime script (`cdn.ampproject.org/v0.js`)
- `<link rel="canonical">` pointing to the original page

## Output Structure

Given a page at `/posts/hello/`, the output is:

```
public/
  posts/hello/index.html       ← canonical (has <link rel="amphtml">)
  amp/posts/hello/index.html   ← AMP version
```

## Section Filtering

By default, AMP pages are generated for all sections. Use `sections` to limit:

```toml
[amp]
enabled = true
sections = ["posts", "blog"]   # Only these sections get AMP versions
```

## Custom Path Prefix

```toml
[amp]
enabled = true
path_prefix = "mobile"    # /mobile/posts/hello/ instead of /amp/posts/hello/
```

## See Also

- [Configuration](/start/config/) — Full config reference
- [SEO](/features/seo/) — Sitemaps, feeds, and OpenGraph

---

Title: Asset Pipeline
URL: https://hwaro.hahwul.com/features/asset-pipeline/
Source: content/features/asset-pipeline.md

Hwaro includes a built-in asset pipeline that bundles, minifies, and fingerprints CSS and JS files for production-ready output.

## Features

- **Bundling** — Combine multiple CSS/JS files into single bundles
- **Minification** — Remove comments and whitespace for smaller files
- **Fingerprinting** — Content-hash filenames for cache busting (e.g., `style.a1b2c3d4.css`)
- **Template helper** — `{{ asset(name="style.css") }}` resolves to the fingerprinted path

## Configuration

Add an `[assets]` section to `config.toml`:

```toml
[assets]
enabled = true
minify = true
fingerprint = true

[[assets.bundles]]
name = "main.css"
files = ["css/reset.css", "css/style.css"]

[[assets.bundles]]
name = "app.js"
files = ["js/util.js", "js/app.js"]
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | bool | `false` | Enable the asset pipeline |
| `minify` | bool | `true` | Minify CSS/JS output |
| `fingerprint` | bool | `true` | Add content hash to filenames |
| `source_dir` | string | `"static"` | Directory containing source files |
| `output_dir` | string | `"assets"` | Output subdirectory in the build output |

### Bundle definition

Each `[[assets.bundles]]` entry defines a single output file:

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Output filename (e.g., `"main.css"`) |
| `files` | array | Source files relative to `source_dir` |

Files are concatenated in the order listed.

## Template Usage

Use the `asset()` function in templates to reference bundled assets:

```html
<link rel="stylesheet" href="{{ asset(name='main.css') }}">
<script src="{{ asset(name='app.js') }}"></script>
```

When fingerprinting is enabled, this resolves to the hashed path:

```html
<link rel="stylesheet" href="https://example.com/assets/main.a1b2c3d4.css">
```

When the asset is not found in the pipeline manifest (e.g., not configured as a bundle), the function falls back to returning the path as-is under `base_url`.

`asset_url` is available as an alias for `asset`.

## How It Works

1. During the Initialize phase, the pipeline reads source files from `source_dir`
2. Files listed in each bundle are concatenated in order
3. If `minify` is enabled, CSS/JS-specific minification is applied
4. If `fingerprint` is enabled, an 8-character SHA-256 hash is inserted before the extension
5. The output is written to `{output_dir}/{output_name}` in the build directory
6. A manifest mapping original names to output paths is stored for template resolution

### Minification

The built-in minifiers are conservative and safe:

**CSS:**
- Removes comments (`/* ... */`)
- Collapses whitespace
- Removes whitespace around `{`, `}`, `:`, `;`, `,`
- Strips trailing semicolons before `}`

**JS:**
- Removes single-line comments (`// ...`) outside strings
- Removes multi-line comments (`/* ... */`)
- Preserves string literals (single, double, and template)
- Removes blank lines

For more aggressive minification, use [build hooks](/features/build-hooks/) with external tools like `esbuild` or `terser`.

## Examples

### Basic CSS bundle

```toml
[assets]
enabled = true

[[assets.bundles]]
name = "style.css"
files = ["css/normalize.css", "css/base.css", "css/layout.css"]
```

```html
<link rel="stylesheet" href="{{ asset(name='style.css') }}">
```

### Multiple bundles

```toml
[assets]
enabled = true

[[assets.bundles]]
name = "vendor.css"
files = ["css/vendor/normalize.css", "css/vendor/highlight.css"]

[[assets.bundles]]
name = "site.css"
files = ["css/base.css", "css/components.css"]

[[assets.bundles]]
name = "app.js"
files = ["js/search.js", "js/nav.js"]
```

### Development without fingerprinting

```toml
[assets]
enabled = true
minify = false
fingerprint = false

[[assets.bundles]]
name = "style.css"
files = ["css/style.css"]
```

## See Also

- [Cache Busting](/features/cache-busting/) — Query-string based cache invalidation for non-pipeline assets
- [Auto Includes](/features/auto-includes/) — Automatically load CSS/JS from static directories
- [Build Hooks](/features/build-hooks/) — Run external tools before/after builds

---

Title: Auto Includes
URL: https://hwaro.hahwul.com/features/auto-includes/
Source: content/features/auto-includes.md

Auto Includes automatically load CSS and JS files from specified static directories into all pages. This eliminates the need to manually add each asset file to templates.

## Configuration

Enable in `config.toml`:

```toml
[auto_includes]
enabled = true
dirs = ["assets/css", "assets/js"]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Enable auto includes |
| dirs | array | [] | Directories under `static/` to scan |

## Directory Structure

Place CSS and JS files in subdirectories of `static/`:

```
static/
├── assets/
│   ├── css/
│   │   ├── 01-reset.css
│   │   ├── 02-typography.css
│   │   └── 03-layout.css
│   └── js/
│       ├── 01-utils.js
│       └── 02-app.js
```

Files are scanned recursively from `static/{dir}/**/*.css` and `static/{dir}/**/*.js`.

## File Ordering

Files are included in **alphabetical order**. Use numeric prefixes to control the load order:

```
assets/css/
├── 01-reset.css        ← loaded first
├── 02-typography.css
├── 03-layout.css
└── 99-overrides.css    ← loaded last
```

## Template Variables

### CSS Only

Place in `<head>` to include only CSS files:

```jinja
<head>
  {{ auto_includes_css | safe }}
</head>
```

### JS Only

Place before `</body>` to include only JS files:

```jinja
<body>
  ...
  {{ auto_includes_js | safe }}
</body>
```

### All Assets

Include both CSS and JS together:

```jinja
{{ auto_includes | safe }}
```

| Variable | Description |
|----------|-------------|
| auto_includes_css | `<link>` tags for CSS files |
| auto_includes_js | `<script>` tags for JS files |
| auto_includes | Both CSS and JS tags combined |

## Generated Output

Given the example directory structure above, the template variables produce:

**`auto_includes_css`:**

```html
<link rel="stylesheet" href="/assets/css/01-reset.css">
<link rel="stylesheet" href="/assets/css/02-typography.css">
<link rel="stylesheet" href="/assets/css/03-layout.css">
```

**`auto_includes_js`:**

```html
<script src="/assets/js/01-utils.js"></script>
<script src="/assets/js/02-app.js"></script>
```

## Full Template Example

```jinja
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>{{ page.title }} - {{ site.title }}</title>
  {{ highlight_css | safe }}
  {{ auto_includes_css | safe }}
</head>
<body>
  {% block content %}{% endblock %}

  {{ highlight_js | safe }}
  {{ auto_includes_js | safe }}
</body>
</html>
```

## Tips

- **Separate concerns**: Use `auto_includes_css` in `<head>` and `auto_includes_js` before `</body>` for optimal page loading.
- **Multiple directories**: You can list multiple directories to scan. Each directory is scanned independently.
- **No duplicates**: Each file is included only once, even if it appears in multiple scanned directories.
- **Static files only**: Auto includes scan the `static/` directory. Files in `content/` are not included.

## See Also

- [Configuration](/start/config/) — Full configuration reference
- [Syntax Highlighting](/features/syntax-highlighting/) — Highlight.js asset inclusion
- [Data Model](/templates/data-model/) — Asset template variables

---

Title: Build Hooks
URL: https://hwaro.hahwul.com/features/build-hooks/
Source: content/features/build-hooks.md

Build hooks allow you to run custom shell commands before and after the build process. This is useful for tasks like installing dependencies, preprocessing data, optimizing assets, or triggering deployments.

## Configuration

Define hooks in `config.toml`:

```toml
[build]
hooks.pre = ["npm install", "npx tsc"]
hooks.post = ["npm run minify", "npx pagefind --site public"]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| hooks.pre | array | [] | Commands to run **before** building |
| hooks.post | array | [] | Commands to run **after** building |

## How It Works

### Pre-Build Hooks

Pre-build hooks run **before** any content processing begins. They are ideal for:

- Installing dependencies
- Compiling assets (TypeScript, Sass, etc.)
- Running data fetching scripts
- Preprocessing content

```toml
[build]
hooks.pre = [
  "npm ci",
  "npx tailwindcss -i src/input.css -o static/assets/css/main.css",
  "python scripts/fetch-data.py"
]
```

If a pre-build hook **fails** (exits with a non-zero status), the build process is **aborted**. This prevents building with missing dependencies or broken assets.

### Post-Build Hooks

Post-build hooks run **after** the site has been generated in the output directory. They are ideal for:

- Optimizing images
- Minifying assets
- Generating search indexes (e.g., Pagefind)
- Deploying the site
- Running validation checks

```toml
[build]
hooks.post = [
  "npx imagemin public/images/* --out-dir=public/images",
  "npx pagefind --site public",
  "./scripts/deploy.sh"
]
```

If a post-build hook **fails**, a warning is shown but the build is **not** considered failed. The generated site remains intact.

## Execution Order

Commands are executed **sequentially** in the order they are defined:

```toml
[build]
hooks.pre = ["echo Step 1", "echo Step 2", "echo Step 3"]
```

Output:

```
Running pre-build hook: echo Step 1
Step 1
Running pre-build hook: echo Step 2
Step 2
Running pre-build hook: echo Step 3
Step 3
```

## Serve Mode

Build hooks also run during `hwaro serve`:

- Hooks execute on the **initial build** when the server starts
- Hooks **re-execute on each rebuild** triggered by file changes
- Config changes are picked up automatically — if you modify `hooks.pre` or `hooks.post` in `config.toml`, the new commands take effect on the next rebuild

## Use Cases

### TypeScript Compilation

```toml
[build]
hooks.pre = ["npx tsc --outDir static/assets/js"]
```

### Tailwind CSS

```toml
[build]
hooks.pre = [
  "npx tailwindcss -i src/styles.css -o static/assets/css/styles.css --minify"
]
```

### Pagefind Search

Generate a client-side search index after build:

```toml
[build]
hooks.post = ["npx pagefind --site public"]
```

### Image Optimization

```toml
[build]
hooks.post = [
  "npx imagemin public/**/*.{jpg,png} --out-dir=public"
]
```

### Custom Deploy Script

```toml
[build]
hooks.post = ["./scripts/deploy.sh"]
```

### Full Pipeline Example

```toml
[build]
hooks.pre = [
  "npm ci",
  "npx tsc",
  "npx tailwindcss -i src/input.css -o static/assets/css/main.css --minify"
]
hooks.post = [
  "npx pagefind --site public",
  "npx imagemin public/images/* --out-dir=public/images",
  "echo 'Build complete!'"
]
```

## Error Handling

| Hook Type | On Failure |
|-----------|------------|
| Pre-build | ❌ Build **aborted** — no content is processed |
| Post-build | ⚠️ Warning shown — generated site is preserved |

This design ensures that critical setup tasks (pre-build) must succeed, while optional optimization tasks (post-build) don't block the build output.

## Tips

- **Keep hooks fast**: Slow hooks run on every rebuild during `hwaro serve`. Consider caching or conditional execution.
- **Use scripts for complexity**: For multi-step processes, write a shell script and call it from the hook: `hooks.pre = ["./scripts/setup.sh"]`
- **Check dependencies**: Use `command -v` to check if tools are available before running them:
  ```bash
  command -v npx >/dev/null 2>&1 && npx pagefind --site public
  ```
- **Combine with Auto Includes**: Use pre-build hooks to compile CSS/JS, then let [Auto Includes](/features/auto-includes/) pick them up automatically.

## See Also

- [Configuration](/start/config/) — Full configuration reference
- [Auto Includes](/features/auto-includes/) — Automatic CSS/JS loading
- [Search](/features/search/) — Search index with Pagefind post-build hook
- [Deploy](/deploy/) — Deployment options

---

Title: Cache Busting
URL: https://hwaro.hahwul.com/features/cache-busting/
Source: content/features/cache-busting.md

Cache busting automatically appends a `?v=<hash>` query parameter to locally served CSS and JS resource URLs. This forces browsers to fetch the latest version of assets when their content changes, preventing stale cached files from being used.

## How It Works

Hwaro computes an MD5 content hash of your local CSS/JS files and appends the first 8 characters as a query parameter. The hash only changes when file contents actually change, so browsers keep using their cache until a real update occurs.

```html
<!-- With cache busting (default) -->
<link rel="stylesheet" href="/assets/css/highlight/github.min.css?v=3a8f1b2c">
<script src="/assets/js/highlight.min.js?v=3a8f1b2c"></script>
<link rel="stylesheet" href="/assets/css/style.css?v=3a8f1b2c">

<!-- Without cache busting -->
<link rel="stylesheet" href="/assets/css/highlight/github.min.css">
<script src="/assets/js/highlight.min.js"></script>
<link rel="stylesheet" href="/assets/css/style.css">
```

## Content Hash vs Timestamp

Hwaro uses a **content-based hash** rather than a build timestamp. This means:

- The hash stays the same across builds if files haven't changed — no unnecessary cache invalidation
- The hash changes immediately when any CSS/JS file content is modified
- Different build machines produce the same hash for identical files

## CDN URLs Are Not Modified

Cache busting only applies to **local** resource URLs. CDN URLs (e.g., cdnjs.cloudflare.com) already contain version numbers in their paths and are not modified:

```html
<!-- CDN URL — unchanged -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">

<!-- Local URL — cache busted -->
<link rel="stylesheet" href="/assets/css/highlight/github.min.css?v=3a8f1b2c">
```

## Affected Template Variables

Cache busting applies to the following template variables:

| Variable | Description |
|----------|-------------|
| `highlight_css` | Syntax highlighting CSS (local only) |
| `highlight_js` | Syntax highlighting JS (local only) |
| `highlight_tags` | Combined highlighting CSS + JS (local only) |
| `auto_includes_css` | Auto-included CSS files |
| `auto_includes_js` | Auto-included JS files |
| `auto_includes` | Combined auto-included CSS + JS |

## Disabling Cache Busting

Cache busting is enabled by default. To disable it, use the `--skip-cache-busting` flag:

```bash
# Build without cache busting
hwaro build --skip-cache-busting

# Serve without cache busting
hwaro serve --skip-cache-busting
```

This can be useful when you manage cache invalidation through other means (e.g., filename hashing, CDN purge).

## See Also

- [Syntax Highlighting](/features/syntax-highlighting/) — Highlight.js configuration
- [Auto Includes](/features/auto-includes/) — Automatic CSS/JS loading
- [CLI](/start/cli/) — Command-line options

---

Title: Content Files
URL: https://hwaro.hahwul.com/features/content-files/
Source: content/features/content-files.md

Non-Markdown files placed in the `content/` directory can be automatically published to the output directory. This is useful for images, PDFs, and other assets that live alongside your content.

## Configuration

Enable content file publishing in `config.toml`:

```toml
[content.files]
allow_extensions = ["jpg", "jpeg", "png", "gif", "svg", "webp", "pdf"]
disallow_extensions = ["psd", "ai"]
disallow_paths = ["drafts/**", "**/_*"]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| allow_extensions | array | [] | File extensions to publish |
| disallow_extensions | array | [] | File extensions to exclude |
| disallow_paths | array | [] | Glob patterns for paths to exclude |

## How It Works

When content file publishing is enabled, Hwaro copies non-Markdown files from `content/` to the output directory, preserving their directory structure.

### Example

```
content/
├── about/
│   ├── index.md          → /about/index.html
│   ├── team-photo.jpg    → /about/team-photo.jpg
│   └── resume.pdf        → /about/resume.pdf
├── blog/
│   ├── _index.md         → /blog/index.html
│   └── my-post/
│       ├── index.md      → /blog/my-post/index.html
│       ├── diagram.svg   → /blog/my-post/diagram.svg
│       └── screenshot.png → /blog/my-post/screenshot.png
└── index.md              → /index.html
```

Files are copied directly to the matching output path. The `content/` prefix is stripped automatically.

## Extension Matching

### Allow List

Only files with extensions in `allow_extensions` are published:

```toml
[content.files]
allow_extensions = ["jpg", "jpeg", "png", "gif", "svg", "webp"]
```

Extensions are normalized — both `"jpg"` and `".jpg"` are accepted.

### Deny List

Exclude specific extensions with `disallow_extensions`:

```toml
[content.files]
allow_extensions = ["jpg", "png", "gif", "svg"]
disallow_extensions = ["psd", "ai", "sketch"]
```

The deny list takes priority over the allow list.

### Path Exclusion

Exclude files by path pattern using glob syntax:

```toml
[content.files]
disallow_paths = ["drafts/**", "**/_*", "private/**"]
```

| Pattern | Matches |
|---------|---------|
| `drafts/**` | All files under `content/drafts/` |
| `**/_*` | Any file starting with underscore |
| `private/**` | All files under `content/private/` |

Paths are matched relative to the `content/` directory.

## Referencing Content Files

### In Markdown

Reference colocated files with relative paths:

```markdown
![Team Photo](team-photo.jpg)

[Download Resume](resume.pdf)

![Diagram](diagram.svg)
```

### In Templates

For page bundles, colocated assets are also available via `page.assets`:

```jinja
{% for asset in page.assets %}
  {% if asset is matching("[.](jpg|png|gif)$") %}
    <img src="{{ get_url(path=asset) }}" alt="Asset">
  {% endif %}
{% endfor %}
```

## Content Files vs Static Files

| Feature | Content Files (`content/`) | Static Files (`static/`) |
|---------|---------------------------|--------------------------|
| Colocated with content | ✅ Yes | ❌ No |
| Requires configuration | ✅ Yes | ❌ No (always copied) |
| Extension filtering | ✅ Yes | ❌ No |
| Path filtering | ✅ Yes | ❌ No |
| Best for | Per-page assets | Site-wide assets |

Use **content files** for assets that belong to specific pages (screenshots, diagrams, attachments). Use **static files** for site-wide assets (CSS, JS, logos, favicons).

## Tips

- **Page Bundles**: For the best organization, use [page bundles](/writing/pages/#asset-colocation) — place `index.md` and its assets in a directory together.
- **Image formats**: Include common web image formats: `["jpg", "jpeg", "png", "gif", "svg", "webp"]`.
- **Security**: Use `disallow_paths` to prevent publishing source files or drafts.
- **Keep it lean**: Only allow extensions you actually need. This prevents accidentally publishing large source files.

## See Also

- [Image Processing](/features/image-processing/) — Automatic image resizing
- [Pages — Asset Colocation](/writing/pages/#asset-colocation) — Page bundles
- [Sections — Asset Colocation](/writing/sections/#asset-colocation) — Section assets
- [Configuration](/start/config/) — Full configuration reference

---

Title: Deployment
URL: https://hwaro.hahwul.com/features/deployment/
Source: content/features/deployment.md

Hwaro includes a built-in `hwaro deploy` command that syncs your built site to configured targets — local directories, cloud storage, or any tool via custom commands.

```toml
[deployment]
source_dir = "public"

[[deployment.targets]]
name = "prod"
url = "file:///var/www/mysite"

[[deployment.targets]]
name = "s3"
url = "s3://my-bucket"
# No command needed — auto-generated from URL scheme (requires aws CLI)

[[deployment.targets]]
name = "gcs"
url = "gs://my-bucket"
# Auto-generated (requires gsutil)
```

**Supported URL schemes:**

| Scheme | Auto Command | Requires |
|--------|-------------|----------|
| `file://` | Local directory sync | — |
| `s3://` | `aws s3 sync` | AWS CLI |
| `gs://` | `gsutil -m rsync` | Google Cloud SDK |
| `az://` | `az storage blob sync` | Azure CLI |

You can always override with a custom `command` field for full control.

```bash
hwaro deploy              # Deploy to default target
hwaro deploy --target s3  # Deploy to specific target
hwaro deploy --dry-run    # Preview changes
```

For full configuration (targets, matchers, options) and platform-specific guides, see the [Deploy](/deploy/) section.

---

Title: Environment-Specific Configuration
URL: https://hwaro.hahwul.com/features/env-config/
Source: content/features/env-config.md

Hwaro supports environment-specific config overrides, allowing different settings for development, staging, and production.

## How It Works

1. Base config is loaded from `config.toml`
2. If an environment is specified, `config.<env>.toml` is loaded and merged on top
3. Nested sections (tables) are deep-merged; top-level and leaf values are replaced

## Setting the Environment

Use the `--env` flag or the `HWARO_ENV` environment variable:

```bash
# Via CLI flag
hwaro build --env production
hwaro serve --env development

# Via environment variable
HWARO_ENV=staging hwaro build

# CLI flag takes precedence over HWARO_ENV
```

## File Structure

```
mysite/
├── config.toml                  # Base configuration (always loaded)
├── config.development.toml      # Development overrides
├── config.staging.toml          # Staging overrides
└── config.production.toml       # Production overrides
```

## Example

**config.toml** (base):

```toml
title = "My Blog"
base_url = "http://localhost:3000"

[sitemap]
enabled = true
changefreq = "weekly"

[search]
enabled = true
```

**config.production.toml** (override):

```toml
base_url = "https://myblog.com"

[sitemap]
changefreq = "daily"
```

Running `hwaro build --env production` produces a config equivalent to:

```toml
title = "My Blog"                     # from base
base_url = "https://myblog.com"       # overridden by production

[sitemap]
enabled = true                        # from base (deep-merged)
changefreq = "daily"                  # overridden by production

[search]
enabled = true                        # from base (untouched)
```

## Deep Merge Behavior

Sub-tables are merged recursively, not replaced entirely. This means you only need to specify the values you want to change:

| Base | Override | Result |
|------|----------|--------|
| `[sitemap] enabled = true, changefreq = "weekly"` | `[sitemap] changefreq = "daily"` | `[sitemap] enabled = true, changefreq = "daily"` |

Top-level scalars and arrays are replaced, not merged:

| Base | Override | Result |
|------|----------|--------|
| `title = "Base"` | `title = "Prod"` | `title = "Prod"` |

## Environment Variables

Environment-specific config files also support [environment variable substitution](/features/env-variables/):

```toml
# config.production.toml
base_url = "${PRODUCTION_URL}"

[og]
fb_app_id = "${FB_APP_ID}"
```

## Use Cases

### Different base URLs per environment

```toml
# config.development.toml
base_url = "http://localhost:3000"

# config.staging.toml
base_url = "https://staging.myblog.com"

# config.production.toml
base_url = "https://myblog.com"
```

### Enable features only in production

```toml
# config.production.toml
[search]
enabled = true

[feeds]
enabled = true
```

### Different analytics per environment

```toml
# config.staging.toml
[og]
fb_app_id = "staging-app-id"

# config.production.toml
[og]
fb_app_id = "prod-app-id"
```

## See Also

- [Configuration](/start/config/) — Full config reference
- [Environment Variables](/features/env-variables/) — Env var substitution in config and templates
- [CLI](/start/cli/) — Command-line options

---

Title: Environment Variables
URL: https://hwaro.hahwul.com/features/env-variables/
Source: content/features/env-variables.md

Hwaro supports environment variable substitution in both `config.toml` and templates, enabling dynamic configuration for CI/CD pipelines, secret management, and per-developer settings.

## Config Substitution

Environment variables in `config.toml` are resolved before TOML parsing.

### Syntax

| Pattern | Description |
|---------|-------------|
| `${VAR}` | Replace with the value of `VAR` |
| `$VAR` | Same (bare form) |
| `${VAR:-default}` | Use `default` if `VAR` is unset or empty |

### Examples

```toml
# Dynamic base URL for CI/CD
base_url = "${SITE_URL:-https://localhost:1313}"

# Bare form
title = "$SITE_TITLE"

# Default values
description = "${SITE_DESC:-My awesome site}"

[og]
fb_app_id = "${FB_APP_ID:-}"
```

Missing variables without a default value are left unchanged and produce a build-time warning:

```
WARN: Environment variable 'SITE_URL' is not set (referenced in config.toml)
```

## Template Function

Use the `env()` function to read environment variables inside templates.

```jinja
{{ env("ANALYTICS_ID") }}
{{ env("API_KEY", default="none") }}
```

| Parameter | Type | Description |
|-----------|------|-------------|
| name | String | Variable name |
| default | String? | Fallback if unset (optional) |

If the variable is not set and no default is provided, an empty string is returned and a warning is logged.

### Examples

**Conditional analytics snippet:**

```jinja
{% if env("GA_ID") %}
<script async src="https://www.googletagmanager.com/gtag/js?id={{ env("GA_ID") }}"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', '{{ env("GA_ID") }}');
</script>
{% endif %}
```

**API endpoint with fallback:**

```jinja
<script>
  const API_URL = "{{ env("API_URL", default="https://api.example.com") }}";
</script>
```

## Use Cases

### CI/CD Pipelines

Set the base URL per deployment environment:

```bash
SITE_URL=https://staging.example.com hwaro build
SITE_URL=https://example.com hwaro build
```

### Secret Management

Keep API keys and tracking IDs out of version control:

```toml
# config.toml
[og]
fb_app_id = "${FB_APP_ID}"
```

```bash
export FB_APP_ID="123456789"
hwaro build
```

### Per-Developer Settings

Each developer can override values locally via their shell environment without modifying `config.toml`:

```bash
export SITE_URL="http://localhost:1313"
hwaro serve
```

## See Also

- [Configuration](/start/config/) — Full config reference
- [Functions](/templates/functions/) — All template functions

---

Title: Image Processing
URL: https://hwaro.hahwul.com/features/image-processing/
Source: content/features/image-processing.md

Hwaro can automatically generate resized image variants during build. This is useful for responsive images, thumbnails, and performance optimization. No external tools required — image processing is built into the binary using [stb](https://github.com/nothings/stb) libraries.

## Supported Formats

| Format | Read | Write |
|--------|------|-------|
| JPEG (.jpg, .jpeg) | Yes | Yes |
| PNG (.png) | Yes | Yes |
| BMP (.bmp) | Yes | Yes |

## Configuration

Enable image processing in `config.toml`:

```toml
[image_processing]
enabled = true
widths = [320, 640, 1024, 1280]
quality = 85
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Enable image resizing |
| widths | array | [] | Target widths to generate (in pixels) |
| quality | int | 85 | JPEG output quality (1-100) |

### LQIP (Low-Quality Image Placeholders)

Enable LQIP to generate tiny base64-encoded placeholder images and extract dominant colors at build time. This eliminates CLS (Cumulative Layout Shift) and provides instant visual feedback while full images load.

```toml
[image_processing.lqip]
enabled = true
width = 32
quality = 20
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Enable LQIP generation |
| width | int | 32 | Placeholder image width in pixels (8-128) |
| quality | int | 20 | JPEG quality for placeholder (1-100, lower = smaller) |

A width of 32 and quality of 20 typically produces ~400-800 byte base64 strings per image — small enough to inline directly in HTML.

## How It Works

1. During build, Hwaro scans images in three locations:
   - **Page bundle assets** (images colocated with `index.md`)
   - **Content files** (images published via `[content.files]` config)
   - **Static files** (images in the `static/` directory)
2. For each image, resized variants are generated for every configured width
3. Aspect ratio is always preserved
4. If the target width is larger than the source, the original is copied as-is (no upscaling)
5. Each source image is decoded only once, then resized to all widths (efficient)

## Output Naming

Resized images follow the naming convention `{name}_{width}w.{ext}`. For example, with `static/hwaro.png`:

```
static/hwaro.png
  -> public/hwaro_320w.png
  -> public/hwaro_640w.png
  -> public/hwaro_1024w.png
  -> public/hwaro_1280w.png
```

## Using in Templates

Use the `resize_image()` function to get the URL of a resized variant:

```jinja
{% set img = resize_image(path="/hwaro.png", width=640) %}
<img src="{{ img.url }}" width="{{ img.width }}">
```

For responsive images with `srcset`:

```jinja
{% set sm = resize_image(path="/hwaro.png", width=320) %}
{% set md = resize_image(path="/hwaro.png", width=640) %}
{% set lg = resize_image(path="/hwaro.png", width=1024) %}
<img
  src="{{ md.url }}"
  srcset="{{ sm.url }} 320w, {{ md.url }} 640w, {{ lg.url }} 1024w"
  sizes="(max-width: 640px) 320px, (max-width: 1024px) 640px, 1024px"
  alt="Hwaro logo"
>
```

The function selects the closest available width. If you request `width=500` and the configured widths are `[320, 640, 1024]`, it returns the 640px variant (smallest width >= requested). If no variant is large enough, it falls back to the largest available.

### Using LQIP Placeholders

When LQIP is enabled, `resize_image()` returns two additional properties: `lqip` (a base64 data URI) and `dominant_color` (a hex color string). Use them for blur-up effects or solid color placeholders:

**Blur-up effect:**

```jinja
{% set img = resize_image(path="/images/hero.jpg", width=1024) %}
<img
  src="{{ img.url }}"
  style="background-image: url({{ img.lqip }}); background-size: cover;"
  loading="lazy"
  alt="Hero image"
>
```

**Dominant color placeholder:**

```jinja
{% set img = resize_image(path="/images/hero.jpg", width=1024) %}
<img
  src="{{ img.url }}"
  style="background-color: {{ img.dominant_color }}"
  loading="lazy"
  alt="Hero image"
>
```

**Combined approach (color first, then blur, then full image):**

```jinja
{% set img = resize_image(path="/images/hero.jpg", width=1024) %}
<div style="background-color: {{ img.dominant_color }}">
  <img
    src="{{ img.url }}"
    style="background-image: url({{ img.lqip }}); background-size: cover;"
    loading="lazy"
    alt="Hero image"
  >
</div>
```

When LQIP is disabled, `lqip` and `dominant_color` return empty strings, so templates work without changes.

## Live Demo

### Resize Demo

This docs site has image processing enabled with `widths = [128, 256, 512]` and LQIP enabled. The images below are automatically generated resized variants of `static/hwaro.png`:

**Original** (`hwaro.png`):

<img src="/hwaro.png" alt="Hwaro logo - original" style="max-width:256px">

**128px** (`hwaro_128w.png`):

<img src="/hwaro_128w.png" alt="Hwaro logo - 128px wide">

**256px** (`hwaro_256w.png`):

<img src="/hwaro_256w.png" alt="Hwaro logo - 256px wide">

**512px** (`hwaro_512w.png`):

<img src="/hwaro_512w.png" alt="Hwaro logo - 512px wide">

These files are generated at build time — no runtime resizing or external services needed. In your templates, use `resize_image()` to reference them:

```jinja
{% set img = resize_image(path="/hwaro.png", width=256) %}
<img src="{{ img.url }}">
{# renders as: <img src="/hwaro_256w.png"> #}
```

### LQIP Demo

The `resize_image()` function also provides LQIP data. Here is the live output for `hwaro.png`:

{{ lqip_demo(src="/hwaro.png") }}

## Performance

- **Single decode**: Each source image is decoded once and resized to all target widths in memory
- **Parallel processing**: Multiple images are processed concurrently using a worker pool
- **No upscaling**: Images smaller than the target width are simply copied
- **Efficient LQIP**: LQIP thumbnails are generated from the smallest resize variant (not the full-resolution original), and dominant color is computed from the thumbnail

## Quick Example

Suppose your site has `static/hwaro.png` (the Hwaro logo) and you want to display it as a responsive image:

**config.toml:**

```toml
[image_processing]
enabled = true
widths = [128, 256, 512]
quality = 90

[image_processing.lqip]
enabled = true
width = 32
quality = 20
```

**Template:**

```jinja
{% set logo_sm = resize_image(path="/hwaro.png", width=128) %}
{% set logo_md = resize_image(path="/hwaro.png", width=256) %}
{% set logo_lg = resize_image(path="/hwaro.png", width=512) %}
<img
  src="{{ logo_md.url }}"
  srcset="{{ logo_sm.url }} 128w, {{ logo_md.url }} 256w, {{ logo_lg.url }} 512w"
  sizes="(max-width: 480px) 128px, (max-width: 768px) 256px, 512px"
  style="background-color: {{ logo_md.dominant_color }}"
  loading="lazy"
  alt="Hwaro"
>
```

**Build output:**

```
public/
  hwaro.png           (original, copied by static files)
  hwaro_128w.png      (128px wide)
  hwaro_256w.png      (256px wide)
  hwaro_512w.png      (512px wide)
```

## Blog Post Images

For blog posts with a hero image in front matter:

```toml
[image_processing]
enabled = true
widths = [320, 640, 1024]
quality = 85

[image_processing.lqip]
enabled = true

[content.files]
allow_extensions = ["jpg", "jpeg", "png"]
```

```jinja
{% if page.image %}
  {% set hero = resize_image(path=page.image, width=1024) %}
  {% set thumb = resize_image(path=page.image, width=320) %}
  <picture>
    <source media="(min-width: 768px)" srcset="{{ hero.url }}">
    <img
      src="{{ thumb.url }}"
      style="background-color: {{ thumb.dominant_color }}"
      loading="lazy"
      alt="{{ page.title }}"
    >
  </picture>
{% endif %}
```

## See Also

- [Content Files](/features/content-files/) — Publishing non-Markdown files from content/
- [Auto OG Images](/features/og-images/) — Auto-generated Open Graph preview images
- [Functions](/templates/functions/) — Template function reference

---

Title: Incremental Build
URL: https://hwaro.hahwul.com/features/incremental-build/
Source: content/features/incremental-build.md

Incremental build tracks file checksums and dependency changes to skip unchanged pages, significantly reducing rebuild times for large sites.

```bash
hwaro build --cache
```

## When to Use

Incremental builds are most effective when:

- Your site has many pages but you typically change only a few at a time
- You want faster edit-build-preview cycles
- You're working on content rather than templates or config

## Usage

### Enable caching

```bash
hwaro build --cache
```

On the first run, Hwaro builds every page and saves checksums to `.hwaro_cache.json`. On subsequent builds, only changed files are re-processed.

### Force a full rebuild

```bash
hwaro build --cache --full
```

The `--full` flag clears the cache and rebuilds every page from scratch. The new cache is saved afterward, so the next build without `--full` will be incremental again.

## How It Works

### Change detection

Each cached entry tracks:

- **File modification time (mtime)** — fast first check
- **Content checksum (MD5)** — verifies actual change when mtime differs, catching false positives from file touches

When mtime hasn't changed, the file is considered unchanged without reading its content. When mtime differs, Hwaro computes and compares the content hash to confirm the change is real.

### Dependency invalidation

Beyond per-file checksums, Hwaro tracks global dependencies:

- **Template checksum** — a combined hash of all template files
- **Config checksum** — a hash of `config.toml`

If either changes between builds, **all cache entries are invalidated** and every page is rebuilt. This ensures that template or config changes are always reflected across the entire site.

```
Build N:   templates hash = abc123, config hash = def456
Build N+1: templates hash = abc123, config hash = def456  → incremental (only changed content rebuilt)
Build N+2: templates hash = xyz789, config hash = def456  → full invalidation (template changed)
```

### What gets skipped

When a page is unchanged and its dependencies haven't changed:

- Content parsing is still performed (to build navigation, taxonomies, etc.)
- **Rendering and writing are skipped** — the existing output file is reused
- SEO files (sitemap, feeds, etc.) are always regenerated

### Serve mode

The development server (`hwaro serve`) uses a more targeted incremental strategy:

| Change Type | Strategy |
|-------------|----------|
| Content files only | Re-parse and re-render only affected pages + neighbors |
| Template files only | Re-render all pages with existing content (skip parsing) |
| Config file | Full rebuild |
| Static files only | Copy only changed files |

## Cache File

The cache is stored in `.hwaro_cache.json` at the project root. This file contains:

- **Metadata** — template and config checksums from the last build
- **Entries** — per-file records with path, mtime, content hash, and output path

Add `.hwaro_cache.json` to your `.gitignore`:

```gitignore
.hwaro_cache.json
```

## Flag Reference

| Flag | Description |
|------|-------------|
| `--cache` | Enable incremental build caching |
| `--full` | Force a complete rebuild (clears and repopulates the cache) |

## Examples

```bash
# First build — creates cache
hwaro build --cache

# Edit a few files, then rebuild — only changed pages are re-rendered
hwaro build --cache

# Something seems off — force a clean rebuild
hwaro build --cache --full

# Combine with other flags
hwaro build --cache --minify --parallel
```

## See Also

- [CLI Reference](/start/cli/) — Full list of build flags
- [Streaming Build](/features/streaming-build/) — Reduce memory usage for large sites
- [Build Hooks](/features/build-hooks/) — Run custom commands before/after builds

---

Title: LLMs.txt
URL: https://hwaro.hahwul.com/features/llms-txt/
Source: content/features/llms-txt.md

Hwaro can generate `llms.txt` and `llms-full.txt` files that provide instructions and content for AI/LLM crawlers. This is part of the emerging [llms.txt standard](https://llmstxt.org/) for making websites more accessible to large language models.

## Configuration

Enable in `config.toml`:

```toml
[llms]
enabled = true
filename = "llms.txt"
instructions = "This is my site. Content is provided under the MIT license."
full_enabled = true
full_filename = "llms-full.txt"
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Generate `llms.txt` |
| filename | string | "llms.txt" | Output filename |
| instructions | string | "" | Instructions text for LLM crawlers |
| full_enabled | bool | false | Generate full content version |
| full_filename | string | "llms-full.txt" | Filename for the full version |

## Generated Files

### llms.txt

The basic `llms.txt` file contains only the instructions you define in the configuration. This is a lightweight file that tells AI crawlers about your site's policies.

**Example output (`llms.txt`):**

```
This is my site. Content is provided under the MIT license.
```

### llms-full.txt

The full version includes all rendered content from your site, making it easy for LLMs to ingest your entire site in a single file. Each page is separated by `---` delimiters.

**Example output (`llms-full.txt`):**

```
# My Site
A great site about programming

Base URL: https://example.com

This is my site. Content is provided under the MIT license.

---

Title: About
URL: https://example.com/about/
Source: content/about.md

About page content goes here...

---

Title: Getting Started
URL: https://example.com/docs/getting-started/
Source: content/docs/getting-started.md

Getting started guide content...
```

## Full Document Structure

The `llms-full.txt` file is structured as follows:

1. **Site header** — Site title as an H1 heading
2. **Site description** — From `config.toml`
3. **Base URL** — The site's base URL
4. **Instructions** — The instructions text from configuration
5. **Page entries** — Each page separated by `---`, containing:
   - `Title` — Page title
   - `URL` — Absolute URL to the page
   - `Source` — Source file path relative to project root
   - `Language` — Language code (only for multilingual sites)
   - Raw content of the page

### Page Selection

Only pages that meet these criteria are included in `llms-full.txt`:

- The page has `render = true` (default)
- The page has non-empty raw content
- Pages are sorted by URL for consistent output

Draft pages are excluded from production builds (unless `--drafts` is used).

## Multilingual Support

For multilingual sites, each page entry includes a `Language` field indicating the content language:

```
---

Title: 소개
URL: https://example.com/ko/about/
Source: content/about.ko.md
Language: ko

한국어 콘텐츠...
```

## Use Cases

### Documentation Sites

Provide your full documentation to LLMs for better AI-assisted answers:

```toml
[llms]
enabled = true
instructions = "This is the official documentation for MyProject. All content is licensed under Apache 2.0. Please cite the source URL when referencing this content."
full_enabled = true
```

### Blog Sites

Share your blog content with clear usage guidelines:

```toml
[llms]
enabled = true
instructions = "This is a personal blog. Content is copyrighted. You may summarize but not reproduce full articles."
full_enabled = false
```

### Restricting LLM Access

Use `llms.txt` to communicate preferences without providing full content:

```toml
[llms]
enabled = true
instructions = "Please do not use this site's content for training purposes. Summarization and citation are permitted."
full_enabled = false
```

## Combining with robots.txt

`llms.txt` works alongside `robots.txt`. While `robots.txt` controls crawler access at the HTTP level, `llms.txt` provides human-readable instructions and context:

```toml
[robots]
enabled = true
rules = [
  { user_agent = "*", allow = ["/"] },
  { user_agent = "GPTBot", disallow = ["/private/"] }
]

[llms]
enabled = true
instructions = "Public content may be used for AI responses with attribution."
full_enabled = true
```

## Template Integration

You can link to the `llms.txt` file from your HTML templates:

```jinja
<head>
  <link rel="alternate" type="text/plain" href="{{ base_url }}/llms.txt" title="LLM Instructions">
</head>
```

## See Also

- [SEO](/features/seo/) — Sitemap, RSS feeds, robots.txt, and social tags
- [Configuration](/start/config/) — Full configuration reference
- [Search](/features/search/) — Search index generation

---

Title: Markdown Extensions
URL: https://hwaro.hahwul.com/features/markdown-extensions/
Source: content/features/markdown-extensions.md

Hwaro supports optional markdown extensions beyond standard CommonMark. Each extension is disabled by default and can be enabled in `config.toml`.

## Configuration

```toml
[markdown]
task_lists = true
definition_lists = true
footnotes = true
math = true
math_engine = "katex"
mermaid = true
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| task_lists | bool | true | Checkbox lists (`- [ ]` / `- [x]`) |
| definition_lists | bool | true | Definition lists (`Term\n: Definition`) |
| footnotes | bool | true | Footnotes (`[^1]`) |
| math | bool | false | Math expressions (`$...$` and `$$...$$`) |
| math_engine | string | "katex" | Math rendering engine (`"katex"` or `"mathjax"`) |
| mermaid | bool | false | Mermaid diagram blocks |

## Task Lists

Render checkboxes in lists.

### Syntax

```markdown
- [x] Completed task
- [ ] Incomplete task
- [X] Also completed (case-insensitive)
```

### Output

```html
<ul>
  <li><input type="checkbox" checked disabled> Completed task</li>
  <li><input type="checkbox" disabled> Incomplete task</li>
  <li><input type="checkbox" checked disabled> Also completed</li>
</ul>
```

## Definition Lists

Render terms with their definitions using `<dl>`, `<dt>`, and `<dd>` elements.

### Syntax

```markdown
Crystal
: A compiled language with Ruby-like syntax

Go
: A statically typed, compiled language by Google
```

### Output

```html
<dl>
  <dt>Crystal</dt>
  <dd>A compiled language with Ruby-like syntax</dd>
  <dt>Go</dt>
  <dd>A statically typed, compiled language by Google</dd>
</dl>
```

## Footnotes

Add footnote references and definitions.

### Syntax

```markdown
This is a statement[^1] with multiple references[^note].

[^1]: First footnote content.
[^note]: Named footnote content.
```

### Output

References become superscript links:

```html
<p>This is a statement<sup class="footnote-ref"><a href="#fn-1" id="fnref-1">[1]</a></sup>
with multiple references<sup class="footnote-ref"><a href="#fn-note" id="fnref-note">[2]</a></sup>.</p>
```

A footnotes section is appended at the end:

```html
<section class="footnotes">
  <hr>
  <ol>
    <li id="fn-1"><p>First footnote content. <a href="#fnref-1" class="footnote-backref">↩</a></p></li>
    <li id="fn-note"><p>Named footnote content. <a href="#fnref-note" class="footnote-backref">↩</a></p></li>
  </ol>
</section>
```

## Math

Render mathematical expressions. Requires a client-side math library (KaTeX or MathJax).

### Syntax

Inline math with single `$`:

```markdown
The equation $E = mc^2$ is well known.
```

Display math with double `$$`:

```markdown
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
```

### Output

```html
<p>The equation <span class="math math-inline">\(E = mc^2\)</span> is well known.</p>

<div class="math math-display">\[\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}\]</div>
```

### Client-Side Setup

#### KaTeX

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css">
<script src="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/katex/dist/contrib/auto-render.min.js"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    renderMathInElement(document.body);
  });
</script>
```

#### MathJax

```html
<script>
  MathJax = { tex: { inlineMath: [['\\(', '\\)']], displayMath: [['\\[', '\\]']] } };
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
```

## Mermaid Diagrams

Render Mermaid diagram blocks as `<div class="mermaid">` elements.

### Syntax

````markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[OK]
    B -->|No| D[Cancel]
```
````

### Output

```html
<div class="mermaid">
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[OK]
    B -->|No| D[Cancel]
</div>
```

### Client-Side Setup

```html
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({ startOnLoad: true });</script>
```

## See Also

- [Configuration](/start/config/) — Markdown configuration options
- [Syntax Highlighting](/features/syntax-highlighting/) — Code block highlighting

---

Title: Multilingual
URL: https://hwaro.hahwul.com/features/multilingual/
Source: content/features/multilingual.md

Hwaro supports building multilingual sites with automatic translation linking, language-specific URLs, and hreflang tags for SEO.

## Configuration

Enable multilingual support in `config.toml`:

```toml
default_language = "en"

[languages.en]
language_name = "English"
weight = 1

[languages.ko]
language_name = "한국어"
weight = 2
generate_feed = true
build_search_index = true
taxonomies = ["tags", "categories"]

[languages.ja]
language_name = "日本語"
weight = 3
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| default_language | string | "en" | Default language code |
| language_name | string | — | Human-readable language name |
| weight | int | 0 | Sort order (lower = first) |
| generate_feed | bool | true | Generate RSS/Atom feed for this language |
| build_search_index | bool | false | Include in search index |
| taxonomies | array | [] | Taxonomies for this language |

## Content Structure

Create translations by adding a language suffix to filenames:

```
content/
├── posts/
│   ├── hello.md         # Default language (en)
│   ├── hello.ko.md      # Korean translation
│   └── hello.ja.md      # Japanese translation
├── about.md             # Default language (en)
├── about.ko.md          # Korean translation
└── index.md             # Homepage (default)
```

### URL Mapping

| File | URL |
|------|-----|
| content/about.md | /about/ |
| content/about.ko.md | /ko/about/ |
| content/about.ja.md | /ja/about/ |
| content/posts/hello.md | /posts/hello/ |
| content/posts/hello.ko.md | /ko/posts/hello/ |

The default language pages are served at the root path. Non-default language pages are prefixed with the language code.

### Section Translations

Section index files also support language suffixes:

```
content/
└── blog/
    ├── _index.md         # /blog/
    ├── _index.ko.md      # /ko/blog/
    └── post.md
```

## Translation Linking

Hwaro automatically links translated pages based on their filenames. Pages with the same base name (without the language suffix) are considered translations of each other.

For example, `hello.md`, `hello.ko.md`, and `hello.ja.md` are all linked as translations.

### Template Variables

Access translation data in templates:

```jinja
{% if page.translations %}
<nav class="language-switcher">
  {% for t in page.translations %}
    {% if t.is_current %}
      <span class="active">{{ t.code | upper }}</span>
    {% else %}
      <a href="{{ t.url }}">{{ t.code | upper }}</a>
    {% endif %}
  {% endfor %}
</nav>
{% endif %}
```

### Translation Properties

| Property | Type | Description |
|----------|------|-------------|
| code | String | Language code (e.g., "en", "ko") |
| url | String | URL of the translated page |
| title | String | Title of the translated page |
| is_current | Bool | Whether this is the current page's language |
| is_default | Bool | Whether this is the default language |

## SEO Tags

### Canonical URLs

Hwaro generates canonical link tags for multilingual pages:

```jinja
<head>
  {{ canonical_tag | safe }}
</head>
```

Output:

```html
<link rel="canonical" href="https://example.com/about/">
```

### Hreflang Tags

Alternate language link tags are generated automatically for translated pages:

```jinja
<head>
  {{ hreflang_tags | safe }}
</head>
```

Output:

```html
<link rel="alternate" hreflang="en" href="https://example.com/about/">
<link rel="alternate" hreflang="ko" href="https://example.com/ko/about/">
<link rel="alternate" hreflang="ja" href="https://example.com/ja/about/">
```

### Combined SEO Tags

Include both canonical and hreflang tags together:

```jinja
<head>
  {{ canonical_tag | safe }}
  {{ hreflang_tags | safe }}
  {{ og_all_tags | safe }}
</head>
```

## Page Language

Access the current page's language in templates:

```jinja
<html lang="{{ page.language }}">
```

```jinja
{% if page.language == "ko" %}
<p>한국어 콘텐츠</p>
{% endif %}
```

## Scaffolding with Multilingual

Create a new site with multilingual support:

```bash
hwaro init mysite --include-multilingual en,ko,ja
```

This generates the configuration and sample content files for each specified language.

## Template Examples

### Language Switcher (Dropdown)

```jinja
{% if page.translations %}
<div class="lang-dropdown">
  <button>{{ page.language | upper }} ▾</button>
  <ul>
    {% for t in page.translations %}
    <li>
      <a href="{{ t.url }}"{% if t.is_current %} class="current"{% endif %}>
        {{ t.code | upper }}
      </a>
    </li>
    {% endfor %}
  </ul>
</div>
{% endif %}
```

### Language-Specific Navigation

```jinja
<nav>
  {% if page.language == "ko" %}
    <a href="/ko/">홈</a>
    <a href="/ko/blog/">블로그</a>
  {% elif page.language == "ja" %}
    <a href="/ja/">ホーム</a>
    <a href="/ja/blog/">ブログ</a>
  {% else %}
    <a href="/">Home</a>
    <a href="/blog/">Blog</a>
  {% endif %}
</nav>
```

### Base Template with i18n

```jinja
<!DOCTYPE html>
<html lang="{{ page.language | default(value='en') }}">
<head>
  <meta charset="utf-8">
  <title>{{ page.title }} - {{ site.title }}</title>
  {{ canonical_tag | safe }}
  {{ hreflang_tags | safe }}
  {{ og_all_tags | safe }}
</head>
<body>
  {% if page.translations %}
  <nav class="i18n">
    {% for t in page.translations %}
      {% if t.is_current %}
        <strong>{{ t.code }}</strong>
      {% else %}
        <a href="{{ t.url }}">{{ t.code }}</a>
      {% endif %}
    {% endfor %}
  </nav>
  {% endif %}

  <main>
    {% block content %}{% endblock %}
  </main>
</body>
</html>
```

## i18n Translation Files

Hwaro supports translation files for UI strings (navigation labels, button text, etc.) using TOML files in the `i18n/` directory.

### File Structure

Create one TOML file per language:

```
i18n/
├── en.toml
├── ko.toml
└── ja.toml
```

### Translation File Format

```toml
# i18n/en.toml
[nav]
home = "Home"
blog = "Blog"
about = "About"

[common]
read_more = "Read more"
back = "Back"
```

```toml
# i18n/ko.toml
[nav]
home = "홈"
blog = "블로그"
about = "소개"

[common]
read_more = "더 읽기"
back = "뒤로"
```

Nested TOML sections are flattened to dot-separated keys (e.g., `nav.home`, `common.read_more`).

### Template Usage

Use the `t` filter to translate keys:

```jinja
<nav>
  <a href="/">{{ "nav.home" | t }}</a>
  <a href="/blog/">{{ "nav.blog" | t }}</a>
  <a href="/about/">{{ "nav.about" | t }}</a>
</nav>

<a href="{{ page.url }}">{{ "common.read_more" | t }}</a>
```

### Fallback Behavior

1. Look up the key in the current page's language
2. If not found, fall back to the default language (`default_language`)
3. If still not found, return the key itself (e.g., `"nav.home"`)

### Pluralization

Use the `pluralize` filter for count-dependent strings:

```jinja
{{ post_count }} {{ post_count | pluralize(singular="post", plural="posts") }}
```

## Per-Language Feeds

When the site is multilingual, Hwaro automatically generates separate RSS/Atom feeds for each language:

| Language | Feed Path | Contents |
|----------|-----------|----------|
| Default (e.g., `en`) | `/rss.xml` | Default language pages only (configurable) |
| Non-default (e.g., `ko`) | `/ko/rss.xml` | Only Korean pages |
| Non-default (e.g., `ja`) | `/ja/rss.xml` | Only Japanese pages |

By default, the main site feed (`/rss.xml` or `/atom.xml`) includes **only default language pages**. You can change this behavior with the `default_language_only` option. Each non-default language with `generate_feed = true` gets its own feed under its language prefix regardless of this setting.

### Configuration

#### Main Feed Language Control

```toml
[feeds]
enabled = true
default_language_only = true   # true (default): main feed = default language only
                               # false: main feed includes all languages
```

#### Per-Language Feed Control

```toml
[languages.ko]
language_name = "한국어"
generate_feed = true    # Generates /ko/rss.xml (default: true)

[languages.ja]
language_name = "日本語"
generate_feed = false   # No /ja/rss.xml will be generated
```

Language feeds share the same `sections`, `limit`, `truncate`, and `full_content` settings from the global `[feeds]` config:

```toml
[feeds]
enabled = true
type = "rss"           # or "atom"
limit = 20
truncate = 0
full_content = true    # false = description/summary only
sections = []          # empty = all sections
default_language_only = true
```

### Feed Details

- **RSS feeds** include a `<language>` tag (e.g., `<language>ko</language>`)
- **Atom feeds** include an `xml:lang` attribute (e.g., `<feed xmlns="..." xml:lang="ko">`)
- Feed title includes the language name: `"My Site (한국어)"`
- Self-referencing links point to the correct language path (e.g., `https://example.com/ko/rss.xml`)
- Draft pages and section index pages are excluded
- Language feeds are generated independently of the main feed's `enabled` setting

### Template Links

Add language-specific feed links in your templates:

```jinja
{# Main feed (default language) #}
<link rel="alternate" type="application/rss+xml"
      href="{{ base_url }}/rss.xml"
      title="{{ site.title }}">

{# Language-specific feed #}
{% if page.language and page.language != "en" %}
<link rel="alternate" type="application/rss+xml"
      href="{{ base_url }}/{{ page.language }}/rss.xml"
      title="{{ site.title }} ({{ page.language }})">
{% endif %}
```

## See Also

- [Configuration](/start/config/) — Full configuration reference
- [SEO](/features/seo/) — SEO features including feeds, canonical and hreflang
- [Data Model](/templates/data-model/) — Translation link properties

---

Title: Auto OG Images
URL: https://hwaro.hahwul.com/features/og-images/
Source: content/features/og-images.md

Hwaro can automatically generate Open Graph (OG) preview images for pages that don't have a custom image set. These images are used by social media platforms when your content is shared.

![](/og-images/features-og-images.png)
*Example: This is the og image of this page.*

## How It Works

1. During build, Hwaro checks each page for a custom `image` in front matter
2. Pages without an image get an auto-generated image (1200x630)
3. The generated image path is set as `page.image`, so `og:image` meta tags pick it up automatically
4. SVG output requires no external dependencies; PNG output uses built-in rendering via system fonts

## Configuration

```toml
[og.auto_image]
enabled = true
background = "#1a1a2e"
text_color = "#ffffff"
accent_color = "#e94560"
font_size = 48
logo = "static/logo.png"
logo_position = "bottom-left"
output_dir = "og-images"
show_title = true
style = "default"
pattern_opacity = 0.15
pattern_scale = 1.0
background_image = "static/og-bg.jpg"
overlay_opacity = 0.5
format = "svg"
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | `false` | Enable auto OG image generation |
| background | string | `"#1a1a2e"` | Background color (hex) |
| text_color | string | `"#ffffff"` | Title and description text color |
| accent_color | string | `"#e94560"` | Accent color for bars and site name |
| font_size | int | `48` | Title font size in pixels |
| logo | string | — | Logo file path (e.g., `static/logo.png`). Embedded as base64 data URI |
| logo_position | string | `"bottom-left"` | Logo placement: `bottom-left`, `bottom-right`, `top-left`, `top-right` |
| output_dir | string | `"og-images"` | Directory for generated images |
| show_title | bool | `true` | Show site name at the bottom of the image |
| style | string | `"default"` | Style preset for background pattern |
| pattern_opacity | float | `0.15` | Opacity of the style pattern (0.0–1.0) |
| pattern_scale | float | `1.0` | Scale multiplier for the pattern (min 0.1) |
| background_image | string | — | Background image file path. Embedded as base64 data URI |
| overlay_opacity | float | `0.5` | Opacity of the color overlay on background images (0.0–1.0) |
| format | string | `"svg"` | Output format: `"svg"` or `"png"` |

## Style Presets

The `style` option controls the background pattern rendered on the image:

| Style | Description |
|-------|-------------|
| `default` | No pattern (solid background) |
| `dots` | Repeating dot grid |
| `grid` | Repeating line grid |
| `diagonal` | Diagonal stripe pattern |
| `gradient` | Diagonal gradient using the accent color |
| `waves` | Horizontal wave curves |
| `minimal` | Clean layout without accent bars |

### Preview

<div class="og-style-grid">
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-default.svg" alt="default style" loading="lazy" />
    <span class="og-style-label"><code>default</code></span>
    <dialog onclick="if(event.target===this)this.close()">
      <div class="og-style-dialog">
        <button onclick="event.stopPropagation();this.closest('dialog').close()">&times;</button>
        <img src="/images/og-style-examples/style-default.svg" alt="default style" />
        <p><code>default</code> — No pattern (solid background)</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-dots.svg" alt="dots style" loading="lazy" />
    <span class="og-style-label"><code>dots</code></span>
    <dialog onclick="if(event.target===this)this.close()">
      <div class="og-style-dialog">
        <button onclick="event.stopPropagation();this.closest('dialog').close()">&times;</button>
        <img src="/images/og-style-examples/style-dots.svg" alt="dots style" />
        <p><code>dots</code> — Repeating dot grid</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-grid.svg" alt="grid style" loading="lazy" />
    <span class="og-style-label"><code>grid</code></span>
    <dialog onclick="if(event.target===this)this.close()">
      <div class="og-style-dialog">
        <button onclick="event.stopPropagation();this.closest('dialog').close()">&times;</button>
        <img src="/images/og-style-examples/style-grid.svg" alt="grid style" />
        <p><code>grid</code> — Repeating line grid</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-diagonal.svg" alt="diagonal style" loading="lazy" />
    <span class="og-style-label"><code>diagonal</code></span>
    <dialog onclick="if(event.target===this)this.close()">
      <div class="og-style-dialog">
        <button onclick="event.stopPropagation();this.closest('dialog').close()">&times;</button>
        <img src="/images/og-style-examples/style-diagonal.svg" alt="diagonal style" />
        <p><code>diagonal</code> — Diagonal stripe pattern</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-gradient.svg" alt="gradient style" loading="lazy" />
    <span class="og-style-label"><code>gradient</code></span>
    <dialog onclick="if(event.target===this)this.close()">
      <div class="og-style-dialog">
        <button onclick="event.stopPropagation();this.closest('dialog').close()">&times;</button>
        <img src="/images/og-style-examples/style-gradient.svg" alt="gradient style" />
        <p><code>gradient</code> — Diagonal gradient using the accent color</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-waves.svg" alt="waves style" loading="lazy" />
    <span class="og-style-label"><code>waves</code></span>
    <dialog onclick="if(event.target===this)this.close()">
      <div class="og-style-dialog">
        <button onclick="event.stopPropagation();this.closest('dialog').close()">&times;</button>
        <img src="/images/og-style-examples/style-waves.svg" alt="waves style" />
        <p><code>waves</code> — Horizontal wave curves</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-minimal.svg" alt="minimal style" loading="lazy" />
    <span class="og-style-label"><code>minimal</code></span>
    <dialog onclick="if(event.target===this)this.close()">
      <div class="og-style-dialog">
        <button onclick="event.stopPropagation();this.closest('dialog').close()">&times;</button>
        <img src="/images/og-style-examples/style-minimal.svg" alt="minimal style" />
        <p><code>minimal</code> — Clean layout without accent bars</p>
      </div>
    </dialog>
  </div>
</div>

<style>
.og-style-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: 16px;
  margin: 24px 0;
}
.og-style-card {
  cursor: pointer;
  border-radius: 8px;
  overflow: hidden;
  border: 1px solid var(--border, #1e1e24);
  background: var(--bg-card, #111114);
  transition: transform 0.2s, box-shadow 0.2s;
}
.og-style-card:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
  border-color: var(--border-light, #2e2e36);
}
.og-style-card > img {
  width: 100%;
  display: block;
}
.og-style-label {
  display: block;
  padding: 8px 12px;
  font-size: 14px;
}
.og-style-card dialog {
  padding: 0;
  border: none;
  background: transparent;
  max-width: 90vw;
  max-height: 90vh;
}
.og-style-card dialog::backdrop {
  background: rgba(0, 0, 0, 0.7);
}
.og-style-dialog {
  position: relative;
  background: var(--bg-elevated, #101014);
  border: 1px solid var(--border, #1e1e24);
  border-radius: 8px;
  overflow: hidden;
}
.og-style-dialog > img {
  display: block;
  max-width: 90vw;
  max-height: 80vh;
  object-fit: contain;
}
.og-style-dialog > button {
  position: absolute;
  top: 8px;
  right: 8px;
  background: rgba(0, 0, 0, 0.6);
  color: #fff;
  border: none;
  border-radius: 50%;
  width: 32px;
  height: 32px;
  font-size: 20px;
  line-height: 1;
  cursor: pointer;
  z-index: 1;
}
.og-style-dialog > p {
  text-align: center;
  padding: 12px;
  margin: 0;
}
</style>

### Example Configuration

```toml
[og.auto_image]
enabled = true
style = "dots"
pattern_opacity = 0.2
pattern_scale = 1.5
```

## Background Image

You can set a custom background image that gets composited behind the text:

```toml
[og.auto_image]
enabled = true
background_image = "static/og-bg.jpg"
overlay_opacity = 0.6
```

The rendering order is: background color → background image → color overlay → style pattern → accent bars → text/logo.

The `overlay_opacity` controls how much the background color covers the image (0.0 = fully visible image, 1.0 = image completely hidden behind background color).

## PNG Output

By default, images are generated as SVG. Set `format = "png"` to produce PNG files instead:

```toml
[og.auto_image]
enabled = true
format = "png"
```

PNG rendering is built-in using stb_truetype and stb_image_write — no external tools required. System fonts are auto-detected:

- **macOS**: Helvetica, Arial, Geneva
- **Linux**: DejaVu Sans, Liberation Sans, Noto Sans

If no system font is found, Hwaro falls back to SVG output with a warning.

## Generated Image Layout

Each image is 1200x630 with the following structure:

```
┌─────────────────────────────────────┐
│ ████████████ accent bar ████████████│
│                                     │
│   Page Title (auto-wrapped,         │
│   bold, large font)                 │
│                                     │
│   Description text (smaller,        │
│   semi-transparent)                 │
│                                     │
│   [logo] Site Name                  │
│ ████████████ accent bar ████████████│
└─────────────────────────────────────┘
```

When `style = "minimal"`, the top and bottom accent bars are removed. When `show_title = false`, the site name at the bottom is hidden.

## Logo Embedding

When a `logo` file path is configured and the file exists, the logo is read and embedded as a base64 data URI directly in the image. This ensures the logo displays correctly everywhere without external file references.

If the file is not found at build time, the logo falls back to a URL reference (SVG only).

## Behavior

- Pages with a custom `image` in front matter are **skipped** (the custom image takes priority)
- Draft pages are **skipped**
- Long titles are automatically **word-wrapped** across multiple lines
- Logo and background images are loaded once and reused across all pages
- SVG output uses `system-ui` font family; PNG output uses detected system fonts

## Output

Given a page at `/posts/hello-world/`, the generated image will be:

```
public/og-images/posts-hello-world.svg   # or .png if format = "png"
```

And the OG meta tag will automatically include:

```html
<meta property="og:image" content="https://example.com/og-images/posts-hello-world.svg">
```

## Overriding Per Page

To use a custom image for a specific page, set `image` in front matter:

```toml
+++
title = "My Post"
image = "/images/custom-og.png"
+++
```

This page will use the custom image instead of auto-generating one.

## See Also

- [SEO](/features/seo/) — OpenGraph, Twitter Cards, and meta tags
- [Image Processing](/features/image-processing/) — Responsive image resizing
- [Configuration](/start/config/) — Full config reference

---

Title: Pagination
URL: https://hwaro.hahwul.com/features/pagination/
Source: content/features/pagination.md

Split large content lists into multiple pages.

## Configuration

### Site-Level Defaults

Set default pagination behavior in `config.toml`:

```toml
[pagination]
enabled = false
per_page = 10
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Enable pagination globally |
| per_page | int | 10 | Default items per page |

### Section Pagination

Enable in section front matter:

```toml
+++
title = "Blog"
paginate = 10
paginate_path = "page"
+++
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| paginate | int | — | Items per page |
| paginate_path | string | "page" | URL pattern for pages |

### Generated URLs

For a section at `/blog/`:

| Page | URL |
|------|-----|
| 1 | /blog/ |
| 2 | /blog/page/2/ |
| 3 | /blog/page/3/ |

With `paginate_path = "p"`:

| Page | URL |
|------|-----|
| 1 | /blog/ |
| 2 | /blog/p/2/ |
| 3 | /blog/p/3/ |

## Template Variables

### pagination

Pre-rendered pagination HTML:

```jinja
{{ pagination | safe }}
```

### paginator

Pagination object for custom rendering:

| Property | Type | Description |
|----------|------|-------------|
| paginator.paginate_by | Int | Items per page |
| paginator.base_url | String | Base URL for pagination |
| paginator.number_pagers | Int | Total number of pagers (pages) |
| paginator.first | String | URL to first pager |
| paginator.last | String | URL to last pager |
| paginator.previous | String? | URL to previous pager |
| paginator.next | String? | URL to next pager |
| paginator.pages | Array | Array of pages for the current pager |
| paginator.current_index | Int | Current pager index (1-indexed) |
| paginator.total_pages | Int | Total number of pages |

### pagination_obj

Structured pagination object with individual fields for building fully custom pagination markup:

| Property | Type | Description |
|----------|------|-------------|
| pagination_obj.html | String | Pre-rendered pagination HTML (same as `pagination`) |
| pagination_obj.current_page | Int | Current page number (1-indexed) |
| pagination_obj.total_pages | Int | Total number of pages |
| pagination_obj.per_page | Int | Items per page |
| pagination_obj.total_items | Int | Total number of items across all pages |
| pagination_obj.has_previous | Bool | Whether a previous page exists |
| pagination_obj.has_next | Bool | Whether a next page exists |
| pagination_obj.previous_url | String | URL to previous page (empty if none) |
| pagination_obj.next_url | String | URL to next page (empty if none) |
| pagination_obj.first_url | String | URL to first page |
| pagination_obj.last_url | String | URL to last page |

```jinja
{% if pagination_obj.has_previous %}
  <a href="{{ pagination_obj.previous_url }}">← Newer</a>
{% endif %}
<span>Page {{ pagination_obj.current_page }} of {{ pagination_obj.total_pages }}</span>
{% if pagination_obj.has_next %}
  <a href="{{ pagination_obj.next_url }}">Older →</a>
{% endif %}
```

## Template Examples

### Simple Navigation

Use the pre-rendered `pagination` variable:

```jinja
{% extends "base.html" %}

{% block content %}
<h1>{{ section.title }}</h1>

<ul>
{% for p in section.pages %}
  <li><a href="{{ p.url }}">{{ p.title }}</a></li>
{% endfor %}
</ul>

{{ pagination | safe }}
{% endblock %}
```

### Custom Pagination

Build your own pagination UI:

```jinja
{% if paginator.number_pagers > 1 %}
<nav class="pagination">
  {% if paginator.previous %}
  <a href="{{ paginator.previous }}" class="prev">← Previous</a>
  {% endif %}
  
  <span class="current">
    Page {{ paginator.current_index }} of {{ paginator.number_pagers }}
  </span>
  
  {% if paginator.next %}
  <a href="{{ paginator.next }}" class="next">Next →</a>
  {% endif %}
</nav>
{% endif %}
```

### Full Pagination with Page Numbers

```jinja
{% if paginator.number_pagers > 1 %}
<nav class="pagination">
  {# First page #}
  {% if paginator.current_index > 1 %}
  <a href="{{ paginator.first }}">« First</a>
  {% endif %}
  
  {# Previous #}
  {% if paginator.previous %}
  <a href="{{ paginator.previous }}">‹ Prev</a>
  {% endif %}
  
  {# Current #}
  <span class="current">{{ paginator.current_index }} / {{ paginator.number_pagers }}</span>
  
  {# Next #}
  {% if paginator.next %}
  <a href="{{ paginator.next }}">Next ›</a>
  {% endif %}
  
  {# Last page #}
  {% if paginator.current_index < paginator.number_pagers %}
  <a href="{{ paginator.last }}">Last »</a>
  {% endif %}
</nav>
{% endif %}
```

## Ellipsis for Large Page Counts

When there are more than 7 pages, the built-in pagination navigation automatically inserts ellipsis (`...`) to keep the UI compact. A sliding window of 5 page numbers around the current page is shown, with the first and last pages always visible.

For example, on page 5 of 20:

```
« Prev  1 ... 3  4  [5]  6  7 ... 20  Next »
```

## SEO Links

Hwaro generates `<link rel="prev">` and `<link rel="next">` tags for paginated pages. Include them in your `<head>`:

```jinja
<head>
  {{ pagination_seo_links | safe }}
</head>
```

Output:

```html
<link rel="prev" href="https://example.com/blog/page/2/">
<link rel="next" href="https://example.com/blog/page/4/">
```

## Taxonomy Pagination

Taxonomies also support pagination in `config.toml`:

```toml
[[taxonomies]]
name = "tags"
paginate = 20
```

## CSS Example

```css
.pagination {
  display: flex;
  gap: 1rem;
  justify-content: center;
  margin: 2rem 0;
}

.pagination a {
  padding: 0.5rem 1rem;
  border: 1px solid #ddd;
  text-decoration: none;
}

.pagination a:hover {
  background: #f0f0f0;
}

.pagination .current {
  padding: 0.5rem 1rem;
  font-weight: bold;
}
```

## See Also

- [Sections](/writing/sections/) — Section configuration
- [Taxonomies](/writing/taxonomies/) — Taxonomy pagination
- [Data Model](/templates/data-model/) — Section variables

---

Title: PWA
URL: https://hwaro.hahwul.com/features/pwa/
Source: content/features/pwa.md

Hwaro can generate Progressive Web App (PWA) files to enable offline access and installability for your site.

## What Gets Generated

When `[pwa]` is enabled, two files are added to your build output:

- **`manifest.json`** — Web app manifest describing your app (name, icons, theme, display mode)
- **`sw.js`** — Service worker for offline caching with a cache-first strategy

## Configuration

```toml
[pwa]
enabled = true
name = "My Blog"
short_name = "Blog"
theme_color = "#1a1a2e"
background_color = "#ffffff"
display = "standalone"
start_url = "/"
icons = ["static/icon-192.png", "static/icon-512.png"]
offline_page = "/offline.html"
precache_urls = ["/", "/about/", "/css/main.css"]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Enable PWA file generation |
| name | string | site title | Full application name |
| short_name | string | name | Short name for home screen |
| theme_color | string | "#ffffff" | Browser toolbar / status bar color |
| background_color | string | "#ffffff" | Splash screen background color |
| display | string | "standalone" | Display mode |
| start_url | string | "/" | URL when the app launches |
| icons | array | [] | Icon file paths |
| offline_page | string | — | Fallback page when offline |
| precache_urls | array | [] | URLs to cache during service worker install |

## Icon Sizing

Icon sizes are automatically extracted from filenames:

| Filename | Detected Size |
|----------|--------------|
| `icon-192.png` | 192x192 |
| `icon-512x512.png` | 512x512 |
| `logo-180.svg` | 180x180 |

Place icon files in your `static/` directory so they are copied to the build output.

## Template Integration

Add the manifest link and service worker registration to your base template:

```html
<head>
  <link rel="manifest" href="/manifest.json">
  <meta name="theme-color" content="{{ config.pwa.theme_color }}">
</head>
<body>
  ...
  <script>
    if ('serviceWorker' in navigator) {
      navigator.serviceWorker.register('/sw.js');
    }
  </script>
</body>
```

## Caching Strategy

The generated service worker uses:

- **Precache on install** — URLs listed in `precache_urls` plus `start_url` are cached immediately
- **Cache-first for assets** — Subsequent requests serve from cache, falling back to network
- **Network-first for navigation** — Page navigations try the network first, falling back to the offline page
- **Automatic cache versioning** — Old caches are cleaned up on service worker activation

## Offline Page

If `offline_page` is set, create a static HTML page at that path (e.g., `content/offline.md` or `static/offline.html`) that will be shown when the user navigates while offline.

## See Also

- [Configuration](/start/config/) — Full config reference
- [SEO](/features/seo/) — Sitemaps, feeds, and OpenGraph

---

Title: Related Posts
URL: https://hwaro.hahwul.com/features/related-posts/
Source: content/features/related-posts.md

Automatically recommend related content based on shared taxonomy terms (tags, categories, etc.).

## Configuration

Enable in `config.toml`:

```toml
[related]
enabled = true
limit = 5
taxonomies = ["tags"]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Enable related posts computation |
| limit | int | 5 | Maximum number of related posts per page |
| taxonomies | array | ["tags"] | Taxonomy names used to compute similarity |

## How It Works

1. Hwaro builds an inverted index of taxonomy terms to pages
2. For each page, it counts how many taxonomy terms are shared with other pages
3. Pages with more shared terms rank higher
4. Results are filtered by language (multilingual sites only show same-language posts)
5. The top N results (up to `limit`) are assigned as related posts

Draft pages, index pages, and generated pages are excluded from related post computation.

## Template Variable

Each page has a `related_posts` array containing the related pages sorted by relevance:

| Variable | Type | Description |
|----------|------|-------------|
| related_posts | array | Pages related to the current page, sorted by shared term count |

Each item in `related_posts` is a full page object with access to all page variables (`title`, `url`, `description`, `date`, `tags`, etc.).

## Usage in Templates

### Basic Related Posts

```jinja
{% if related_posts | length > 0 %}
<section class="related-posts">
  <h2>Related Posts</h2>
  <ul>
    {% for post in related_posts %}
    <li>
      <a href="{{ post.url }}">{{ post.title }}</a>
      {% if post.description %}
        <p>{{ post.description }}</p>
      {% endif %}
    </li>
    {% endfor %}
  </ul>
</section>
{% endif %}
```

### With Tags Display

```jinja
{% if related_posts | length > 0 %}
<aside class="related">
  <h3>You might also like</h3>
  {% for post in related_posts %}
  <article>
    <a href="{{ post.url }}">{{ post.title }}</a>
    <div class="tags">
      {% for tag in post.tags %}
        <span class="tag">{{ tag }}</span>
      {% endfor %}
    </div>
  </article>
  {% endfor %}
</aside>
{% endif %}
```

## Using Multiple Taxonomies

You can base related posts on multiple taxonomies for better relevance:

```toml
[related]
enabled = true
limit = 5
taxonomies = ["tags", "categories"]
```

Posts sharing terms in multiple taxonomies will rank higher. For example, a post sharing 2 tags and 1 category with another post scores 3, while a post sharing only 1 tag scores 1.

## See Also

- [Taxonomies](/writing/taxonomies/) — Tags and categories used for scoring
- [Series](/features/series/) — Ordered content grouping
- [Configuration](/start/config/) — Related posts config reference

---

Title: Search
URL: https://hwaro.hahwul.com/features/search/
Source: content/features/search.md

Hwaro generates a search index that works with Fuse.js for client-side search.

## Configuration

Enable in `config.toml`:

```toml
[search]
enabled = true
format = "fuse_json"
fields = ["title", "content", "description", "tags", "url", "section"]
filename = "search.json"
exclude = ["/private", "/drafts"]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Generate search index |
| format | string | "fuse_json" | Search index format |
| fields | array | ["title", "content"] | Fields to include in index |
| filename | string | "search.json" | Output filename |
| exclude | array | [] | Paths (prefixes) to exclude from search index |
| tokenize_cjk | bool | false | Enable CJK bigram tokenization |

## Generated Files

When enabled, Hwaro generates `/search.json` (configurable via `filename`):

```json
[
  {
    "title": "My Post",
    "url": "/blog/my-post/",
    "content": "Page content...",
    "description": "Post description",
    "section": "blog",
    "tags": ["tutorial"]
  }
]
```

## Fields Indexed

| Field | Description |
|-------|-------------|
| title | Page title |
| url | Page URL |
| content | Page content (if `"content"` is in `fields`) |
| description | Page description |
| section | Section name |
| tags | Page tags |

## Client-Side Implementation

### Using Fuse.js

Add to your template:

```html
<script src="https://cdn.jsdelivr.net/npm/fuse.js@7.0.0"></script>
<script>
let searchIndex = [];

// Load index
fetch('/search.json')
  .then(res => res.json())
  .then(data => {
    searchIndex = data;
  });

// Initialize Fuse.js
function search(query) {
  const fuse = new Fuse(searchIndex, {
    keys: ['title', 'content', 'description', 'tags'],
    threshold: 0.3
  });
  return fuse.search(query);
}
</script>
```

### Search Form

```html
<form id="search-form">
  <input type="search" id="search-input" placeholder="Search...">
</form>

<div id="search-results"></div>

<script>
const input = document.getElementById('search-input');
const results = document.getElementById('search-results');

input.addEventListener('input', (e) => {
  const query = e.target.value;
  if (query.length < 2) {
    results.innerHTML = '';
    return;
  }
  
  const matches = search(query);
  results.innerHTML = matches
    .slice(0, 10)
    .map(m => `
      <a href="${m.item.url}">
        <h3>${m.item.title}</h3>
        <p>${m.item.description || ''}</p>
      </a>
    `)
    .join('');
});
</script>
```

## CJK Search Support

For sites with Chinese, Japanese, or Korean content, enable CJK tokenization to improve search accuracy. CJK languages often lack spaces between words, making it difficult for search libraries to tokenize text properly.

When enabled, CJK character runs are split into overlapping bigrams (2-character pairs), allowing search terms to match within longer text.

**Example:** `"검색엔진"` → `"검색 색엔 엔진"` (search query `"검색"` now matches)

### Configuration

```toml
[search]
enabled = true
tokenize_cjk = true
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| tokenize_cjk | bool | false | Enable CJK bigram tokenization for search index |

### How It Works

- Only `title`, `content`, and `description` fields are tokenized
- `url`, `tags`, and `section` fields are left unchanged (structural fields)
- Non-CJK text passes through unmodified
- Works with both Fuse.js and ElasticLunr formats

### Notes

- Enabling this option slightly increases the search index size
- The bigram approach works well for most CJK search scenarios
- Korean text with natural spaces (e.g., `"검색 엔진"`) is handled correctly

## Excluding Pages

### Front Matter

Exclude individual pages from search with front matter:

```markdown
+++
title = "Terms of Service"
in_search_index = false
+++
```

### Configuration

Exclude entire sections or paths using `config.toml`:

```toml
[search]
exclude = ["/private", "/drafts"]
```

### Field Selection

Control which fields appear in the search index by specifying `fields`:

```toml
[search]
enabled = true
fields = ["title", "description", "tags", "url"]
```

Available fields: `title`, `content`, `description`, `tags`, `url`, `section`.

Omitting `content` from `fields` significantly reduces the index file size for large sites.

## Performance Tips

### Large Sites

For sites with many pages:

1. Remove `"content"` from `fields` to reduce index size
2. Use Fuse.js `ignoreLocation` option
3. Implement debounced search

```javascript
function debounce(fn, delay) {
  let timeout;
  return (...args) => {
    clearTimeout(timeout);
    timeout = setTimeout(() => fn(...args), delay);
  };
}

input.addEventListener('input', debounce((e) => {
  // search logic
}, 200));
```

### Lazy Loading

Load index only when search is focused:

```javascript
let indexLoaded = false;

input.addEventListener('focus', async () => {
  if (indexLoaded) return;
  const res = await fetch('/search.json');
  searchIndex = await res.json();
  indexLoaded = true;
});
```

## Alternative: Pagefind

For larger sites, consider [Pagefind](https://pagefind.app/):

```bash
# After build
npx pagefind --site public
```

Add to config as post-build hook:

```toml
[build]
hooks.post = ["npx pagefind --site public"]
```

## See Also

- [Configuration](/start/config/) — Search config reference
- [Multilingual](/features/multilingual/) — CJK tokenization and i18n search

---

Title: SEO
URL: https://hwaro.hahwul.com/features/seo/
Source: content/features/seo.md

Hwaro includes built-in SEO features: sitemaps, RSS feeds, robots.txt, and social sharing meta tags.

## Sitemap

Automatically generates `sitemap.xml` for search engines.

### Configuration

```toml
[sitemap]
enabled = true
filename = "sitemap.xml"
changefreq = "weekly"
priority = 0.5
exclude = ["/private", "/drafts"]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Generate `sitemap.xml` |
| filename | string | "sitemap.xml" | Output filename |
| changefreq | string | "weekly" | Default change frequency for all pages |
| priority | float | 0.5 | Default priority for all pages (0.0 to 1.0) |
| exclude | array | [] | Path prefixes to exclude (e.g., `["/private"]` excludes `/private`, `/private/page.html`) |

### Output

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <lastmod>2024-01-15</lastmod>
  </url>
  <url>
    <loc>https://example.com/about/</loc>
  </url>
</urlset>
```

### Excluding Pages

Set `in_sitemap = false` in front matter:

```markdown
+++
title = "Private Page"
in_sitemap = false
+++
```

---

## RSS Feeds

Generate RSS feeds for your site and sections.

### Configuration

```toml
[feeds]
enabled = true
type = "rss"              # "rss" or "atom"
limit = 20                # Maximum number of items
truncate = 0              # Truncate to N characters (0 = no truncation)
full_content = true       # true = full HTML body, false = description/summary only
filename = ""             # Leave empty for default (rss.xml or atom.xml)
sections = []             # Limit to specific sections, e.g., ["posts"]
```

| Option | Default | Description |
|--------|---------|-------------|
| `enabled` | `false` | Enable feed generation |
| `type` | `"rss"` | Feed format: `"rss"` or `"atom"` |
| `limit` | `10` | Maximum number of items in feed |
| `truncate` | `0` | Truncate content to N characters (0 = full content) |
| `full_content` | `true` | `true` = full HTML in feed, `false` = use front matter `description` or auto-generated summary |
| `filename` | `""` | Custom filename (empty = `rss.xml` or `atom.xml`) |
| `sections` | `[]` | Limit feed to specific sections |
| `default_language_only` | `true` | Multilingual: main feed includes default language only |

### Section Feeds

Enable per-section feeds:

```markdown
+++
title = "Blog"
generate_feeds = true
+++
```

Generates `/blog/rss.xml`.

### Output

- `/rss.xml` — Site-wide feed
- `/blog/rss.xml` — Section feed (if enabled)

### Multilingual Feeds

When the site is multilingual, feeds are generated per language automatically:

| Language | Feed Path | Contents |
|----------|-----------|----------|
| Default (e.g., `en`) | `/rss.xml` | Default language pages only (configurable) |
| Non-default (e.g., `ko`) | `/ko/rss.xml` | Only Korean pages |
| Non-default (e.g., `ja`) | `/ja/rss.xml` | Only Japanese pages |

By default, the main site feed includes **only default language pages** (`default_language_only = true`). Set `default_language_only = false` to include all languages in the main feed. Each non-default language with `generate_feed = true` gets its own separate feed regardless of this setting.

```toml
[feeds]
enabled = true
default_language_only = true   # true (default): main feed = default language only
                               # false: main feed includes all languages
```

Per-language feed control:

```toml
[languages.ko]
language_name = "한국어"
generate_feed = true    # Generates /ko/rss.xml (default: true)

[languages.ja]
language_name = "日本語"
generate_feed = false   # No /ja/rss.xml will be generated
```

Language feeds share the same `sections`, `limit`, `truncate`, and `full_content` settings from `[feeds]` config. RSS language feeds include a `<language>` tag, and Atom feeds include an `xml:lang` attribute. The feed title includes the language name (e.g., `"My Site (한국어)"`).

### Template Links

```jinja
<link rel="alternate" type="application/rss+xml" 
      href="{{ base_url }}/rss.xml" 
      title="{{ site.title }}">

{% if page.language and page.language != "en" %}
<link rel="alternate" type="application/rss+xml"
      href="{{ base_url }}/{{ page.language }}/rss.xml"
      title="{{ site.title }} ({{ page.language }})">
{% endif %}
```

---

## Robots.txt

Control search engine crawling.

### Configuration

```toml
[robots]
enabled = true
```

With custom rules:

```toml
[robots]
enabled = true
rules = [
  { user_agent = "*", disallow = ["/admin", "/private"] },
  { user_agent = "GPTBot", disallow = ["/"] }
]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | true | Generate `robots.txt` |
| filename | string | "robots.txt" | Output filename |
| rules | array | [] | List of user-agent rules with `allow` and `disallow` paths |

When no rules are configured, Hwaro generates a default allow-all rule. If a rule has both `allow` and `disallow` empty, an explicit `Allow: /` is added to prevent ambiguous behavior.

### Output

```
User-agent: *
Allow: /
Sitemap: https://example.com/sitemap.xml
```

---

## LLMs.txt

Generate instruction files for AI/LLM crawlers following the [llms.txt standard](https://llmstxt.org/).

```toml
[llms]
enabled = true
instructions = "This site's content is provided under the MIT license."
full_enabled = true
```

See [LLMs.txt](/features/llms-txt/) for full configuration and output details.

---

## OpenGraph Tags

Social sharing meta tags for Facebook, LinkedIn, etc.

### Configuration

```toml
[og]
default_image = "/images/og-default.png"
type = "website"
fb_app_id = "your_fb_app_id"
```

| Key | Description |
|-----|-------------|
| default_image | Fallback image when page has none |
| type | OpenGraph type (website, article) |
| fb_app_id | Facebook App ID (optional) |

### Page-Level Override

```markdown
+++
title = "My Article"
description = "Article description"
image = "/images/article-cover.png"
+++
```

### Template Usage

```jinja
<head>
  {{ og_tags | safe }}
</head>
```

### Output

```html
<meta property="og:title" content="My Article">
<meta property="og:type" content="article">
<meta property="og:url" content="https://example.com/my-article/">
<meta property="og:description" content="Article description">
<meta property="og:image" content="https://example.com/images/article-cover.png">
```

---

## Twitter Cards

Twitter-specific sharing tags.

### Configuration

```toml
[og]
twitter_card = "summary_large_image"
twitter_site = "@yourusername"
twitter_creator = "@authorusername"
```

| Key | Description |
|-----|-------------|
| twitter_card | Card type: summary, summary_large_image |
| twitter_site | Site's Twitter handle |
| twitter_creator | Author's Twitter handle |

### Template Usage

```jinja
<head>
  {{ twitter_tags | safe }}
</head>
```

Or include both OG and Twitter:

```jinja
<head>
  {{ og_all_tags | safe }}
</head>
```

### Output

```html
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="My Article">
<meta name="twitter:description" content="Article description">
<meta name="twitter:image" content="https://example.com/images/article-cover.png">
<meta name="twitter:site" content="@yourusername">
```

---

## JSON-LD Structured Data

Hwaro automatically generates Article and BreadcrumbList JSON-LD for every page.

```jinja
<head>
  {{ jsonld | safe }}
</head>
```

Additional schema types (FAQ, HowTo, WebSite, Organization) are also available. See [Structured Data](/features/structured-data/) for all types, configuration, and output examples.

---

## Template Variables

### Pre-rendered HTML

These variables output ready-to-use HTML tags:

| Variable | Description |
|----------|-------------|
| og_tags | OpenGraph meta tags |
| twitter_tags | Twitter Card meta tags |
| og_all_tags | Both OG and Twitter tags |
| canonical_tag | Canonical link tag |
| hreflang_tags | Hreflang alternate link tags |
| jsonld | Article + BreadcrumbList JSON-LD |
| jsonld_article | Article JSON-LD only |
| jsonld_breadcrumb | BreadcrumbList JSON-LD only |
| page_description | Page description (fallback: site) |
| page_image | Page image (fallback: og.default_image) |

### Structured SEO Object

The `seo` object provides individual field access for building custom meta tags:

| Property | Type | Description |
|----------|------|-------------|
| seo.canonical_url | String | Full canonical URL |
| seo.og_type | String | OpenGraph type (default: "article") |
| seo.og_image | String | Resolved absolute image URL |
| seo.twitter_card | String | Twitter card type |
| seo.twitter_site | String | Twitter site handle |
| seo.twitter_creator | String | Twitter creator handle |
| seo.fb_app_id | String | Facebook App ID |
| seo.hreflang | Array | Language translation links |

```jinja
<head>
  <link rel="canonical" href="{{ seo.canonical_url }}">
  <meta property="og:title" content="{{ page.title }}">
  <meta property="og:type" content="{{ seo.og_type }}">
  <meta property="og:url" content="{{ seo.canonical_url }}">
  {% if page.description %}
  <meta property="og:description" content="{{ page.description }}">
  {% endif %}
  {% if seo.og_image %}
  <meta property="og:image" content="{{ seo.og_image }}">
  {% endif %}
  {% if seo.fb_app_id %}
  <meta property="fb:app_id" content="{{ seo.fb_app_id }}">
  {% endif %}
  <meta name="twitter:card" content="{{ seo.twitter_card }}">
  <meta name="twitter:title" content="{{ page.title }}">
  {% if seo.twitter_site %}
  <meta name="twitter:site" content="{{ seo.twitter_site }}">
  {% endif %}
</head>
```

---

## Complete Example

### config.toml

```toml
title = "My Site"
description = "A great site"
base_url = "https://example.com"

[sitemap]
enabled = true

[feeds]
enabled = true
limit = 20

[robots]
enabled = true

[og]
default_image = "/images/og-default.png"
type = "website"
twitter_card = "summary_large_image"
twitter_site = "@mysite"
```

### templates/base.html

```jinja
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>{{ page.title }} - {{ site.title }}</title>
  <meta name="description" content="{{ page.description | default(value=site.description) }}">
  {{ og_all_tags | safe }}
  {{ canonical_tag | safe }}
  {{ hreflang_tags | safe }}
  {{ jsonld | safe }}
  <link rel="alternate" type="application/rss+xml" href="{{ base_url }}/rss.xml">
</head>
<body>
  {% block content %}{% endblock %}
</body>
</html>
```

## See Also

- [LLMs.txt](/features/llms-txt/) — AI/LLM crawler instructions
- [Multilingual](/features/multilingual/) — Hreflang and canonical tags for i18n
- [Configuration](/start/config/) — Full config reference

---

Title: Series
URL: https://hwaro.hahwul.com/features/series/
Source: content/features/series.md

Group related posts into an ordered series so readers can follow content sequentially.

## Configuration

Enable in `config.toml`:

```toml
[series]
enabled = true
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Enable series grouping |

## Assigning Posts to a Series

Use front matter to assign a post to a series:

```toml
+++
title = "Part 1: Getting Started"
series = "Building a CLI Tool"
series_weight = 1
+++
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| series | string | — | Series name to assign this post to |
| series_weight | int | 0 | Order within the series (lower = earlier) |

Posts within a series are sorted by `series_weight`, then by date, then by title.

## Template Variables

Each page in a series has the following variables:

| Variable | Type | Description |
|----------|------|-------------|
| series | string | The series name |
| series_index | int | 1-based position in the series |
| series_pages | array | All pages in the same series (sorted) |

## Usage in Templates

### Series Navigation

```jinja
{% if series %}
<nav class="series-nav">
  <h3>{{ series }}</h3>
  <ol>
    {% for p in series_pages %}
    <li{% if p.url == page.url %} class="current"{% endif %}>
      <a href="{{ p.url }}">{{ p.title }}</a>
    </li>
    {% endfor %}
  </ol>
</nav>
{% endif %}
```

### Previous / Next Links

```jinja
{% if series_pages | length > 1 %}
<div class="series-pager">
  {% if series_index > 1 %}
    <a href="{{ series_pages[series_index - 2].url }}">← Previous</a>
  {% endif %}
  <span>Part {{ series_index }} of {{ series_pages | length }}</span>
  {% if series_index < series_pages | length %}
    <a href="{{ series_pages[series_index].url }}">Next →</a>
  {% endif %}
</div>
{% endif %}
```

## Example

Given three posts:

```
content/
  tutorials/
    cli-part1.md   # series = "CLI Tool", series_weight = 1
    cli-part2.md   # series = "CLI Tool", series_weight = 2
    cli-part3.md   # series = "CLI Tool", series_weight = 3
```

Each post will have `series_pages` containing all three posts in order, and `series_index` set to 1, 2, or 3 respectively.

## See Also

- [Pages](/writing/pages/) — Front matter fields for series
- [Related Posts](/features/related-posts/) — Content recommendations
- [Data Model](/templates/data-model/) — Series template variables

---

Title: Streaming Build
URL: https://hwaro.hahwul.com/features/streaming-build/
Source: content/features/streaming-build.md

Streaming build reduces memory usage for large sites by processing pages in batches during the Render phase. Instead of holding all rendered HTML in memory at once, each batch is rendered, written to disk, and then released before the next batch begins.

```bash
hwaro build --stream
```

## When to Use

For most sites, the default build mode works well. Streaming build is useful when:

- Your site has thousands of pages
- The build process consumes too much memory
- You're building in a memory-constrained environment (CI, containers, small VMs)

## Usage

### `--stream` flag

Enable streaming with a default batch size of 50 pages:

```bash
hwaro build --stream
```

### `--memory-limit` flag

Set a memory limit and let Hwaro calculate the optimal batch size automatically:

```bash
hwaro build --memory-limit 512M
hwaro build --memory-limit 2G
```

Accepts `G` (gigabytes), `M` (megabytes), and `K` (kilobytes) suffixes. The batch size is calculated using a heuristic of ~50KB per page.

### Environment variable

Set `HWARO_MEMORYLIMIT` as a fallback when the CLI flag is not provided:

```bash
export HWARO_MEMORYLIMIT=1G
hwaro build
```

The CLI `--memory-limit` flag always overrides the environment variable.

### Combined flags

You can combine `--stream` with `--memory-limit`. When `--memory-limit` is provided, it determines the batch size regardless of `--stream`:

```bash
hwaro build --stream --memory-limit 512M
```

## Flag Interaction

| `--stream` | `--memory-limit` | `HWARO_MEMORYLIMIT` | Result |
|---|---|---|---|
| - | - | - | Normal build |
| yes | - | - | Streaming, batch=50 |
| - | 2G | - | Streaming, batch≈20000 |
| - | - | 1G | Streaming, batch≈10000 |
| yes | 512M | - | Streaming, batch≈5000 |
| - | 2G | 1G | CLI wins (2G) |

## How It Works

1. During the Render phase, pages are split into batches
2. Each batch is rendered using the same parallel/sequential logic as a normal build
3. After each batch is written to disk, `page.content` is cleared to free memory
4. The garbage collector is invoked to reclaim the released memory
5. After the Generate phase (feeds, sitemap, search index), `page.raw_content` is also cleared

The Generate phase (feeds, search, sitemap, llms.txt) still works correctly because these generators already fall back to re-rendering from `raw_content` when `page.content` is empty.

## Output

The build output is **identical** whether streaming is enabled or not. Streaming only affects memory usage during the build process.

Use `--verbose` to see batch progress:

```bash
hwaro build --stream --verbose
```

```
Building site...
  Streaming mode enabled (batch size: 50)
  ...
  Streaming batch 1 (50 pages)
  Streaming batch 2 (50 pages)
  Streaming batch 3 (23 pages)
  ...
```

## See Also

- [CLI Reference](/start/cli/) — Full list of build flags
- [Build Hooks](/features/build-hooks/) — Run custom commands before/after builds

---

Title: Structured Data
URL: https://hwaro.hahwul.com/features/structured-data/
Source: content/features/structured-data.md

Hwaro automatically generates JSON-LD structured data for rich search results. Beyond the default Article and BreadcrumbList types, you can enable additional Schema.org types.

## Auto-Generated (Always)

These are generated for every page:

- **Article** — headline, dates, description, author, image
- **BreadcrumbList** — auto-generated from page hierarchy/ancestors

Available as template variables: `{{ jsonld }}`, `{{ jsonld_article }}`, `{{ jsonld_breadcrumb }}`

## Site-Wide Schemas

Generated once and available on all pages:

### WebSite + SearchAction

Enables the sitelinks search box in Google. Automatically includes `SearchAction` when `[search]` is enabled.

```jinja
{{ jsonld_website }}
```

### Organization

Basic organization info from site config. Uses `og.default_image` as logo if set.

```jinja
{{ jsonld_organization }}
```

## Page-Specific Schemas

Set `schema_type` in front matter to auto-detect and include additional types:

### FAQPage

```toml
+++
title = "Frequently Asked Questions"
schema_type = "FAQ"
faq_questions = ["What is Hwaro?", "How do I install it?"]
faq_answers = ["A fast static site generator.", "Run crystal build."]
+++
```

Or use paired array format:
```toml
faq = ["Question 1", "Answer 1", "Question 2", "Answer 2"]
```

The FAQ schema is auto-included in `{{ jsonld }}` when `schema_type = "FAQ"`. You can also use `{{ jsonld_faq }}` directly.

### HowTo

```toml
+++
title = "Getting Started with Hwaro"
schema_type = "HowTo"
howto_names = ["Install", "Configure", "Build"]
howto_texts = ["Run the install command.", "Edit config.toml.", "Run hwaro build."]
+++
```

Or use paired array format:
```toml
howto_steps = ["Step Name", "Step Description", "Step 2 Name", "Step 2 Description"]
```

Auto-included in `{{ jsonld }}` when `schema_type = "HowTo"`. Also available as `{{ jsonld_howto }}`.

### Person

Use in templates for author pages:

```jinja
{{ jsonld_person }}
```

Or build manually via the template function (for author-specific pages).

## Template Variables

| Variable | Scope | Description |
|----------|-------|-------------|
| `jsonld` | per-page | All applicable JSON-LD combined (Article + Breadcrumb + extended type) |
| `jsonld_article` | per-page | Article schema only |
| `jsonld_breadcrumb` | per-page | BreadcrumbList schema only |
| `jsonld_faq` | per-page | FAQPage schema (empty if not FAQ) |
| `jsonld_howto` | per-page | HowTo schema (empty if not HowTo) |
| `jsonld_website` | global | WebSite + SearchAction schema |
| `jsonld_organization` | global | Organization schema |

## Usage in Templates

Typical placement in your base template `<head>`:

```jinja
<head>
  {{ jsonld }}
  {{ jsonld_website }}
</head>
```

## See Also

- [SEO](/features/seo/) — Sitemaps, feeds, OpenGraph, and canonical tags
- [Configuration](/start/config/) — Full config reference

---

Title: Syntax Highlighting
URL: https://hwaro.hahwul.com/features/syntax-highlighting/
Source: content/features/syntax-highlighting.md

Code blocks in Markdown are automatically syntax highlighted.

## Usage

Use fenced code blocks with a language identifier:

````markdown
```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
```
````

## Supported Languages

Common languages:

| Language | Identifiers |
|----------|-------------|
| JavaScript | javascript, js |
| TypeScript | typescript, ts |
| Python | python, py |
| Ruby | ruby, rb |
| Go | go, golang |
| Rust | rust, rs |
| Crystal | crystal, cr |
| HTML | html |
| CSS | css |
| JSON | json |
| YAML | yaml, yml |
| TOML | toml |
| Markdown | markdown, md |
| Shell | bash, sh, shell |
| SQL | sql |

## Configuration

Configure in `config.toml`:

```toml
[highlight]
enabled = true
theme = "github-dark"
use_cdn = true
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | true | Enable syntax highlighting |
| theme | string | "github" | Highlight.js theme name |
| use_cdn | bool | true | Load assets from CDN (false = local files) |

## Themes

Hwaro uses [Highlight.js](https://highlightjs.org/) themes. Any valid Highlight.js theme name works. Popular choices:

- `github` — Light GitHub style (default)
- `github-dark` — Dark GitHub style
- `github-dark-dimmed` — Dimmed dark GitHub style
- `monokai` — Classic dark theme
- `dracula` — Dark purple theme
- `solarized-dark` — Solarized dark
- `solarized-light` — Solarized light
- `nord` — Arctic color palette
- `tokyo-night-dark` — Tokyo Night dark

Browse all available themes at [highlightjs.org/demo](https://highlightjs.org/demo).

## CDN vs Local

When `use_cdn = true` (default), assets are loaded from cdnjs:

```html
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
```

When `use_cdn = false`, assets are loaded from local paths:

```html
<link rel="stylesheet" href="/assets/css/highlight/github-dark.min.css">
<script src="/assets/js/highlight.min.js"></script>
```

You must provide the local files yourself when using `use_cdn = false`.

## Template Integration

Include highlighting assets in templates:

```jinja
<head>
  {{ highlight_css | safe }}
</head>
<body>
  ...
  {{ highlight_js | safe }}
</body>
```

Or combined:

```jinja
<head>
  {{ highlight_tags | safe }}
</head>
```

## Build Options

Disable highlighting for faster builds:

```bash
hwaro build --skip-highlighting
```

## Plain Text Blocks

For no highlighting, omit the language or use `text`:

````markdown
```text
Plain text content
No highlighting applied
```
````

## Inline Code

Inline code uses backticks and is not highlighted:

```markdown
Use the `console.log()` function.
```

## See Also

- [Markdown Extensions](/features/markdown-extensions/) — Code blocks and language support
- [Configuration](/start/config/) — Highlight config reference

---

Title: Start
URL: https://hwaro.hahwul.com/start/
Source: content/start/_index.md

## What is Hwaro?

Hwaro is a lightweight and fast static site generator (SSG) written in [Crystal](https://crystal-lang.org). It processes Markdown content with TOML front matter and Jinja2-compatible templates (Crinja) to build high-performance static sites.

Hwaro is designed to help you **build your own website without relying on pre-made themes**. Instead of picking a theme and tweaking it, you craft your templates and styles from scratch, giving you full control over every aspect of your site. With parallel builds, incremental caching, and a dev server with live reload, Hwaro keeps the development experience fast and smooth.

## Quick Start

```bash
# Install (see Installation for all methods)
brew tap hwaro/hwaro && brew install hwaro

# Create a new site
hwaro init my-site --scaffold blog
cd my-site

# Start dev server with live reload
hwaro serve
```

Open `http://localhost:3000` to preview your site.

## Why "Hwaro"?

Hwaro (화로) is the Korean word for **Furnace** — the same name used in Minecraft's Korean localization. In the game, the Furnace is an essential tool that transforms raw materials into useful items. Hwaro aims to serve the same role for static sites: feed in your content, and it crafts a complete website.

![Hwaro in Minecraft](/images/hwaro-minecraft.webp)

---

Title: CLI
URL: https://hwaro.hahwul.com/start/cli/
Source: content/start/cli.md

Hwaro provides commands for creating, building, and serving your site.

## Commands

### init

Create a new site:

```bash
hwaro init my-site
hwaro init my-site --scaffold blog
hwaro init my-site --scaffold docs
```

You can also use a remote scaffold from a GitHub repository:

```bash
# GitHub shorthand
hwaro init my-site --scaffold github:user/repo
hwaro init my-site --scaffold github:user/repo/docs

# Full URL
hwaro init my-site --scaffold https://github.com/user/repo
hwaro init my-site --scaffold https://github.com/user/repo/tree/main/docs
```

Remote scaffolds fetch `config.toml`, `templates/`, `static/`, and content structure from the repository. Content files keep only front matter (metadata) so you can see the expected page structure without the original body text. Set `GITHUB_TOKEN` environment variable to avoid API rate limits.

**Options:**

| Flag | Description |
|------|-------------|
| --scaffold TYPE | Built-in (`simple`, `bare`, `blog`, `blog-dark`, `docs`, `docs-dark`) or remote source (`github:user/repo[/path]`, URL) |
| --agents MODE | AGENTS.md content mode: `remote` (lightweight, default) or `local` (full embedded reference) |
| -f, --force | Force creation even if directory is not empty |
| --skip-agents-md | Skip creating AGENTS.md file |
| --skip-sample-content | Skip creating sample content files |
| --skip-taxonomies | Skip taxonomies configuration and templates |
| --include-multilingual LANGS | Enable multilingual support (e.g., `en,ko,ja`) |

### new

Create a new content file:

```bash
hwaro new content/about.md
hwaro new content/blog/my-post.md
hwaro new -t "My Post Title"
hwaro new posts/my-post.md -a posts
hwaro new my-post.md --section blog --draft --tags "go,web" --date 2026-03-22
```

Creates a Markdown file with front matter template. Supports **archetypes** for customizable templates.

**Options:**

| Flag | Description |
|------|-------------|
| -t, --title TITLE | Content title |
| --date DATE | Content date (default: now, e.g. `2026-03-22`) |
| --draft | Mark as draft |
| --tags TAGS | Comma-separated tags |
| -s, --section NAME | Section directory (e.g. `blog`, `docs`) |
| -a, --archetype NAME | Archetype to use |

**Archetypes:**

Archetypes are template files in `archetypes/` directory that define default front matter for new content:

- `archetypes/default.md` - Default template for all content
- `archetypes/posts.md` - Used for `hwaro new posts/...`
- `archetypes/tools/develop.md` - Used for `hwaro new tools/develop/...`

Archetype files support placeholders: `{{ title }}`, `{{ date }}`, `{{ draft }}`, `{{ tags }}`

Example archetype (`archetypes/posts.md`):
```
---
title: "{{ title }}"
date: {{ date }}
draft: false
tags: []
---

# {{ title }}
```

Archetype matching priority:
1. Explicit `-a` flag (e.g., `-a posts` uses `archetypes/posts.md`)
2. Path-based matching (e.g., `posts/hello.md` checks `archetypes/posts.md`)
3. Nested paths try parent archetypes (e.g., `tools/dev/x.md` tries `tools/dev.md`, then `tools.md`)
4. Falls back to `archetypes/default.md`
5. Uses built-in template if no archetype found

### build

Build the site to `public/`:

```bash
hwaro build
hwaro build --drafts
hwaro build --minify
hwaro build -i /path/to/my-site
hwaro build -i /path/to/my-site -o ./dist
```

**Options:**

| Flag | Description |
|------|-------------|
| -i, --input DIR | Project directory to build (default: current directory) |
| -o, --output DIR | Output directory (default: public) |
| --base-url URL | Temporarily override `base_url` from `config.toml` |
| -d, --drafts | Include draft content |
| --include-expired | Include expired content |
| --include-future | Include future-dated content |
| --minify | Minify output files (see below) |
| --no-parallel | Disable parallel processing |
| --cache | Enable incremental build caching (see below) |
| --full | Force a complete rebuild, clearing the cache |
| --skip-highlighting | Disable syntax highlighting |
| --skip-cache-busting | Disable cache busting query parameters on CSS/JS resources |
| --stream | Enable streaming build to reduce memory usage |
| --memory-limit SIZE | Memory limit for streaming build (e.g. `2G`, `512M`) |
| -v, --verbose | Show detailed output |
| --profile | Print phase-by-phase and per-template build timing |
| --debug | Print debug information after build |

**About `--stream` / `--memory-limit` (Streaming Build):**

For sites with thousands of pages, loading all rendered HTML into memory at once can cause high memory usage. Streaming build processes pages in batches during the Render phase, releasing rendered HTML after each batch is written to disk.

- `--stream` enables streaming with a default batch size of 50 pages.
- `--memory-limit SIZE` enables streaming and calculates the batch size automatically based on the given limit (heuristic: ~50KB per page). Accepts `G`, `M`, `K` suffixes (e.g. `2G`, `512M`, `256K`).
- You can also set the `HWARO_MEMORYLIMIT` environment variable as a fallback. The CLI flag overrides the env var.

| `--stream` | `--memory-limit` | `HWARO_MEMORYLIMIT` | Result |
|---|---|---|---|
| - | - | - | Normal build |
| yes | - | - | Streaming, batch=50 |
| - | 2G | - | Streaming, batch≈20000 |
| - | - | 1G | Streaming, batch≈10000 |
| yes | 512M | - | Streaming, batch≈5000 |
| - | 2G | 1G | CLI wins (2G) |

The build output is identical — streaming only affects memory usage during the build.

**About `--minify`:**

The minify flag performs conservative optimization on generated files:

- **HTML**: Removes comments and trailing whitespace, collapses excessive blank lines. Preserves all indentation, newlines, and content structure.
- **JSON**: Removes whitespace and newlines for compact output.
- **XML**: Removes whitespace between tags for smaller file sizes.

Code blocks (`<pre>`, `<code>`) and script/style content are always preserved intact.

**About `--cache` (Incremental Build):**

When enabled, Hwaro tracks file modification times and content checksums in a `.hwaro_cache.json` file at the project root. On subsequent builds, only files that have changed since the last build are re-rendered. The cache also tracks template and config checksums — if templates or `config.toml` change, all entries are automatically invalidated and every page is rebuilt.

Use `--full` together with `--cache` to force a clean rebuild while still saving the cache for the next run:

```bash
hwaro build --cache --full
```

See [Incremental Build](/features/incremental-build/) for details.

**About `-i, --input`:**

When specified, Hwaro changes its working directory to the given path before building. This lets you build a site located in another directory without `cd`-ing into it first.

- All site sources (`config.toml`, `content/`, `templates/`, `static/`) are read from the input directory.
- **Without `-o`:** The default output directory `public/` is created inside the input directory (i.e., the site's own `public/` folder). This is the natural behavior — `hwaro build -i ../my-site` produces `../my-site/public/`.
- **With `-o`:** The output path is resolved relative to **your current directory** (not the input directory), so `hwaro build -i ../my-site -o ./dist` writes output to `./dist` in your shell's CWD.
- If `-i` is omitted, behavior is unchanged — the current directory is used.

### serve

Start a development server with live reload:

```bash
hwaro serve
hwaro serve --port 8080
hwaro serve --open
hwaro serve --access-log
hwaro serve --live-reload
hwaro serve -i /path/to/my-site
hwaro serve -i /path/to/my-site -p 8080
```

**Options:**

| Flag | Description |
|------|-------------|
| -i, --input DIR | Project directory to serve (default: current directory) |
| -b, --bind HOST | Bind address (default: 0.0.0.0) |
| -p, --port PORT | Port number (default: 3000) |
| --base-url URL | Temporarily override `base_url` from `config.toml` |
| --minify | Serve minified output |
| --open | Open browser after starting |
| -d, --drafts | Include draft content |
| --include-expired | Include expired content |
| --include-future | Include future-dated content |
| -v, --verbose | Show detailed output |
| --debug | Print debug information after each rebuild |
| --access-log | Show HTTP access log (e.g. GET requests) |
| --live-reload | Enable browser live reload on file changes |
| --cache | Enable build caching (skip unchanged files) |
| --stream | Enable streaming build to reduce memory usage |
| --memory-limit SIZE | Memory limit for streaming build (e.g. `2G`, `512M`) |
| --skip-cache-busting | Disable cache busting query parameters on CSS/JS resources |
| --skip-og-image | Skip auto OG image generation |
| --skip-image-processing | Skip image resizing and LQIP generation |
| --profile | Print phase-by-phase and per-template build timing |

The server watches for file changes and rebuilds automatically. It uses **smart rebuild strategies** based on what changed:

| Change Type | Strategy | Description |
|-------------|----------|-------------|
| `config.toml` | Full rebuild | Rebuilds entire site |
| `content/` only | Incremental | Rebuilds only affected content pages |
| `templates/` only | Template re-render | Re-renders all pages with existing content |
| `static/` only | Static copy | Copies only changed static files |
| Mixed / new / deleted files | Full rebuild | Rebuilds entire site |

**About `--live-reload`:**

When enabled, the server injects a small WebSocket client script into every HTML response. After each successful rebuild, connected browsers automatically refresh the page — no manual reload needed. The client uses exponential backoff (1s–30s) for reconnection, so restarting the server won't break the connection permanently.

When `-i` is specified, the server operates as if you had `cd`-ed into the given directory — watching and serving from that project root.

### deploy

Deploy the generated site to configured targets.

```bash
hwaro deploy [target ...]
hwaro deploy --dry-run
```

**Options:**

| Flag | Description |
|------|-------------|
| -s, --source DIR | Source directory to deploy (default: deployment.source_dir or public) |
| --dry-run | Show planned changes without writing |
| --confirm | Ask for confirmation before deploying |
| --force | Force upload/copy (ignore file comparisons) |
| --max-deletes N | Maximum number of deletes (default: deployment.maxDeletes or 256, -1 disables) |
| --list-targets | List configured deployment targets and exit |

### doctor

Diagnose config and content issues (top-level shortcut):

```bash
hwaro doctor               # Diagnose config and content issues
hwaro doctor --fix         # Add missing config sections to config.toml
```

See [doctor](/start/tools/doctor/) for details. `hwaro tool doctor` also works as an alias.

### tool

Utility tools for content management:

```bash
hwaro tool convert to-yaml      # Convert frontmatter to YAML
hwaro tool convert to-toml      # Convert frontmatter to TOML
hwaro tool list all             # List all content files
hwaro tool list drafts          # List draft files
hwaro tool list published       # List published files
hwaro tool check-links          # Check for dead external links
hwaro tool platform netlify       # Generate Netlify config
hwaro tool platform vercel        # Generate Vercel config
hwaro tool platform cloudflare    # Generate Cloudflare Pages config
hwaro tool platform github-pages  # Generate GitHub Pages deploy workflow
hwaro tool platform gitlab-ci     # Generate GitLab CI config
hwaro tool import wordpress export.xml   # Import from WordPress
hwaro tool import jekyll /path/to/site   # Import from Jekyll
hwaro tool import hugo /path/to/site     # Import from Hugo
hwaro tool import notion /path/to/export # Import from Notion
hwaro tool import obsidian /path/to/vault # Import from Obsidian
hwaro tool import hexo /path/to/site     # Import from Hexo
hwaro tool import astro /path/to/site    # Import from Astro
hwaro tool import eleventy /path/to/site # Import from Eleventy
hwaro tool agents-md                    # Print local AGENTS.md to stdout
hwaro tool agents-md --remote           # Print remote (lightweight) version
hwaro tool agents-md --write            # Write AGENTS.md to file
hwaro tool agents-md --remote --write   # Write remote version to file

# JSON output
hwaro tool list all --json
hwaro tool doctor --json
hwaro tool check-links --json
hwaro tool convert to-yaml --json
```

**Subcommands:**

| Subcommand | Description |
|------------|-------------|
| [convert](/start/tools/convert/) | Convert frontmatter between YAML and TOML formats |
| [list](/start/tools/list/) | List content files by status (all, drafts, published) |
| [check-links](/start/tools/deadlink/) | Check for dead links in content files |
| [doctor](/start/tools/doctor/) | Diagnose config and content issues |
| [platform](/start/tools/platform/) | Generate platform config and CI/CD workflow files |
| ci *(deprecated)* | Use `tool platform github-pages` instead |
| import | Import content from WordPress, Jekyll, Hugo, Notion, Obsidian, Hexo, Astro, or Eleventy |
| [agents-md](/start/tools/agents-md/) | Generate or update AGENTS.md file |

**Common Options:**

| Flag | Description |
|------|-------------|
| -c, --content DIR | Limit to specific content directory |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

See [Tools & Completion](/start/tools/) for detailed usage.

### completion

Generate shell completion scripts:

```bash
hwaro completion bash    # Bash completion script
hwaro completion zsh     # Zsh completion script
hwaro completion fish    # Fish completion script
```

**Installation:**

```bash
# Bash (add to ~/.bashrc)
eval "$(hwaro completion bash)"

# Zsh (add to ~/.zshrc)
eval "$(hwaro completion zsh)"

# Fish (add to ~/.config/fish/config.fish)
hwaro completion fish | source
```

See [Tools & Completion](/start/tools/) for detailed installation instructions.

## Examples

```bash
# Development workflow
hwaro serve --drafts --verbose

# Development with HTTP access log
hwaro serve --access-log

# Development with auto browser refresh
hwaro serve --live-reload

# Production build
hwaro build

# Custom output directory
hwaro build -o dist

# Preview on specific port
hwaro serve -p 8000 --open

# Build a site in another directory
hwaro build -i ~/projects/my-blog

# Build a remote project and output to current directory
hwaro build -i ~/projects/my-blog -o ./output

# Incremental build (skip unchanged files)
hwaro build --cache

# Force full rebuild and repopulate cache
hwaro build --cache --full

# Streaming build for large sites
hwaro build --stream
hwaro build --memory-limit 512M

# Streaming build with env var
HWARO_MEMORYLIMIT=1G hwaro build

# Serve a site from another directory
hwaro serve -i ~/projects/my-blog --open
```

## Global Options

| Flag | Description |
|------|-------------|
| -h, --help | Show help |
| -v, --verbose | Verbose output |

## See Also

- [Configuration](/start/config/) — Config options that CLI flags override
- [Build Hooks](/features/build-hooks/) — Pre/post build commands
- [Tools & Completion](/start/tools/) — Utility subcommands

---

Title: Configuration
URL: https://hwaro.hahwul.com/start/config/
Source: content/start/config.md

All site configuration lives in `config.toml` at the project root.

## Site Settings

```toml
title = "My Site"
description = "Site description for SEO"
base_url = "https://example.com"
```

| Key | Type | Description |
|-----|------|-------------|
| title | string | Site title |
| description | string | Site description |
| base_url | string | Production URL (no trailing slash) |

## Environment Variables

You can reference environment variables in `config.toml`. Values are substituted before TOML parsing.

```toml
base_url = "${SITE_URL}"
title = "$SITE_TITLE"
description = "${SITE_DESC:-My awesome site}"
```

| Syntax | Description |
|--------|-------------|
| `${VAR}` | Substitute with env var value |
| `$VAR` | Same as above (bare form) |
| `${VAR:-default}` | Use `default` if `VAR` is unset or empty |

Missing variables without defaults are left as-is and produce a build warning. See [Environment Variables](/features/env-variables/) for template usage.

## Build Options

```toml
[build]
output_dir = "public"
drafts = false
parallel = true
cache = false
hooks.pre = ["npm install", "npx tsc"]
hooks.post = ["npm run minify"]
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| output_dir | string | "public" | Output directory |
| drafts | bool | false | Include draft content |
| parallel | bool | true | Parallel processing |
| cache | bool | false | Enable build caching |
| hooks.pre | array | [] | Commands to run before build |
| hooks.post | array | [] | Commands to run after build |

See [Build Hooks](/features/build-hooks/) for error handling and use cases.

## Markdown

```toml
[markdown]
safe = false
lazy_loading = true
emoji = true
footnotes = true
task_lists = true
definition_lists = true
mermaid = false
math = false
math_engine = "katex"
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| safe | bool | false | Strip raw HTML from markdown |
| lazy_loading | bool | false | Automatically add `loading="lazy"` to images |
| emoji | bool | false | Convert emoji shortcodes (e.g. `:smile:`) to emoji characters |
| footnotes | bool | true | Enable footnote syntax (`[^1]`) |
| task_lists | bool | true | Enable task list syntax (`- [ ]` / `- [x]`) |
| definition_lists | bool | true | Enable definition list syntax (`Term\n: Definition`) |
| mermaid | bool | false | Render ` ```mermaid ` blocks as `<div class="mermaid">` |
| math | bool | false | Enable math syntax (`$...$` and `$$...$$`) |
| math_engine | string | "katex" | Math rendering engine (`"katex"` or `"mathjax"`) |

See [Markdown Extensions](/features/markdown-extensions/) for syntax details and examples.

## Permalinks

Rewrite content directory paths to custom URL paths. Useful for site restructuring without breaking links.

```toml
[permalinks]
"old/posts" = "posts"
"2023/drafts" = "archive/2023"
```

| Source (Directory) | Target (URL Path) | Example Effect |
|-------------------|-------------------|----------------|
| `content/old/posts/a.md` | `posts/` | `/old/posts/a/` -> `/posts/a/` |

## Taxonomies

```toml
[[taxonomies]]
name = "tags"
feed = true
paginate = 10

[[taxonomies]]
name = "categories"
feed = true
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| name | string | — | Taxonomy name (used in front matter) |
| feed | bool | false | Generate RSS feed for each term |
| sitemap | bool | true | Include taxonomy pages in sitemap |
| paginate | int | — | Pages per pagination page |

## Feature Configuration Reference

Each feature has its own documentation with full configuration details. Below is a quick reference of all `config.toml` sections.

| Config Section | Documentation | Description |
|----------------|---------------|-------------|
| `[feeds]` | [SEO](/features/seo/) | RSS/Atom feed generation |
| `[sitemap]` | [SEO](/features/seo/) | Sitemap XML generation |
| `[robots]` | [SEO](/features/seo/) | Robots.txt generation |
| `[og]` | [SEO](/features/seo/) | OpenGraph & Twitter Card meta tags |
| `[og.auto_image]` | [Auto OG Images](/features/og-images/) | Auto-generate OG preview images |
| `[search]` | [Search](/features/search/) | Client-side search index |
| `[highlight]` | [Syntax Highlighting](/features/syntax-highlighting/) | Code syntax highlighting |
| `[pagination]` | [Pagination](/features/pagination/) | Section pagination |
| `[auto_includes]` | [Auto Includes](/features/auto-includes/) | Auto-include CSS/JS files |
| `[assets]` | [Asset Pipeline](/features/asset-pipeline/) | CSS/JS minification & fingerprinting |
| `[image_processing]` | [Image Processing](/features/image-processing/) | Image resizing & LQIP |
| `[image_processing.lqip]` | [Image Processing](/features/image-processing/#lqip-low-quality-image-placeholders) | Base64 blur-up placeholders |
| `[content.files]` | [Content Files](/features/content-files/) | Publish non-Markdown files |
| `[series]` | [Series](/features/series/) | Group posts into ordered series |
| `[related]` | [Related Posts](/features/related-posts/) | Related content recommendations |
| `[llms]` | [LLMs.txt](/features/llms-txt/) | AI/LLM crawler instructions |
| `[pwa]` | [PWA](/features/pwa/) | Progressive Web App support |
| `[amp]` | [AMP](/features/amp/) | Accelerated Mobile Pages |
| `[deployment]` | [Deploy](/deploy/) | Deploy targets configuration |
| `languages.*` | [Multilingual](/features/multilingual/) | Multi-language support |

## Plugins

```toml
[plugins]
processors = ["markdown"]
```

## Full Example

A complete `config.toml` with all core sections. Copy and adjust to your needs.

```toml
title = "My Blog"
description = "A blog about programming"
base_url = "https://myblog.com"
default_language = "en"

[build]
output_dir = "public"
drafts = false
parallel = true
cache = false
hooks.pre = ["npm ci"]
hooks.post = ["npm run optimize"]

[markdown]
safe = false
lazy_loading = true
emoji = false
footnotes = true
task_lists = true

[permalinks]
"old/posts" = "posts"

[plugins]
processors = ["markdown"]

[[taxonomies]]
name = "tags"
feed = true

[[taxonomies]]
name = "categories"

# Feature sections — see Feature Configuration Reference above
# [feeds], [sitemap], [robots], [og], [search], [highlight],
# [pagination], [auto_includes], [assets], [image_processing],
# [series], [related], [llms], [pwa], [amp], [deployment], etc.
```

## See Also

- [CLI](/start/cli/) — Command-line options that override config
- [Environment-Specific Config](/features/env-config/) — Per-environment overrides (`config.production.toml`)

---

Title: First Site
URL: https://hwaro.hahwul.com/start/first-site/
Source: content/start/first-site.md

Create your first Hwaro site in 5 minutes.

## 1. Create Project

```bash
hwaro init my-site --scaffold blog
cd my-site
```

Built-in scaffolds:

| Scaffold | Description |
|----------|-------------|
| `simple` | Landing pages, small sites (default) |
| `bare` | Minimal structure with semantic HTML only |
| `blog` | Posts with tags and categories |
| `blog-dark` | Blog with dark theme |
| `docs` | Documentation with sidebar |
| `docs-dark` | Documentation with dark theme |

## 2. Start Development Server

```bash
hwaro serve
```

Open `http://localhost:3000`. Changes reload automatically.

## 3. Project Structure

```
my-site/
├── config.toml      # Site configuration
├── content/         # Markdown content
│   ├── index.md     # Homepage
│   └── blog/        # Blog section
│       ├── _index.md
│       └── hello.md
├── templates/       # Jinja2 templates
├── static/          # Static files (CSS, JS, images)
└── public/          # Generated output
```

## 4. Edit Configuration

Open `config.toml`:

```toml
title = "My Site"
description = "A site built with Hwaro"
base_url = "https://example.com"
```

## 5. Create a Page

```bash
hwaro new content/about.md
```

Edit `content/about.md`:

```markdown
+++
title = "About"
+++

Welcome to my site!
```

Visit `http://localhost:3000/about/`.

## 6. Create a Section

Sections group related content. Create a blog section:

```bash
mkdir -p content/blog
```

Create `content/blog/_index.md`:

```markdown
+++
title = "Blog"
sort_by = "date"
+++

My blog posts.
```

Create `content/blog/first-post.md`:

```markdown
+++
title = "My First Post"
date = "2024-01-15"
tags = ["hello"]
+++

Hello, world!
```

Visit `http://localhost:3000/blog/`.

## 7. Build for Production

```bash
hwaro build
```

Deploy the `public/` directory to any static host. See [Deploy to GitHub Pages](/deploy/github-pages/) for a quick setup.

## Next Steps

- [CLI Commands](/start/cli/) — All available commands
- [Configuration](/start/config/) — Full config reference
- [Writing Content](/writing/) — Pages, sections, taxonomies
- [Deploy](/deploy/) — Hosting and deployment guides

---

Title: Installation
URL: https://hwaro.hahwul.com/start/installation/
Source: content/start/installation.md

Hwaro is written in Crystal. You can install it from source or use a pre-built binary.

## Homebrew

```bash
brew tap hwaro/hwaro
brew install hwaro
```

## Snapcraft

```bash
sudo snap install hwaro
```

## Pre-built Binary

Pre-built binaries for macOS and Linux are available on the [GitHub Releases](https://github.com/hahwul/hwaro/releases) page.

1. Download the archive for your platform from the [latest release](https://github.com/hahwul/hwaro/releases/latest).
2. Extract the archive and move the binary to a directory in your PATH.

```bash
# Example for Linux (amd64)
tar -xzf hwaro-linux-amd64.tar.gz
sudo mv hwaro /usr/local/bin/
```

## From Source

### Prerequisites

- [Crystal](https://crystal-lang.org/install/) 1.19+
- Git

### Build

```bash
git clone https://github.com/hahwul/hwaro
cd hwaro
shards install
shards build --release
```

The binary is created at `./bin/hwaro`.

### Add to PATH (Optional)

```bash
# Copy to a directory in your PATH
sudo cp ./bin/hwaro /usr/local/bin/

# Or add the bin directory to PATH
export PATH="$PATH:$(pwd)/bin"
```

## Verify Installation

```bash
hwaro --version
```

## Next Steps

- [Create your first site →](/start/first-site/)

---

Title: Tools & Completion
URL: https://hwaro.hahwul.com/start/tools/
Source: content/start/tools/_index.md

Hwaro includes utility tools for content management and shell completion scripts for a better CLI experience.

## Tool Commands

The `hwaro tool` command provides utility subcommands for working with content files.

| Subcommand | Description |
|------------|-------------|
| [convert](/start/tools/convert/) | Convert frontmatter between YAML and TOML formats |
| [list](/start/tools/list/) | List content files by status |
| [check-links](/start/tools/check-links/) | Check for dead links in content files |
| [doctor](/start/tools/doctor/) | Diagnose config and content issues |
| [platform](/start/tools/platform/) | Generate hosting platform config files |
| [ci](/start/tools/ci/) | Generate CI/CD workflow files |
| [agents-md](/start/tools/agents-md/) | Generate or update AGENTS.md file |

---

## Shell Completion

Hwaro can generate completion scripts for your shell, providing tab completion for commands, subcommands, and flags.

### Supported Shells

| Shell | Command |
|-------|---------|
| Bash | `hwaro completion bash` |
| Zsh | `hwaro completion zsh` |
| Fish | `hwaro completion fish` |

### Installation

#### Bash

Add to your `~/.bashrc`:

```bash
eval "$(hwaro completion bash)"
```

Or save to a file:

```bash
hwaro completion bash > /etc/bash_completion.d/hwaro
```

#### Zsh

Add to your `~/.zshrc`:

```bash
eval "$(hwaro completion zsh)"
```

Or save to your fpath:

```bash
hwaro completion zsh > ~/.zsh/completions/_hwaro
```

#### Fish

Add to your `~/.config/fish/config.fish`:

```fish
hwaro completion fish | source
```

Or save to the completions directory:

```bash
hwaro completion fish > ~/.config/fish/completions/hwaro.fish
```

### What Gets Completed

The completion scripts provide tab completion for:

- **Commands**: `hwaro <TAB>` → `init`, `build`, `serve`, `new`, `deploy`, `tool`, `completion`
- **Subcommands**: `hwaro tool <TAB>` → `convert`, `list`, `check-links`, `agents-md`
- **Flags**: `hwaro build <TAB>` → `--output`, `--drafts`, `--minify`, etc.
- **Positional arguments**: `hwaro completion <TAB>` → `bash`, `zsh`, `fish`
- **Positional choices**: `hwaro tool convert <TAB>` → `to-yaml`, `to-toml`

### Automatic Updates

Completion scripts are generated dynamically from command metadata. When you update Hwaro to a new version with new commands or flags, regenerating the completion script will automatically include them.

```bash
# Regenerate after updating hwaro
eval "$(hwaro completion bash)"
```

## See Also

- [CLI](/start/cli/) — Full CLI command reference
- [Configuration](/start/config/) — Site configuration
- [Build Hooks](/features/build-hooks/) — Custom build commands

---

Title: agents-md
URL: https://hwaro.hahwul.com/start/tools/agents-md/
Source: content/start/tools/agents-md.md

Generate or update the AGENTS.md file for AI agent instructions. Useful for updating existing projects to the latest AGENTS.md or switching between content modes.

```bash
# Print local (full embedded) version to stdout
hwaro tool agents-md

# Print remote (lightweight) version to stdout
hwaro tool agents-md --remote

# Write to AGENTS.md file
hwaro tool agents-md --write

# Write remote version to file
hwaro tool agents-md --remote --write

# Overwrite without confirmation
hwaro tool agents-md --write --force
```

## Content Modes

| Mode | Description |
|------|-------------|
| `--local` (default) | Full embedded reference (~260 lines). Includes content format, template variables, configuration reference, and AI agent notes. Best for offline or local LLM environments. |
| `--remote` | Lightweight version (~50 lines). Includes project structure, essential commands, and AI agent notes with links to [online documentation](https://hwaro.hahwul.com) and [LLM reference](https://hwaro.hahwul.com/llms-full.txt). |

Both modes include a **Site-Specific Instructions** section where you can add your own project rules and conventions.

## Options

| Flag | Description |
|------|-------------|
| --remote | Generate lightweight version with links to online docs |
| --local | Generate full embedded reference (default) |
| --write | Write to AGENTS.md file instead of stdout |
| -f, --force | Overwrite existing file without confirmation |
| -h, --help | Show help |

By default, the command prints to stdout so you can inspect the content before saving. Use `--write` to save to file. If `AGENTS.md` already exists, you'll be prompted for confirmation unless `--force` is used.

## Relation to `hwaro init`

When creating a new project, `hwaro init` also generates an AGENTS.md file. You can control the content mode with the `--agents` flag:

```bash
hwaro init my-site                  # default: remote (lightweight)
hwaro init my-site --agents local   # full embedded reference
hwaro init my-site --skip-agents-md # skip AGENTS.md entirely
```

## See Also

- [CLI Reference](/start/cli/#init) — Init command options
- [CLI Reference](/start/cli/#tool) — All tool commands

---

Title: ci (deprecated)
URL: https://hwaro.hahwul.com/start/tools/ci/
Source: content/start/tools/ci.md

> **Deprecated:** `hwaro tool ci` has been merged into `hwaro tool platform`. Use `hwaro tool platform github-pages` instead.

```bash
# Old (deprecated)
hwaro tool ci github-actions

# New
hwaro tool platform github-pages
```

See [platform](/start/tools/platform/) for full documentation.

---

Title: convert
URL: https://hwaro.hahwul.com/start/tools/convert/
Source: content/start/tools/convert.md

Convert frontmatter between YAML and TOML formats across your content files.

```bash
# Convert all frontmatter to YAML
hwaro tool convert to-yaml

# Convert all frontmatter to TOML
hwaro tool convert to-toml

# Convert only in a specific directory
hwaro tool convert to-yaml -c posts

# Output result as JSON
hwaro tool convert to-yaml --json
```

## Options

| Flag | Description |
|------|-------------|
| -c, --content DIR | Limit conversion to a specific content directory |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

## JSON Output

```json
{
  "success": true,
  "message": "Converted 5 files to YAML",
  "converted_count": 5,
  "skipped_count": 2,
  "error_count": 0
}
```

## Example

Before:

```markdown
+++
title = "My Post"
date = "2024-01-15"
tags = ["crystal", "tutorial"]
+++

Content here.
```

After `hwaro tool convert to-yaml`:

```markdown
---
title: "My Post"
date: "2024-01-15"
tags:
  - crystal
  - tutorial
---

Content here.
```

---

Title: check-links
URL: https://hwaro.hahwul.com/start/tools/deadlink/
Source: content/start/tools/deadlink.md

Check for broken external and internal links in your content files.

```bash
hwaro tool check-links

# Output result as JSON
hwaro tool check-links --json

# Custom timeout and concurrency
hwaro tool check-links --timeout 30 --concurrency 4

# Check only external or internal links
hwaro tool check-links --external-only
hwaro tool check-links --internal-only
```

## Options

| Flag | Description |
|------|-------------|
| -c, --content-dir DIR | Content directory (default: `content`) |
| --timeout SECONDS | HTTP request timeout in seconds (default: 10) |
| --concurrency N | Max concurrent requests (default: 8) |
| --external-only | Check external links only |
| --internal-only | Check internal links only |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

## How It Works

1. Scans all Markdown files in the `content/` directory
2. Finds external URLs (http/https links) and internal links (relative/absolute paths)
3. Sends concurrent HEAD requests to external URLs
4. Verifies internal link targets exist on disk (checks `.md`, `_index.md`, `index.md`)
5. Reports broken or unreachable links

## Link Types

| Type | Description |
|------|-------------|
| External | `http://` and `https://` links — checked via HTTP HEAD |
| Internal | Relative and absolute path links — checked on filesystem |
| Images | `![alt](path)` image references — checked on filesystem |

## Example Output

```
Starting dead link check in 'content'...
----------------------------------------
✘ Found 3 dead links (out of 50 total):
[DEAD] content/blog/post.md
  └─ URL: https://old-site.com/page
  └─ Status: 404
[DEAD] content/blog/post.md
  └─ URL: ../missing-page (internal)
  └─ Internal link target not found
[DEAD] content/about.md
  └─ URL: /images/photo.png (internal)
  └─ Image not found
----------------------------------------
```

## JSON Output

```json
{
  "dead_links": [
    {
      "link": {
        "file": "content/blog/post.md",
        "url": "https://old-site.com/page",
        "kind": "external"
      },
      "status": 404,
      "error": null
    },
    {
      "link": {
        "file": "content/about.md",
        "url": "/images/photo.png",
        "kind": "image"
      },
      "status": -1,
      "error": "Image not found"
    }
  ],
  "total_links": 50,
  "external_links": 30,
  "internal_links": 20,
  "dead_link_count": 2
}
```

---

Title: doctor
URL: https://hwaro.hahwul.com/start/tools/doctor/
Source: content/start/tools/doctor.md

Diagnose configuration and content issues in your Hwaro site.

```bash
hwaro doctor

# Check only a specific content directory
hwaro doctor -c posts

# Auto-fix: add missing config sections
hwaro doctor --fix

# Auto-fix with minimal sections (skip pwa, amp, assets, etc.)
hwaro doctor --fix --minimal

# Output result as JSON
hwaro doctor --json
```

> `hwaro tool doctor` also works as a backward-compatible alias.

## Options

| Flag | Description |
|------|-------------|
| -c, --content DIR | Content directory to check |
| --fix | Auto-fix issues (add missing config sections) |
| --minimal | With `--fix`, skip advanced optional sections (pwa, amp, assets, deployment, image_processing, etc.) |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

## What It Checks

**Config diagnostics:**

- `base_url` is not set
- `base_url` doesn't start with `http://` or `https://`
- `base_url` has a trailing slash
- `title` is still the default value
- `feeds.enabled` is true but `feeds.filename` is empty
- `sitemap.changefreq` has an invalid value
- `sitemap.priority` is out of range (0.0–1.0)
- Duplicate taxonomy names
- Duplicate language codes
- Invalid `search.format` value

**Template diagnostics:**

- Templates directory not found
- Required templates missing (`page.html`, `section.html`)
- Unclosed block tags (`if`, `for`, `block`, `macro` without matching `end`)
- Mismatched `{{ }}` variable tags

**Content diagnostics:**

- Missing `title` in frontmatter
- Missing `description` in frontmatter
- Images without alt text (`![](url)`)
- Broken internal links (`@/` prefixed paths that don't resolve)
- Frontmatter parse errors (TOML/YAML)
- Draft files (reported as info)

**Structure diagnostics:**

- Section directories missing `_index.md`

## Example Output

```
Running diagnostics...

Config:
  ⚠ config.toml: base_url is not set
  ⚠ config.toml: feeds.enabled is true but feeds.filename is not set

Content:
  ⚠ content/blog/draft.md: Missing description in frontmatter
  ℹ content/blog/draft.md: File is marked as draft
  ⚠ content/about.md: Image missing alt text: ![](photo.jpg)

Found 0 error(s), 3 warning(s), 1 info(s)
```

## JSON Output

```json
{
  "issues": [
    {
      "level": "warning",
      "category": "config",
      "file": "config.toml",
      "message": "base_url is not set"
    },
    {
      "level": "warning",
      "category": "content",
      "file": "content/blog/draft.md",
      "message": "Missing description in frontmatter"
    },
    {
      "level": "info",
      "category": "content",
      "file": "content/blog/draft.md",
      "message": "File is marked as draft"
    }
  ],
  "summary": {
    "errors": 0,
    "warnings": 2,
    "infos": 1,
    "total": 3
  }
}
```

---

Title: list
URL: https://hwaro.hahwul.com/start/tools/list/
Source: content/start/tools/list.md

List content files filtered by status.

```bash
# List all content files
hwaro tool list all

# List only draft files
hwaro tool list drafts

# List only published files
hwaro tool list published

# List files in a specific directory
hwaro tool list all -c posts

# Output result as JSON
hwaro tool list all --json
```

## Options

| Flag | Description |
|------|-------------|
| -c, --content DIR | Limit listing to a specific content directory |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

## Filters

| Filter | Description |
|--------|-------------|
| all | Show all content files |
| drafts | Show only files with `draft = true` |
| published | Show only files with `draft = false` or no draft field |

## JSON Output

```json
[
  {
    "path": "content/blog/my-post.md",
    "title": "My Post",
    "draft": false,
    "date": "2024-06-15T00:00:00+00:00"
  },
  {
    "path": "content/blog/draft-post.md",
    "title": "Draft Post",
    "draft": true,
    "date": "2024-06-10T00:00:00+00:00"
  }
]
```

---

Title: platform
URL: https://hwaro.hahwul.com/start/tools/platform/
Source: content/start/tools/platform.md

Generate platform configuration and CI/CD workflow files for popular providers. Reads your `config.toml` and content aliases to produce ready-to-use deploy configs.

```bash
# Hosting platforms
hwaro tool platform netlify
hwaro tool platform vercel
hwaro tool platform cloudflare

# CI/CD workflows
hwaro tool platform github-pages
hwaro tool platform gitlab-ci

# Output to custom path
hwaro tool platform netlify -o deploy/netlify.toml

# Print to stdout instead of writing file
hwaro tool platform vercel --stdout
```

> **Note:** `hwaro tool ci` is deprecated. Use `hwaro tool platform github-pages` instead.

## Supported Platforms

| Platform | Output File | Description |
|----------|-------------|-------------|
| netlify | `netlify.toml` | Build settings, redirects, headers |
| vercel | `vercel.json` | Build command, routing, cache headers |
| cloudflare | `wrangler.toml` | Workers/Pages site config |
| github-pages | `.github/workflows/deploy.yml` | GitHub Actions build + deploy workflow |
| gitlab-ci | `.gitlab-ci.yml` | GitLab CI/CD pipeline |

## Options

| Flag | Description |
|------|-------------|
| -o, --output PATH | Output file path (default: auto-detected) |
| --stdout | Print to stdout instead of writing file |
| -f, --force | Overwrite existing file without warning |
| -h, --help | Show help |

If the output file already exists, use `--force` to overwrite.

## Generated Config

Each config includes:

- **Build command**: `hwaro build`
- **Output directory**: `public/`
- **Redirects**: 301 redirects from page [`aliases`](/writing/pages/) defined in frontmatter (e.g., `aliases: ["/old-url/"]`)
- **Cache headers**: Long-lived caching for static assets

### Netlify Output

```toml
[build]
  command = "hwaro build"
  publish = "public"

[build.environment]
  # Add environment variables here

[[redirects]]
  from = "/old-url/"
  to = "/posts/new-post/"
  status = 301

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"
```

### Vercel Output

```json
{
  "buildCommand": "hwaro build",
  "outputDirectory": "public",
  "redirects": [
    {
      "source": "/old-url/",
      "destination": "/posts/new-post/",
      "statusCode": 301
    }
  ],
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}
```

## See Also

- [GitHub Pages](/deploy/github-pages/) | [GitLab CI](/deploy/gitlab-ci/) | [Netlify](/deploy/netlify/) | [Vercel](/deploy/vercel/) | [Cloudflare Pages](/deploy/cloudflare-pages/) — Platform deploy guides
- [CLI Reference](/start/cli/#tool) — All tool commands

---

Title: Templates
URL: https://hwaro.hahwul.com/templates/
Source: content/templates/_index.md

Templates define how content becomes HTML. Hwaro uses Crinja, a Jinja2-compatible engine.

## Template Directory

```
templates/
├── base.html           # Base layout
├── page.html           # Regular pages
├── section.html        # Section index pages
├── index.html          # Homepage (optional)
├── taxonomy.html       # Taxonomy listing
├── taxonomy_term.html  # Taxonomy term page
├── 404.html            # Error page
└── shortcodes/         # Shortcode templates
```

The `shortcodes/` directory contains reusable components you can embed in Markdown. See [Writing: Shortcodes](/writing/shortcodes/) for usage and how to create custom shortcodes.

## Template Selection

| Content | Template |
|---------|----------|
| content/index.md | index.html or page.html |
| content/about.md | page.html |
| content/blog/_index.md | section.html |
| content/blog/post.md | page.html |
| Taxonomy index | taxonomy.html |
| Taxonomy term | taxonomy_term.html |

## Quick Example

```jinja
{% extends "base.html" %}

{% block content %}
<article>
  <h1>{{ page.title }}</h1>
  <time>{{ page.date }}</time>
  {{ content | safe }}
</article>
{% endblock %}
```

---

Title: Data Model
URL: https://hwaro.hahwul.com/templates/data-model/
Source: content/templates/data-model.md

Hwaro's template system centers on three core types: **Site**, **Section**, and **Page**. This page is a **template-side reference** — all properties and variables you can use when building templates. For how to write content and set front matter fields, see [Writing](/writing/).

## Hierarchy

```
Site
├── Config (title, base_url, ...)
├── Pages[] (standalone pages)
├── Sections[]
│   ├── Pages[] (pages in section)
│   └── Subsections[]
│       ├── Pages[]
│       └── Subsections[] (recursive)
└── Taxonomies{}
    └── Terms{}
        └── Pages[]
```

### Relationships

- A **Site** contains multiple **Sections** and standalone **Pages**
- A **Section** contains **Pages** and child **Subsections**
- **Subsections** can nest indefinitely
- **Taxonomies** group **Pages** by terms

## Site

The root container. Configured in `config.toml`.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| site.title | String | Site title |
| site.description | String | Site description |
| site.base_url | String | Base URL (no trailing slash) |
| site.pages | Array<Page> | All non-section pages |
| site.sections | Array<Section> | All section index pages |
| site.taxonomies | Object | All taxonomy groups and terms |
| site.data | Object | Data loaded from `data/` directory |
| site.authors | Object | Aggregated author data |

### Flat Aliases

| Variable | Equivalent |
|----------|------------|
| site_title | site.title |
| site_description | site.description |
| base_url | site.base_url |

### Data Directory

Hwaro allows you to store auxiliary data in the `data/` directory. Files ending in `.yml`, `.yaml`, `.json`, or `.toml` are automatically loaded and exposed via `site.data`.

#### File Structure

```text
data/
├── authors.yml
├── products.json
└── config.toml
```

#### Accessing Data

Data is accessed by the filename (without extension).

For example, `data/products.json`:

```json
[
  {"name": "Widget", "price": 10},
  {"name": "Gadget", "price": 20}
]
```

Can be accessed in templates:

```jinja
{% for product in site.data.products %}
  <h2>{{ product.name }}</h2>
  <p>{{ product.price }}</p>
{% endfor %}
```

### Site Authors

Hwaro automatically aggregates all authors defined in the `authors` front matter field (`authors = ["id"]`) into `site.authors`.

#### Defining Authors

You can enrich author data by creating a `data/authors.yml` (or `.json`, `.toml`) file. Keys must match the author IDs used in the page front matter.

**content/my-post.md**

```yaml
---
title: "My Post"
authors: ["john-doe"]
---
```

**data/authors.yml**

```yaml
john-doe:
  name: "John Doe"
  bio: "Creator of things."
  avatar: "/images/john.jpg"
```

#### Usage in Templates

The `site.authors` object contains all authors found on the site. Each author object has:
- `key`: The author ID (e.g., "john-doe")
- `name`: The author name (from data or ID fallback)
- `pages`: List of pages by this author (sorted by date)
- Any custom fields from `data/authors.yml`

```jinja
{% for id, author in site.authors %}
  <div class="author">
    <img src="{{ author.avatar }}" alt="{{ author.name }}">
    <h3>{{ author.name }}</h3>
    <p>{{ author.bio }}</p>

    <h4>Recent Posts</h4>
    <ul>
    {% for p in author.pages %}
      <li><a href="{{ p.url }}">{{ p.title }}</a></li>
    {% endfor %}
    </ul>
  </div>
{% endfor %}
```

### Example

```jinja
<title>{{ site.title }}</title>
<link rel="canonical" href="{{ site.base_url }}{{ page.url }}">
```

---

## Section

A directory with `_index.md` that groups related content.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| section.title | String | Section title |
| section.description | String? | Section description |
| section.pages | Array<Page> | Pages in this section |
| section.pages_count | Int | Number of pages |
| section.list | String | Pre-rendered HTML list (`section_list`) |
| section.subsections | Array<Section> | Child sections |
| section.assets | Array<String> | Static files in section |
| section.page_template | String? | Default template for pages |
| section.paginate_path | String | Pagination URL pattern |
| section.redirect_to | String? | Redirect URL |

For the current section URL in `section.html`, use `page.url`.

### Flat Aliases

| Variable | Equivalent |
|----------|------------|
| section_title | section.title |
| section_description | section.description |
| section_list | Pre-rendered HTML list of pages |

### From Front Matter

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| sort_by | String? | "date" | Sort by: date, weight, title |
| reverse | Bool? | false | Reverse sort order |
| paginate | Int? | — | Pages per page |
| transparent | Bool | false | Pass pages to parent |
| generate_feeds | Bool | false | Generate RSS feed |

### Iterating Pages

```jinja
{% for p in section.pages %}
<article>
  <h2><a href="{{ p.url }}">{{ p.title }}</a></h2>
  <time>{{ p.date }}</time>
  {% if p.description %}
  <p>{{ p.description }}</p>
  {% endif %}
</article>
{% endfor %}
```

### Iterating Subsections

```jinja
{% for sub in section.subsections %}
<div class="category">
  <a href="{{ sub.url }}">{{ sub.title }}</a>
  <span>({{ sub.pages_count }} articles)</span>
</div>
{% endfor %}
```

### Using section_list

For simple listings, use the pre-rendered HTML:

```jinja
<ul>{{ section_list | safe }}</ul>
```

For custom markup, iterate `section.pages` directly:

```jinja
<ul>
{% for p in section.pages %}
  <li>
    <a href="{{ p.url }}">{{ p.title }}</a>
    {% if p.date %}<time>{{ p.date }}</time>{% endif %}
  </li>
{% endfor %}
</ul>
```

---

## Page

An individual content file (`.md`).

### Core Properties

| Property | Type | Description |
|----------|------|-------------|
| page.title | String | Page title |
| page.description | String? | Page description |
| page.url | String | Relative URL path |
| page.permalink | String? | Absolute URL with base_url |
| page.section | String | Parent section name |
| page.date | String? | Publication date (YYYY-MM-DD) |
| page.updated | String? | Last updated date |
| page.language | String | Effective language code |
| page.translations | Array<TranslationLink> | Language variants |

Rendered HTML content is available as the top-level `content` variable.

### Metadata Properties

| Property | Type | Description |
|----------|------|-------------|
| page.draft | Bool | Is draft |
| page.weight | Int | Sort weight |
| page.image | String? | Featured image path |
| page.authors | Array<String> | Author names |
| page.extra | Object | Custom front matter fields |

### Computed Properties

| Property | Type | Description |
|----------|------|-------------|
| page.word_count | Int | Word count |
| page.reading_time | Int | Reading time (minutes) |
| page.summary | String? | Content before <!-- more --> |
| page.assets | Array<String> | Static files in page bundle |

### Boolean Flags

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| page.toc | Bool | false | Show table of contents |
| page.render | Bool | true | Should render |
| page.is_index | Bool | — | Is index file |
| page.generated | Bool | false | Auto-generated page |
| page.in_sitemap | Bool | true | Include in sitemap |
| page.in_search_index | Bool | true | Include in search |

### Navigation Properties

| Property | Type | Description |
|----------|------|-------------|
| page.lower | Page? | Previous page in section |
| page.higher | Page? | Next page in section |
| page.ancestors | Array<Page> | Parent section chain |
| page.translations | Array<TranslationLink> | Language variants |

### Custom Metadata

| Property | Type | Description |
|----------|------|-------------|
| page.extra | Object | Custom front matter fields |

### Flat Aliases

| Variable | Equivalent |
|----------|------------|
| page_title | page.title |
| page_description | page.description |
| page_url | page.url |
| page_section | page.section |
| page_date | page.date |
| page_image | page.image |
| page_summary | page.summary |
| page_word_count | page.word_count |
| page_reading_time | page.reading_time |
| page_permalink | page.permalink |
| page_authors | page.authors |
| page_weight | page.weight |
| page_language | page.language |
| page_translations | page.translations |
| taxonomy_name | Current taxonomy name (taxonomy pages) |
| taxonomy_term | Current taxonomy term (taxonomy term pages) |
| content | Rendered HTML content |

---

## Navigation Objects

### page.lower / page.higher

| Property | Type | Description |
|----------|------|-------------|
| .title | String | Page title |
| .url | String | Page URL |
| .description | String? | Page description |
| .date | String? | Page date |

```jinja
<nav class="post-nav">
  {% if page.lower %}
  <a href="{{ page.lower.url }}">← {{ page.lower.title }}</a>
  {% endif %}
  
  {% if page.higher %}
  <a href="{{ page.higher.url }}">{{ page.higher.title }} →</a>
  {% endif %}
</nav>
```

### page.ancestors

Parent sections for breadcrumbs:

```jinja
<nav class="breadcrumbs">
  <a href="/">Home</a>
  {% for ancestor in page.ancestors %}
  / <a href="{{ ancestor.url }}">{{ ancestor.title }}</a>
  {% endfor %}
  / <span>{{ page.title }}</span>
</nav>
```

### page.translations

| Property | Type | Description |
|----------|------|-------------|
| .code | String | Language code (e.g., "en") |
| .url | String | Translated page URL |
| .title | String | Title in that language |
| .is_current | Bool | Current page's language |
| .is_default | Bool | Default language |

```jinja
{% if page.translations %}
<nav class="lang-switcher">
{% for t in page.translations %}
  {% if t.is_current %}
  <span>{{ t.code | upper }}</span>
  {% else %}
  <a href="{{ t.url }}">{{ t.code | upper }}</a>
  {% endif %}
{% endfor %}
</nav>
{% endif %}
```

---

## Accessing page.extra

Custom metadata from front matter:

```markdown
+++
title = "Review"

[extra]
rating = 4.5
featured = true
pros = ["Fast", "Reliable"]
+++
```

```jinja
{% if page.extra.featured %}
<span class="badge">Featured</span>
{% endif %}

<div class="rating">{{ page.extra.rating }} / 5</div>

<ul>
{% for pro in page.extra.pros %}
  <li>{{ pro }}</li>
{% endfor %}
</ul>
```

---

### Time Variables

| Variable | Type | Description |
|----------|------|-------------|
| current_year | Int | Current year (e.g., 2025) |
| current_date | String | Current date (YYYY-MM-DD) |
| current_datetime | String | Current datetime |

```jinja
<footer>&copy; {{ current_year }} {{ site.title }}</footer>
```

---

### SEO Variables

**Pre-rendered HTML** (backward compatible):

| Variable | Description |
|----------|-------------|
| og_tags | OpenGraph meta tags |
| twitter_tags | Twitter Card meta tags |
| og_all_tags | Both OG and Twitter tags |
| canonical_tag | Canonical link tag |
| hreflang_tags | Hreflang alternate link tags (multilingual) |
| pagination_seo_links | `<link rel="prev/next">` tags |

```jinja
<head>
  {{ og_all_tags | safe }}
  {{ canonical_tag | safe }}
  {{ hreflang_tags | safe }}
  {{ pagination_seo_links | safe }}
</head>
```

**Structured data** for custom meta tag markup:

| Property | Type | Description |
|----------|------|-------------|
| seo.canonical_url | String | Full canonical URL (base_url + page URL) |
| seo.og_type | String | OpenGraph type (default: "article") |
| seo.og_image | String | Resolved absolute image URL |
| seo.twitter_card | String | Twitter card type (default: "summary_large_image") |
| seo.twitter_site | String | Twitter site handle |
| seo.twitter_creator | String | Twitter creator handle |
| seo.fb_app_id | String | Facebook App ID |
| seo.hreflang | Array | Same as `page.translations` |

Page title, description, URL, and image are available as `page.title`, `page.description`, `page.url`, `page.image`. The `seo` object provides computed values specific to SEO (resolved URLs, config values).

```jinja
<head>
  <link rel="canonical" href="{{ seo.canonical_url }}">
  <meta property="og:title" content="{{ page.title }}">
  <meta property="og:type" content="{{ seo.og_type }}">
  <meta property="og:url" content="{{ seo.canonical_url }}">
  {% if page.description %}
  <meta property="og:description" content="{{ page.description }}">
  {% endif %}
  {% if seo.og_image %}
  <meta property="og:image" content="{{ seo.og_image }}">
  {% endif %}
  <meta name="twitter:card" content="{{ seo.twitter_card }}">
  {% if seo.twitter_site %}
  <meta name="twitter:site" content="{{ seo.twitter_site }}">
  {% endif %}
</head>
```

---

### Asset Variables

Pre-rendered `<link>` and `<script>` tags for convenience. These are generated from your `config.toml` settings.

| Variable | Description |
|----------|-------------|
| highlight_css | Syntax highlighting CSS `<link>` tag |
| highlight_js | Syntax highlighting JS `<script>` tag |
| highlight_tags | Both CSS and JS tags |
| auto_includes_css | Auto-included CSS `<link>` tags |
| auto_includes_js | Auto-included JS `<script>` tags |
| auto_includes | All auto-include tags |

```jinja
<head>
  {{ highlight_css | safe }}
  {{ auto_includes_css | safe }}
</head>
<body>
  ...
  {{ highlight_js | safe }}
  {{ auto_includes_js | safe }}
</body>
```

---

### Table of Contents

Only available when `toc = true` in front matter.

**Pre-rendered HTML** (backward compatible):

| Variable | Type | Description |
|----------|------|-------------|
| toc | String | Generated TOC HTML |
| toc_obj.html | String | Same TOC HTML in object form |

```jinja
{% if page.toc %}
<aside class="toc">
  {{ toc | safe }}
</aside>
{% endif %}
```

**Structured data** for custom TOC markup:

| Property | Type | Description |
|----------|------|-------------|
| toc_obj.headers | Array | Structured TOC header objects |
| toc_obj.headers[].level | Int | Heading level (2-6) |
| toc_obj.headers[].id | String | Anchor ID |
| toc_obj.headers[].title | String | Heading text |
| toc_obj.headers[].permalink | String | Full anchor permalink |
| toc_obj.headers[].children | Array | Nested child headers (same structure) |

```jinja
{% if page.toc %}
<nav class="toc">
  <ul>
  {% for h in toc_obj.headers %}
    <li>
      <a href="{{ h.permalink }}">{{ h.title }}</a>
      {% if h.children %}
      <ul>
        {% for child in h.children %}
        <li><a href="{{ child.permalink }}">{{ child.title }}</a></li>
        {% endfor %}
      </ul>
      {% endif %}
    </li>
  {% endfor %}
  </ul>
</nav>
{% endif %}
```

---

### Taxonomy Variables

Available in taxonomy templates:

| Variable | Type | Description |
|----------|------|-------------|
| taxonomy_name | String | Taxonomy name (e.g., "tags") |
| taxonomy_term | String | Current term name |
| taxonomy_terms | Array | All terms (in taxonomy.html) |
| taxonomy_pages | Array<Page> | Pages for term |

---

## Type Reference

### Quick Reference

| Type | Description |
|------|-------------|
| String | Text value |
| String? | Optional text (may be nil) |
| Int | Integer number |
| Bool | true/false |
| Array<T> | List of type T |
| Object | Key-value map |

### Template Checking

```jinja
{# Check for nil #}
{% if page.description %}...{% endif %}

{# Check for empty array #}
{% if page.authors %}...{% endif %}

{# Check for empty string #}
{% if page.description is present %}...{% endif %}

{# Default value #}
{{ page.description | default(value=site.description) }}
```

---

## See Also

- [Template Syntax](/templates/syntax/) — Jinja2 basics
- [Functions](/templates/functions/) — Data retrieval functions
- [Filters](/templates/filters/) — Value transformation

---

Title: Filters
URL: https://hwaro.hahwul.com/templates/filters/
Source: content/templates/filters.md

Filters transform values in templates. Apply with the pipe `|` operator.

## Syntax

```jinja
{{ value | filter }}
{{ value | filter(arg="value") }}
{{ value | filter1 | filter2 }}
```

## Text Filters

| Filter | Description | Example |
|--------|-------------|---------|
| upper | Uppercase | {{ "hello" \| upper }} → HELLO |
| lower | Lowercase | {{ "HELLO" \| lower }} → hello |
| capitalize | Capitalize first | {{ "hello" \| capitalize }} → Hello |
| trim | Remove whitespace | {{ "  hi  " \| trim }} → hi |
| replace | Replace text | {{ "hello" \| replace("l", "x") }} → hexxo |
| slugify | URL slug | {{ "Hello World" \| slugify }} → hello-world |
| truncate_words | Limit words | {{ text \| truncate_words(20) }} |

## HTML Filters

| Filter | Description | Example |
|--------|-------------|---------|
| safe | Don't escape HTML | {{ content \| safe }} |
| strip_html | Remove HTML tags | {{ html \| strip_html }} |
| markdownify | Render Markdown | {{ text \| markdownify }} |
| xml_escape | XML escape | {{ text \| xml_escape }} |

## Array Filters

| Filter | Description | Example |
|--------|-------------|---------|
| length | Get length | {{ items \| length }} |
| first | First element | {{ items \| first }} |
| last | Last element | {{ items \| last }} |
| reverse | Reverse order | {{ items \| reverse }} |
| sort | Sort array | {{ items \| sort }} |
| join | Join elements | {{ tags \| join(", ") }} |
| split | Split string | {{ "a,b,c" \| split(pat=",") }} |
| where | Filter objects by field value | {{ posts \| where(attribute="draft", value=false) }} |
| sort_by | Sort objects by field | {{ posts \| sort_by(attribute="date", reverse=true) }} |
| group_by | Group objects by field | {{ posts \| group_by(attribute="section") }} |

## Collection Filters

| Filter | Description | Example |
|--------|-------------|---------|
| unique | Remove duplicates | {{ items \| unique }} |
| flatten | Flatten nested arrays | {{ nested \| flatten }} |
| compact | Remove nil/empty values | {{ items \| compact }} |

## Math Filters

| Filter | Description | Example |
|--------|-------------|---------|
| ceil | Round up to integer | {{ 3.2 \| ceil }} → 4 |
| floor | Round down to integer | {{ 3.8 \| floor }} → 3 |

## i18n Filters

| Filter | Description | Example |
|--------|-------------|---------|
| t | Translate a key | {{ "nav.home" \| t }} |
| pluralize | Select singular/plural form | {{ count \| pluralize(singular="item", plural="items") }} |

The `t` filter looks up translation keys from TOML files in the `i18n/` directory. It uses the current page's language and falls back to the default language, then returns the key itself if no translation is found. See [Multilingual](/features/multilingual/) for i18n file setup.

## Debug Filters

| Filter | Description | Example |
|--------|-------------|---------|
| inspect | Debug representation | {{ value \| inspect }} |

## URL Filters

| Filter | Description | Example |
|--------|-------------|---------|
| absolute_url | Full URL with base | {{ "/about/" \| absolute_url }} |
| relative_url | Prefix base_url | {{ "/img.png" \| relative_url }} |

## Data Filters

| Filter | Description | Example |
|--------|-------------|---------|
| default | Fallback value | {{ value \| default(value="N/A") }} |
| jsonify | JSON encode | {{ data \| jsonify }} |
| date | Format date | {{ page.date \| date("%Y-%m-%d") }} |

## Examples

### Safe HTML

Always use `safe` for rendered content:

```jinja
{{ content | safe }}
{{ og_tags | safe }}
{{ toc | safe }}
```

### Default Values

```jinja
{{ page.description | default(value=site.description) }}
{{ page.image | default(value="/images/default.png") }}
```

### Date Formatting

```jinja
<time>{{ page.date | date("%B %d, %Y") }}</time>
```

Format codes:
- `%Y` — Year (2024)
- `%m` — Month (01-12)
- `%d` — Day (01-31)
- `%B` — Month name (January)
- `%b` — Month abbr (Jan)

### URL Handling

```jinja
<a href="{{ page.url | absolute_url }}">Permalink</a>
<img src="{{ "/logo.png" | relative_url }}">
```

### String Processing

```jinja
{{ page.title | upper }}
{{ page.title | slugify }}
{{ long_text | truncate_words(50) }}
```

### Array Operations

```jinja
{% set tags = "a,b,c" | split(pat=",") %}
{% for tag in tags %}
  <span>{{ tag | trim }}</span>
{% endfor %}

{{ page.authors | join(" & ") }}
```

### Collection Querying

```jinja
{% set published = site.pages | where(attribute="draft", value=false) %}
{% set newest = published | sort_by(attribute="date", reverse=true) %}

{% for group in newest | group_by(attribute="section") %}
  <h3>{{ group.grouper }}</h3>
  <ul>
  {% for p in group.list %}
    <li><a href="{{ p.url }}">{{ p.title }}</a></li>
  {% endfor %}
  </ul>
{% endfor %}
```

### Collection Processing

```jinja
{# Remove duplicates from tags across all pages #}
{% set all_tags = site.pages | map(attribute="tags") | flatten | unique %}

{# Remove empty entries #}
{% set valid = items | compact %}
```

### Math Operations

```jinja
{# Calculate number of pages #}
{% set total_pages = total_items / per_page | ceil %}
```

### Translations

```jinja
{# Translate UI strings (requires i18n/*.toml files) #}
<nav>
  <a href="/">{{ "nav.home" | t }}</a>
  <a href="/blog/">{{ "nav.blog" | t }}</a>
</nav>

{# Pluralize based on count #}
<p>{{ post_count }} {{ post_count | pluralize(singular="post", plural="posts") }}</p>
```

### Debugging

```jinja
{# Inspect a value for debugging #}
<!-- {{ page.extra | inspect }} -->
```

### Chaining

```jinja
{{ page.title | lower | slugify }}
{{ content | strip_html | truncate_words(100) }}
{{ description | default(value="No description") | upper }}
```

---

## Tests

Tests evaluate conditions in `{% if %}` statements.

| Test | Description | Example |
|------|-------------|---------|
| startswith | Starts with | {% if page.url is startswith("/blog/") %} |
| endswith | Ends with | {% if page.url is endswith("/") %} |
| containing | Contains | {% if page.url is containing("docs") %} |
| matching | Regex match | {% if asset is matching("[.](jpg|png)$") %} |
| empty | Is empty | {% if page.description is empty %} |
| present | Is not empty | {% if page.title is present %} |

### Test Examples

```jinja
{% if page.url is startswith("/blog/") %}
<span class="badge">Blog</span>
{% endif %}

{% if page.description is empty %}
<meta name="description" content="{{ site.description }}">
{% endif %}

{% if page.image is present %}
<meta property="og:image" content="{{ page.image | absolute_url }}">
{% endif %}

{% if "hero.jpg" is matching("[.](jpg|png)$") %}
<span>Image file</span>
{% endif %}
```

### Built-in Tests

```jinja
{% if value is defined %}
{% if value is none %}
{% if value is number %}
{% if value is string %}
{% if value is iterable %}
{% if value is even %}
{% if value is odd %}
```

---

## See Also

- [Data Model](/templates/data-model/) — Available variables
- [Functions](/templates/functions/) — Template functions
- [Syntax](/templates/syntax/) — Template basics

---

Title: Functions
URL: https://hwaro.hahwul.com/templates/functions/
Source: content/templates/functions.md

Built-in functions for retrieving data and generating URLs in templates.

## Data Retrieval

### get_page()

Retrieve any page by path or URL:

```jinja
{% set about = get_page(path="about.md") %}
{% if about %}
<a href="{{ about.url }}">{{ about.title }}</a>
{% endif %}
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| path | String | Relative source path (e.g. `about.md`) or URL path (e.g. `/about/`) |

**Returns:** Page? (nil if not found)

**Returned Properties:**

| Property | Type |
|----------|------|
| title | String |
| description | String? |
| url | String |
| date | String? |
| section | String |
| draft | Bool |
| weight | Int |
| summary | String? |
| word_count | Int |
| reading_time | Int |

**Examples:**

```jinja
{# Page in root #}
{% set contact = get_page(path="contact.md") %}

{# Page in section #}
{% set intro = get_page(path="docs/introduction.md") %}

{# Match by URL #}
{% set intro_by_url = get_page(path="/docs/introduction/") %}
```

---

### get_section()

Retrieve a section by section name, source path, or URL:

```jinja
{% set blog = get_section(path="blog") %}
{% if blog %}
<h2>{{ blog.title }}</h2>
<ul>
{% for p in blog.pages %}
  <li><a href="{{ p.url }}">{{ p.title }}</a></li>
{% endfor %}
</ul>
{% endif %}
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| path | String | Section name (`blog`), path (`blog/_index.md`), or URL (`/blog/`) |

**Returns:** Section? (nil if not found)

**Returned Properties:**

| Property | Type |
|----------|------|
| title | String |
| description | String? |
| url | String |
| path | String |
| name | String |
| pages | Array<Page> |
| pages_count | Int |
| assets | Array<String> |

**Examples:**

```jinja
{# Top-level section #}
{% set docs = get_section(path="docs") %}

{# Nested section #}
{% set guides = get_section(path="docs/guides") %}

{# Match by URL #}
{% set blog = get_section(path="/blog/") %}

{# Display count #}
<p>{{ docs.pages_count }} articles</p>
```

---

### get_taxonomy()

Access taxonomy terms and their pages:

```jinja
{% set tags = get_taxonomy(kind="tags") %}
{% if tags %}
<ul class="tag-cloud">
{% for term in tags.items %}
  <li>
    <a href="/tags/{{ term.slug }}/">
      {{ term.name }} ({{ term.count }})
    </a>
  </li>
{% endfor %}
</ul>
{% endif %}
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| kind | String | Taxonomy name (e.g., "tags", "categories") |

**Returns:** Taxonomy? (nil if not found)

**Returned Properties:**

| Property | Type |
|----------|------|
| name | String |
| items | Array<Term> |

**Term Properties:**

| Property | Type |
|----------|------|
| name | String |
| slug | String |
| pages | Array<Page> |
| count | Int |

---

### get_taxonomy_url()

Generate URL for a taxonomy term:

```jinja
<a href="{{ get_taxonomy_url(kind='tags', term='crystal') }}">
  Crystal articles
</a>
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| kind | String | Taxonomy name |
| term | String | Term name |

**Returns:** String (absolute URL)

---

## Data Loading

### load_data()

Load external data files (JSON, TOML, YAML, CSV):

```jinja
{% set menu = load_data(path="data/menu.json") %}
{% for item in menu %}
<a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| path | String | Path to data file |

**Returns:** Parsed data or nil

**Supported Formats:**

| Extension | Format |
|-----------|--------|
| .json | JSON |
| .toml | TOML |
| .yaml, .yml | YAML |
| .csv | CSV (array of arrays) |

**Examples:**

JSON (`data/team.json`):
```json
[
  {"name": "Alice", "role": "Developer"},
  {"name": "Bob", "role": "Designer"}
]
```

```jinja
{% set team = load_data(path="data/team.json") %}
<ul>
{% for member in team %}
  <li>{{ member.name }} - {{ member.role }}</li>
{% endfor %}
</ul>
```

TOML (`data/social.toml`):
```toml
[[links]]
name = "Twitter"
url = "https://twitter.com/example"
```

```jinja
{% set social = load_data(path="data/social.toml") %}
{% for link in social.links %}
<a href="{{ link.url }}">{{ link.name }}</a>
{% endfor %}
```

---

## Environment

### env()

Read environment variables in templates:

```jinja
{{ env("ANALYTICS_ID") }}
{{ env("API_KEY", default="none") }}
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| name | String | Environment variable name |
| default | String? | Fallback value if variable is unset (optional) |

**Returns:** String (env var value, default, or empty string)

If the variable is not set and no default is provided, an empty string is returned and a build warning is logged.

**Examples:**

```jinja
{# Google Analytics #}
{% if env("GA_ID") %}
<script async src="https://www.googletagmanager.com/gtag/js?id={{ env("GA_ID") }}"></script>
{% endif %}

{# API endpoint with fallback #}
<script>
  const API = "{{ env("API_URL", default="https://api.example.com") }}";
</script>
```

---

## URL Functions

### url_for()

Generate URL with base_url:

```jinja
<a href="{{ url_for(path='/about/') }}">About</a>
<img src="{{ url_for(path='/images/logo.png') }}">
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| path | String | Path to convert |

**Returns:** String (absolute URL)

---

### get_url()

Alias for `url_for()`. You can use either name:

```jinja
<a href="{{ get_url(path='/about/') }}">About</a>
```

---

### now()

Get current datetime:

```jinja
{# Default format #}
<p>Generated: {{ now() }}</p>

{# Custom format #}
<p>Year: {{ now(format="%Y") }}</p>
<p>Date: {{ now(format="%B %d, %Y") }}</p>
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| format | String? | Date format string (optional) |

**Returns:** String

**Format Codes:**

| Code | Description | Example |
|------|-------------|---------|
| %Y | Year | 2025 |
| %m | Month (01-12) | 01 |
| %d | Day (01-31) | 15 |
| %B | Month name | January |
| %b | Month abbr | Jan |
| %H | Hour (00-23) | 14 |
| %M | Minute | 30 |
| %S | Second | 45 |

---

## Media Functions

### resize_image()

Returns a resized image variant. When [image processing](/features/image-processing/) is enabled, this returns the URL to an automatically generated resized image. Otherwise, it returns the original URL.

```jinja
{% set img = resize_image(path="/images/hero.jpg", width=640) %}
<img src="{{ img.url }}" width="{{ img.width }}">
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| path | String | Image path (e.g., `/images/photo.jpg`) |
| width | Int | Requested width in pixels (0 = original) |
| height | Int | Requested height in pixels (0 = original) |

**Returns:** Object with properties:

| Property | Type | Description |
|----------|------|-------------|
| url | String | URL to the resized variant (or original if unavailable) |
| width | Int | Requested width |
| height | Int | Requested height |
| lqip | String | Base64 data URI of a tiny JPEG placeholder (empty if LQIP disabled) |
| dominant_color | String | Hex color string of the image's dominant color, e.g. `#a3b2c1` (empty if LQIP disabled) |

The function selects the closest available width from the configured `widths`. If you request `width=500` and the configured widths are `[320, 640, 1024]`, it returns the 640px variant (smallest width >= requested). If nothing is large enough, it falls back to the largest available.

The `lqip` and `dominant_color` properties require `[image_processing.lqip]` to be enabled. When disabled, they return empty strings.

**Examples:**

```jinja
{# Single resized image #}
{% set img = resize_image(path="/images/hero.jpg", width=800) %}
<img src="{{ img.url }}" alt="Hero">

{# Responsive srcset #}
{% set sm = resize_image(path="/images/hero.jpg", width=320) %}
{% set md = resize_image(path="/images/hero.jpg", width=640) %}
{% set lg = resize_image(path="/images/hero.jpg", width=1024) %}
<img
  src="{{ md.url }}"
  srcset="{{ sm.url }} 320w, {{ md.url }} 640w, {{ lg.url }} 1024w"
  sizes="(max-width: 640px) 320px, (max-width: 1024px) 640px, 1024px"
>

{# With page image from front matter #}
{% if page.image %}
  {% set thumb = resize_image(path=page.image, width=320) %}
  <img src="{{ thumb.url }}" alt="{{ page_title }}">
{% endif %}

{# LQIP blur-up placeholder #}
{% set img = resize_image(path="/images/hero.jpg", width=1024) %}
<img
  src="{{ img.url }}"
  style="background-image: url({{ img.lqip }}); background-size: cover;"
  loading="lazy"
  alt="Hero"
>

{# Dominant color placeholder #}
{% set img = resize_image(path="/images/photo.jpg", width=640) %}
<img
  src="{{ img.url }}"
  style="background-color: {{ img.dominant_color }}"
  loading="lazy"
  alt="Photo"
>
```

Requires `[image_processing]` to be enabled in `config.toml`. See [Image Processing](/features/image-processing/) for setup details.

---

## Best Practices

### Always Check for nil

```jinja
{% set page = get_page(path="featured.md") %}
{% if page %}
{{ page.title }}
{% else %}
<p>Coming soon</p>
{% endif %}
```

### Cache Function Results

```jinja
{# Good: Single lookup #}
{% set blog = get_section(path="blog") %}
<h2>{{ blog.title }}</h2>
<p>{{ blog.pages_count }} posts</p>

{# Avoid: Multiple lookups #}
<h2>{{ get_section(path="blog").title }}</h2>
<p>{{ get_section(path="blog").pages_count }} posts</p>
```

### Organize Data Files

```
data/
├── navigation/
│   ├── main.json
│   └── footer.json
├── team.yaml
└── products.toml
```

---

## See Also

- [Data Model](/templates/data-model/) — Site, Section, Page types
- [Filters](/templates/filters/) — Value transformation

---

Title: Syntax
URL: https://hwaro.hahwul.com/templates/syntax/
Source: content/templates/syntax.md

Hwaro uses Crinja, a Jinja2-compatible template engine. This page covers the essential syntax.

## Variables

Print values with double braces:

```jinja
{{ page.title }}
{{ site.description }}
{{ content }}
```

## Comments

```jinja
{# This is a comment #}
```

## Conditionals

```jinja
{% if page.description %}
<meta name="description" content="{{ page.description }}">
{% endif %}
```

With else:

```jinja
{% if page.draft %}
<span class="badge">Draft</span>
{% else %}
<span class="badge">Published</span>
{% endif %}
```

With elif:

```jinja
{% if page.section == "blog" %}
<article class="post">{{ content | safe }}</article>
{% elif page.section == "docs" %}
<div class="documentation">{{ content | safe }}</div>
{% else %}
<main>{{ content | safe }}</main>
{% endif %}
```

## Loops

```jinja
{% for p in section.pages %}
<li><a href="{{ p.url }}">{{ p.title }}</a></li>
{% endfor %}
```

With index:

```jinja
{% for tag in page.tags %}
{% if not loop.first %}, {% endif %}
{{ tag }}
{% endfor %}
```

Loop variables:

| Variable | Description |
|----------|-------------|
| loop.index | Current iteration (1-based) |
| loop.index0 | Current iteration (0-based) |
| loop.first | True on first iteration |
| loop.last | True on last iteration |
| loop.length | Total items |

## Template Inheritance

### Base Template

`templates/base.html`:

```jinja
<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}{{ site.title }}{% endblock %}</title>
  {{ highlight_css | safe }}
</head>
<body>
  {% block content %}{% endblock %}
  {{ highlight_js | safe }}
</body>
</html>
```

### Child Template

`templates/page.html`:

```jinja
{% extends "base.html" %}

{% block title %}{{ page.title }} - {{ site.title }}{% endblock %}

{% block content %}
<article>
  <h1>{{ page.title }}</h1>
  {{ content | safe }}
</article>
{% endblock %}
```

## Includes

Include partial templates:

```jinja
{% include "partials/header.html" %}
<main>{{ content | safe }}</main>
{% include "partials/footer.html" %}
```

## Variables

Set variables:

```jinja
{% set author = page.authors | first %}
<span>By {{ author }}</span>
```

## Filters

Transform values with the pipe operator:

```jinja
{{ page.title | upper }}
{{ content | safe }}
{{ page.date | date("%B %d, %Y") }}
{{ page.authors | join(", ") }}
```

See [Filters](/templates/filters/) for all available filters.

## Tests

Evaluate conditions:

```jinja
{% if page.url is startswith("/blog/") %}
<span>Blog post</span>
{% endif %}

{% if page.description is empty %}
<meta name="description" content="{{ site.description }}">
{% endif %}
```

See [Filters](/templates/filters/) for all available tests.

## Whitespace Control

Trim whitespace with minus signs:

```jinja
{%- if condition -%}
trimmed
{%- endif -%}
```

## Raw Blocks

Output literal Jinja syntax:

```jinja
{% raw %}
{{ this will not be parsed }}
{% endraw %}
```

## Operators

### Comparison

| Operator | Description |
|----------|-------------|
| `==` | Equal |
| `!=` | Not equal |
| `<` | Less than |
| `>` | Greater than |
| `<=` | Less or equal |
| `>=` | Greater or equal |

### Logical

| Operator | Description |
|----------|-------------|
| `and` | Both true |
| `or` | Either true |
| `not` | Negation |

```jinja
{% if page.section == "blog" and not page.draft %}
<article>{{ content | safe }}</article>
{% endif %}
```

### Membership

```jinja
{% if "tutorial" in page.tags %}
<span class="badge">Tutorial</span>
{% endif %}
```

## Common Patterns

### Active Navigation

```jinja
<nav>
  <a href="/"{% if page.url == "/" %} class="active"{% endif %}>Home</a>
  <a href="/blog/"{% if page.section == "blog" %} class="active"{% endif %}>Blog</a>
</nav>
```

### Conditional Meta Tags

```jinja
<head>
  {% if page.description %}
  <meta name="description" content="{{ page.description }}">
  {% endif %}
  {{ og_all_tags | safe }}
</head>
```

### Section-Based Layout

```jinja
<body data-section="{{ page.section }}">
  {% if page.section == "docs" %}
  {% include "partials/sidebar.html" %}
  {% endif %}
  
  <main>{{ content | safe }}</main>
</body>
```

### Loop with Empty Check

```jinja
{% if section.pages %}
<ul>
{% for p in section.pages %}
  <li><a href="{{ p.url }}">{{ p.title }}</a></li>
{% endfor %}
</ul>
{% else %}
<p>No articles yet.</p>
{% endif %}
```

## See Also

- [Data Model](/templates/data-model/) — Available variables
- [Functions](/templates/functions/) — Built-in functions
- [Filters](/templates/filters/) — Filters and tests

---

Title: Writing
URL: https://hwaro.hahwul.com/writing/
Source: content/writing/_index.md

Content lives in the `content/` directory. Write Markdown with TOML front matter.

## Content Types

| Type | File | URL |
|------|------|-----|
| Page | about.md | /about/ |
| Section | blog/_index.md | /blog/ |
| Section Page | blog/post.md | /blog/post/ |

## Basic Content File

```markdown
+++
title = "My Page"
date = "2024-01-15"
+++

Content in **Markdown**.
```

## Where to Start

Start with **Pages** to learn the basics of content files and front matter. Then read **Sections** to organize content into groups like a blog or docs. From there:

- **Taxonomies** — Classify pages by tags, categories, or custom groups
- **Shortcodes** — Embed reusable components (YouTube, alerts, galleries) inside Markdown
- **Archetypes** — Define templates for `hwaro new` to scaffold content quickly

---

Title: Archetypes
URL: https://hwaro.hahwul.com/writing/archetypes/
Source: content/writing/archetypes.md

Archetypes are content templates that define default front matter and content structure for new pages. When you create content with `hwaro new`, archetypes provide consistent starting points.

## Overview

Archetypes live in the `archetypes/` directory at your project root:

```
my-site/
├── archetypes/
│   ├── default.md      # Default template
│   ├── posts.md        # For content/posts/
│   └── tools/
│       └── develop.md  # For content/tools/develop/
├── content/
├── templates/
└── config.toml
```

## Creating Archetypes

An archetype is a Markdown file with front matter and optional content. Use placeholders that get replaced when creating new content.

### Available Placeholders

| Placeholder | Description |
|-------------|-------------|
| `{{ title }}` | Content title (from `-t` flag or filename) |
| `{{ date }}` | Current date and time |
| `{{ draft }}` | Draft status (`true` for drafts/ directory) |

### Example Archetype

Create `archetypes/posts.md`:

```markdown
+++
title = "{{ title }}"
date = {{ date }}
draft = false
authors = ["Your Name"]
tags = []
categories = []
+++

# {{ title }}

Write your introduction here.

## Main Content

Add your content...
```

## Archetype Matching

When you run `hwaro new`, archetypes are matched in this order:

### 1. Explicit Flag (`-a`)

```bash
hwaro new -t "My Article" -a posts
```

Uses `archetypes/posts.md` regardless of the output path.

### 2. Path-Based Matching

```bash
hwaro new posts/hello-world.md
```

Checks for `archetypes/posts.md`.

### 3. Nested Path Matching

```bash
hwaro new tools/develop/mytool.md
```

Tries in order:
1. `archetypes/tools/develop.md`
2. `archetypes/tools.md`
3. `archetypes/default.md`

### 4. Default Archetype

If no specific archetype matches, uses `archetypes/default.md`.

### 5. Built-in Template

If no archetypes exist, uses the built-in default template.

## Usage Examples

### Basic Usage

```bash
# Uses path-based archetype matching
hwaro new posts/my-first-post.md

# Specify title explicitly
hwaro new posts/my-post.md -t "My First Post"

# Use specific archetype
hwaro new -t "Quick Note" -a posts
```

### Creating Different Content Types

```bash
# Blog post (uses archetypes/posts.md)
hwaro new posts/new-article.md

# Documentation (uses archetypes/docs.md)
hwaro new docs/getting-started.md

# Tool page (uses archetypes/tools.md or archetypes/tools/develop.md)
hwaro new tools/develop/my-tool.md
```

## Recommended Archetypes

### Blog Posts (`archetypes/posts.md`)

```markdown
+++
title = "{{ title }}"
date = {{ date }}
draft = false
authors = []
tags = []
categories = []
description = ""
image = ""
+++

# {{ title }}

Introduction paragraph.

## Content
```

### Documentation (`archetypes/docs.md`)

```markdown
+++
title = "{{ title }}"
date = {{ date }}
weight = 10
toc = true
+++

Brief description of this documentation page.

## Overview

## Usage

## Examples
```

### Default (`archetypes/default.md`)

```markdown
+++
title = "{{ title }}"
date = {{ date }}
draft = {{ draft }}
+++

# {{ title }}
```

## Tips

- **Consistent metadata**: Define all commonly used front matter fields in archetypes
- **Section-specific**: Create archetypes for each content section with relevant defaults
- **Nested organization**: Use subdirectories in `archetypes/` to match your content structure
- **Draft handling**: The `{{ draft }}` placeholder is `true` when creating in `drafts/` directory

## See Also

- [Pages](/writing/pages/) — Front matter fields reference
- [CLI](/start/cli/) — The `hwaro new` command

---

Title: Pages
URL: https://hwaro.hahwul.com/writing/pages/
Source: content/writing/pages.md

Pages are Markdown files that become HTML pages on your site. This page covers **how to write content** — front matter fields, Markdown syntax, and file organization. For how these fields are accessed in templates, see the [Data Model](/templates/data-model/#page).

## Basic Structure

```markdown
+++
title = "My Page"
date = "2024-01-15"
+++

Your content in **Markdown**.
```

The `+++` block is TOML front matter. Content below becomes HTML.

## Front Matter

### Required

| Field | Type | Description |
|-------|------|-------------|
| title | string | Page title |

### Common Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| date | string | — | Publication date (YYYY-MM-DD) |
| description | string | — | SEO description |
| draft | bool | false | Exclude from production builds |
| template | string | "page" | Template to use |
| weight | int | 0 | Sort order (lower = first) |
| image | string | — | Featured image for social sharing |
| tags | array | [] | Tag taxonomy terms |
| categories | array | [] | Category taxonomy terms |

### All Fields

| Field | Type | Description |
|-------|------|-------------|
| updated | string | Last updated date |
| slug | string | Custom URL slug |
| path | string | Custom URL path |
| aliases | array | Redirect URLs to this page |
| authors | array | Author names |
| toc | bool | Show table of contents |
| in_search_index | bool | Include in search |
| in_sitemap | bool | Include in sitemap |
| insert_anchor_links | bool | Add heading anchors |
| redirect_to | string | Redirect page to this URL |
| render | bool | Render page to output (default: true) |
| expires | date | Auto-exclude after this date |
| series | string | Series name for grouping |
| series_weight | int | Sort order within series |
| extra | table | Custom metadata |

## Examples

### Blog Post

```markdown
+++
title = "Getting Started with Crystal"
date = "2024-01-15"
description = "Learn Crystal programming basics"
tags = ["crystal", "tutorial"]
authors = ["Alice Smith"]
image = "/images/crystal-guide.png"
+++

Crystal is a fast, compiled language...
```

### Draft

```markdown
+++
title = "Work in Progress"
draft = true
+++

Not visible in production.
```

Build with drafts: `hwaro build --drafts`

### Expiring Content

```markdown
+++
title = "Limited Time Offer"
expires = 2025-12-31
+++

Automatically excluded from builds after the expiry date.
```

Build with expired content: `hwaro build --include-expired`

Pages expiring within 7 days generate a build warning.

### Future-Dated Content

Pages with a `date` in the future are automatically excluded from builds. This is useful for scheduling content.

```markdown
+++
title = "Coming Soon"
date = 2099-01-01
+++

Published only after the date arrives.
```

Build with future content: `hwaro build --include-future`

### Series Post

```markdown
+++
title = "Part 1: Introduction"
series = "Crystal Tutorial"
series_weight = 1
+++

First part of the series.
```

In templates, access `page.series`, `page.series_index`, and `page.series_pages`.

### Custom Template

```markdown
+++
title = "Landing Page"
template = "landing"
+++

Uses `templates/landing.html` instead of `page.html`.
```

### Weighted Order

```markdown
+++
title = "Introduction"
weight = 1
+++
```

```markdown
+++
title = "Getting Started"
weight = 2
+++
```

Lower weight appears first.

### URL Aliases

```markdown
+++
title = "New Page"
aliases = ["/old-url/", "/another-old-url/"]
+++

Redirects from old URLs to this page.
```

### Custom Metadata

```markdown
+++
title = "Product Review"

[extra]
rating = 4.5
featured = true
pros = ["Fast", "Reliable"]
+++
```

Access in templates: `{{ page.extra.rating }}`

## Full Front Matter Reference

All available fields in one block. Copy and remove what you don't need.

```toml
+++
title = "Page Title"
date = "2024-01-15"
updated = "2024-02-01"
description = "SEO description"
draft = false
template = "page"
weight = 0
slug = "custom-slug"
path = "custom/path"
aliases = ["/old-url/"]
image = "/images/cover.png"
tags = ["tag1", "tag2"]
categories = ["category1"]
authors = ["Author Name"]
toc = true
in_search_index = true
in_sitemap = true
insert_anchor_links = true
render = true
redirect_to = ""
expires = 2025-12-31
series = "Series Name"
series_weight = 1

[extra]
custom_field = "value"
+++
```

## Content Summary

Use `<!-- more -->` to define a summary:

```markdown
+++
title = "Long Article"
+++

This is the summary shown in listings.

<!-- more -->

The full article continues here...
```

## Markdown Syntax

### Text

```markdown
**bold** and *italic*
`inline code`
[link](https://example.com)
![image](/img.jpg)
```

### Lists

```markdown
- Unordered
- Items

1. Ordered
2. Items
```

### Code Blocks

````markdown
```javascript
console.log("Hello");
```
````

### Tables

```markdown
| Header | Header |
|--------|--------|
| Cell   | Cell   |
```

Table cells support inline Markdown: **bold**, *italic*, `code spans`, [links](url), ![images](url), and ~~strikethrough~~.

```markdown
| Feature        | Example                          |
|----------------|----------------------------------|
| Bold           | **important**                    |
| Italic         | *emphasis*                       |
| Code           | `config.toml`                    |
| Link           | [Hwaro](https://example.com)     |
| Image          | ![logo](/img/logo.png)           |
| Strikethrough  | ~~deprecated~~                   |
```

### Internal Links

Use `@/` to link to other content pages by their source path. Hwaro resolves these to the correct output URL at build time.

```markdown
[Read the post](@/blog/my-post.md)
[About section](@/about/_index.md)
[With anchor](@/blog/my-post.md#introduction)
```

This is useful because you don't need to know the final URL — Hwaro calculates it from the content path. If the target page doesn't exist, the link is left unchanged and a warning is logged during build.

| Syntax | Resolved URL |
|--------|-------------|
| `@/blog/post.md` | `/blog/post/` |
| `@/blog/_index.md` | `/blog/` |
| `@/blog/post.md#section` | `/blog/post/#section` |

### Blockquotes

```markdown
> Quote text
```

## Asset Colocation

You can keep related assets (images, PDFs, etc.) in the same directory as your content file. This is known as a **Page Bundle**.

To use this feature, rename your markdown file to `index.md` (for regular pages) or `_index.md` (for section pages) and place it in a directory named after your page.

**Example Structure:**

```text
content/
└── blog/
    ├── my-trip/
    │   ├── index.md        <-- The page content
    │   ├── photo.jpg       <-- Asset
    │   └── data.json       <-- Asset
    └── _index.md
```

Hwaro will copy all non-markdown files from the page bundle directory to the output directory, maintaining the relative path.

In your markdown, you can link to these assets using relative paths:

```markdown
![My Trip Photo](photo.jpg)

[Download Data](data.json)
```

### Accessing Assets in Templates

You can access the list of colocated assets in your templates using `page.assets`. This returns an array of relative paths to the files.

```jinja
{% for asset in page.assets %}
  {% if asset is matching("[.](jpg|png)$") %}
    <img src="{{ get_url(path=asset) }}" alt="Gallery Image">
  {% endif %}
{% endfor %}
```

## URL Mapping

| File | URL |
|------|-----|
| content/index.md | `/` |
| content/about.md | `/about/` |
| content/blog/post.md | `/blog/post/` |

## See Also

- [Sections](/writing/sections/) — Group related pages
- [Data Model](/templates/data-model/) — Page properties in templates

---

Title: Sections
URL: https://hwaro.hahwul.com/writing/sections/
Source: content/writing/sections.md

Sections are directories that group related content. They require an `_index.md` file.

## Creating a Section

```
content/
└── blog/
    ├── _index.md     # Section index → /blog/
    ├── first.md      # Page → /blog/first/
    └── second.md     # Page → /blog/second/
```

## Section Index

Every section needs an `_index.md`:

```markdown
+++
title = "Blog"
description = "Latest articles"
sort_by = "date"
+++

Welcome to my blog.
```

## Front Matter

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| title | string | — | Section title (required) |
| description | string | — | Section description |
| template | string | "section" | Template to use |
| page_template | string | — | Default template for pages |
| sort_by | string | "date" | Sort by: date, weight, title |
| reverse | bool | false | Reverse sort order |
| paginate | int | — | Pages per page |
| paginate_path | string | "page" | Pagination URL pattern |
| transparent | bool | false | Pass pages to parent |
| generate_feeds | bool | false | Generate RSS feed |
| redirect_to | string | — | Redirect URL |
| draft | bool | false | Exclude from production |
| weight | int | 0 | Section sort order |

## Examples

### Blog with Pagination

```toml
+++
title = "Blog"
sort_by = "date"
paginate = 10
paginate_path = "p"
+++
```

Generates: `/blog/`, `/blog/p/2/`, `/blog/p/3/`

### Documentation

```toml
+++
title = "Docs"
page_template = "doc-page"
sort_by = "weight"
+++
```

All pages use `doc-page.html` template and sort by weight.

### Section with Feed

```toml
+++
title = "News"
generate_feeds = true
+++
```

Generates `/news/rss.xml`.

## Full Front Matter Reference

All available fields in one block. Copy and remove what you don't need.

```toml
+++
title = "Section Title"
description = "Section description"
template = "section"
page_template = "custom-page"
sort_by = "date"
reverse = false
paginate = 10
paginate_path = "page"
transparent = false
generate_feeds = true
redirect_to = ""
draft = false
weight = 0
+++
```

## Nested Sections

Sections can contain other sections:

```
content/
└── docs/
    ├── _index.md           # /docs/
    ├── getting-started/
    │   ├── _index.md       # /docs/getting-started/
    │   └── install.md      # /docs/getting-started/install/
    └── guides/
        ├── _index.md       # /docs/guides/
        └── deploy.md       # /docs/guides/deploy/
```

Access subsections in templates:

```jinja
{% for sub in section.subsections %}
<a href="{{ sub.url }}">{{ sub.title }}</a>
<small>({{ sub.pages_count }})</small>
{% endfor %}
```

## Template Variables

When rendering a section page (`_index.md`), these variables are available:

| Variable | Type | Description |
|----------|------|-------------|
| section.title | String | Current section title |
| section.description | String | Current section description |
| section.pages | Array<Page> | Pages shown in the current section list |
| section.pages_count | Int | Number of items in `section.pages` |
| section.list | String | Pre-rendered HTML list (same value as `section_list`) |
| section.subsections | Array<Section> | Direct child sections (`title`, `description`, `url`, `pages_count`) |
| section.assets | Array<String> | Colocated section assets |
| section.page_template | String | Default template name for child pages |
| section.paginate_path | String | Pagination path segment |
| section.redirect_to | String | Redirect target if configured |
| section_list | String | Same as `section.list` |
| pagination | String | Pre-rendered pagination HTML |
| paginator | Object | Structured pagination object |

Use `page.url` for the current section URL.

### `section.list` / `section_list`

```jinja
<ul class="auto-list">
  {{ section.list | safe }}
</ul>
```

### `paginator` (custom pagination UI)

```jinja
{% if paginator is defined and paginator.number_pagers > 1 %}
<nav>
  {% if paginator.previous %}<a href="{{ paginator.previous }}">Prev</a>{% endif %}
  <span>{{ paginator.current_index }} / {{ paginator.number_pagers }}</span>
  {% if paginator.next %}<a href="{{ paginator.next }}">Next</a>{% endif %}
</nav>
{% endif %}
```

## Transparent Sections

Use `transparent = true` to merge pages into parent section:

```toml
+++
title = "2024 Posts"
transparent = true
+++
```

Pages appear in the parent's `section.pages` list.

## Asset Colocation

Just like regular pages, sections can have colocated assets. Place non-markdown files in the same directory as the `_index.md` file.

**Example Structure:**

```text
content/
└── gallery/
    ├── _index.md       <-- The section index
    ├── banner.jpg      <-- Section asset
    └── icon.png        <-- Section asset
```

These assets are copied to the output directory relative to the section.

### Accessing Assets in Templates

You can access the list of section assets in your templates using `section.assets`. This returns an array of relative paths to the files (from the content directory).

```jinja
<!-- In section.html -->
<div class="gallery">
  {% for asset in section.assets %}
    <img src="{{ get_url(path=asset) }}" alt="Section Asset">
  {% endfor %}
</div>
```

## Section vs Page

| File | Type | URL |
|------|------|-----|
| _index.md | Section index | `/blog/` |
| index.md | Regular page | `/blog/` |

Use `_index.md` when you need to list child pages.

## See Also

- [Pages](/writing/pages/) — Individual content files and front matter
- [Taxonomies](/writing/taxonomies/) — Classify content by tags and categories
- [Data Model](/templates/data-model/) — Section properties in templates

---

Title: Shortcodes
URL: https://hwaro.hahwul.com/writing/shortcodes/
Source: content/writing/shortcodes.md

Shortcodes are reusable template snippets you can use in Markdown content. Custom shortcodes are Jinja2 templates placed in `templates/shortcodes/` — see [Template Syntax](/templates/syntax/) for the templating language reference.

## Using Shortcodes

Two syntax patterns work in content files:

```markdown
{%raw%}{{ shortcode_name(arg1="value", arg2="value") }}{%endraw%}
```

Or explicitly:

```markdown
{%raw%}{{ shortcode("shortcode_name", arg1="value") }}{%endraw%}
```

## Built-in Shortcodes

Hwaro ships with built-in shortcodes that work out of the box — no template files needed.

### youtube

Embed a YouTube video.

```markdown
{%raw%}{{ youtube(id="dQw4w9WgXcQ") }}
{{ youtube(id="dQw4w9WgXcQ", width="800", height="450") }}{%endraw%}
```

| Param | Default | Description |
|-------|---------|-------------|
| `id` | (required) | YouTube video ID |
| `width` | `560` | Player width |
| `height` | `315` | Player height |
| `title` | `YouTube Video` | Accessible title |

### vimeo

Embed a Vimeo video.

```markdown
{%raw%}{{ vimeo(id="123456789") }}{%endraw%}
```

| Param | Default | Description |
|-------|---------|-------------|
| `id` | (required) | Vimeo video ID |
| `width` | `560` | Player width |
| `height` | `315` | Player height |
| `title` | `Vimeo Video` | Accessible title |

### gist

Embed a GitHub Gist.

```markdown
{%raw%}{{ gist(user="octocat", id="abc123") }}
{{ gist(user="octocat", id="abc123", file="hello.rb") }}{%endraw%}
```

| Param | Default | Description |
|-------|---------|-------------|
| `user` | (required) | GitHub username |
| `id` | (required) | Gist ID |
| `file` | (none) | Specific file to show |

### alert / callout

Display an alert box. Use as a block shortcode to wrap content.

```markdown
{%raw%}{% alert(type="warning", title="Caution") %}Be careful with this!{% end %}
{% callout(type="tip") %}Here is a helpful tip.{% end %}{%endraw%}
```

| Param | Default | Description |
|-------|---------|-------------|
| `type` | `info` | `info`, `warning`, `danger`, `tip`, `success` |
| `title` | (none) | Optional title |

### figure

Image with optional caption.

```markdown
{%raw%}{{ figure(src="/img/photo.jpg", alt="A photo", caption="My caption") }}{%endraw%}
```

| Param | Default | Description |
|-------|---------|-------------|
| `src` | (required) | Image URL |
| `alt` | `""` | Alt text |
| `caption` | (none) | Caption below image |
| `width` | (none) | Image width |
| `height` | (none) | Image height |

### tweet

Embed a tweet.

```markdown
{%raw%}{{ tweet(user="jack", id="20") }}{%endraw%}
```

| Param | Default | Description |
|-------|---------|-------------|
| `user` | (required) | Twitter username |
| `id` | (required) | Tweet ID |

### codepen

Embed a CodePen.

```markdown
{%raw%}{{ codepen(user="chriscoyier", id="gfdDu") }}
{{ codepen(user="chriscoyier", id="gfdDu", tab="css,result", height="400") }}{%endraw%}
```

| Param | Default | Description |
|-------|---------|-------------|
| `user` | (required) | CodePen username |
| `id` | (required) | Pen ID |
| `tab` | `result` | Default tab(s) |
| `height` | `300` | Embed height |
| `title` | `CodePen Embed` | Accessible title |

> To override any built-in shortcode, create a file with the same name in `templates/shortcodes/` (e.g., `templates/shortcodes/youtube.html`). User templates always take priority.

## Creating Custom Shortcodes

Shortcode templates live in `templates/shortcodes/`.

### Example: Alert Box

Create `templates/shortcodes/alert.html`:

```jinja
{% if type and message %}
<div class="alert alert-{{ type }}">
  {{ message | safe }}
</div>
{% endif %}
```

Use in content:

```markdown
{%raw%}{{ alert(type="warning", message="This is important!") }}{%endraw%}
```

Output:

```html
<div class="alert alert-warning">
  This is important!
</div>
```

### Example: YouTube Embed

Create `templates/shortcodes/youtube.html`:

```jinja
{% if id %}
<div class="video-container">
  <iframe 
    src="https://www.youtube.com/embed/{{ id }}"
    frameborder="0"
    allowfullscreen>
  </iframe>
</div>
{% endif %}
```

Use in content:

```markdown
{%raw%}{{ youtube(id="dQw4w9WgXcQ") }}{%endraw%}
```

### Example: Figure with Caption

Create `templates/shortcodes/figure.html`:

```jinja
<figure>
  <img src="{{ src }}" alt="{{ alt | default(value='') }}">
  {% if caption %}
  <figcaption>{{ caption }}</figcaption>
  {% endif %}
</figure>
```

Use in content:

```markdown
{%raw%}{{ figure(src="/images/photo.jpg", alt="A photo", caption="My caption") }}{%endraw%}
```

### Example: Image Gallery (Asset Colocation)

You can create a gallery that automatically lists images found in the same directory as the page (Page Bundle).

Create `templates/shortcodes/gallery.html`:

```jinja
<div class="gallery">
{% for asset in page.assets -%}
  {%- if asset is matching("[.](jpg|png)$") -%}
    {% set image = resize_image(path=asset, width=240, height=180) %}
    <a href="{{ get_url(path=asset) }}" target="_blank">
      <img src="{{ image.url }}" alt="{{ asset }}" />
    </a>
  {%- endif %}
{%- endfor %}
</div>
```

Use in content (inside a Page Bundle directory):

```markdown
{%raw%}{{ gallery() }}{%endraw%}
```

This will render a grid of all JPG and PNG images found alongside the Markdown file.

## Block Shortcodes

Block shortcodes wrap content between opening and closing tags:

```markdown
{%raw%}{% note() %}
This is the **body** content of the shortcode.
{% end %}{%endraw%}
```

The body is passed to the shortcode template as the `body` variable. Markdown conversion is **not** applied automatically — use the `markdownify` filter in your template if needed:

```jinja
<div class="note">
  {{ body | markdownify | safe }}
</div>
```

Or use the body as-is for raw content:

```jinja
<div class="note">{{ body }}</div>
```

### Nested Shortcodes

Block shortcodes can be nested up to 5 levels deep:

```markdown
{%raw%}{% outer() %}
  Some text with {{ inner(type="info") }} inside.
{% end %}{%endraw%}
```

## Argument Syntax

### Named Arguments

Arguments support multiple quote styles:

```markdown
{%raw%}{{ alert(type="warning", message="Double quotes") }}
{{ alert(type='info', message='Single quotes') }}
{{ alert(type=danger, message=No quotes for simple values) }}{%endraw%}
```

### Positional Arguments

When no `key=value` syntax is used, arguments are assigned as `_0`, `_1`, etc.:

```markdown
{%raw%}{{ youtube("dQw4w9WgXcQ") }}{%endraw%}
```

In the shortcode template, access via `{{ _0 }}`:

```jinja
<iframe src="https://www.youtube.com/embed/{{ _0 }}"></iframe>
```

## Built-in Variables

Shortcodes have access to:

- All passed arguments
- `site` object
- `page` object
- Standard filters and functions

```jinja
{# In shortcode template #}
<a href="{{ site.base_url }}/{{ url }}">{{ text }}</a>
```

## Tips

### Validate Arguments

Always check for required arguments:

```jinja
{% if not url %}
<p class="error">Missing url parameter</p>
{% else %}
<a href="{{ url }}">{{ text | default(value="Link") }}</a>
{% endif %}
```

### Use Safe Filter for HTML

When passing HTML content:

```jinja
{{ content | safe }}
```

### Organize Shortcodes

Group related shortcodes:

```
templates/shortcodes/
├── alert.html
├── youtube.html
├── figure.html
├── code/
│   ├── tabs.html
│   └── snippet.html
└── social/
    ├── twitter.html
    └── github.html
```

## See Also

- [Template Syntax](/templates/syntax/) — Jinja2 reference for custom shortcodes
- [Functions](/templates/functions/) — Built-in template functions

---

Title: Taxonomies
URL: https://hwaro.hahwul.com/writing/taxonomies/
Source: content/writing/taxonomies.md

Taxonomies organize content into groups like tags, categories, or authors.

## Configuration

Define taxonomies in `config.toml`:

```toml
[[taxonomies]]
name = "tags"
feed = true
paginate = 10

[[taxonomies]]
name = "categories"
feed = true

[[taxonomies]]
name = "authors"
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `name` | string | — | Taxonomy name (used in front matter) |
| `feed` | bool | false | Generate RSS feed for each term |
| `sitemap` | bool | true | Include taxonomy pages in sitemap |
| `paginate` | int | — | Pages per pagination page |

## Using Taxonomies

Assign terms in front matter:

```markdown
+++
title = "My Post"
tags = ["crystal", "tutorial"]
categories = ["Programming"]
authors = ["Alice"]
+++
```

## Generated URLs

For a taxonomy named `tags` with term `crystal`:

| URL | Content |
|-----|---------|
| `/tags/` | List of all tags |
| `/tags/crystal/` | Pages tagged "crystal" |

## Templates

### Taxonomy Index

`templates/taxonomy.html` — List of all terms:

```jinja
{% extends "base.html" %}

{% block content %}
<h1>{{ taxonomy_name | capitalize }}</h1>
<ul>
{% for term in taxonomy_terms %}
  <li>
    <a href="/{{ taxonomy_name }}/{{ term.slug }}/">
      {{ term.name }} ({{ term.count }})
    </a>
  </li>
{% endfor %}
</ul>
{% endblock %}
```

### Taxonomy Term

`templates/taxonomy_term.html` — Pages for a specific term:

```jinja
{% extends "base.html" %}

{% block content %}
<h1>{{ taxonomy_name }}: {{ taxonomy_term }}</h1>
<ul>
{% for p in taxonomy_pages %}
  <li>
    <a href="{{ p.url }}">{{ p.title }}</a>
    <time>{{ p.date }}</time>
  </li>
{% endfor %}
</ul>
{% endblock %}
```

## Template Variables

### In taxonomy.html

| Variable | Type | Description |
|----------|------|-------------|
| taxonomy_name | String | Taxonomy name ("tags") |
| taxonomy_terms | Array | All terms (in taxonomy.html) |

### In taxonomy_term.html

| Variable | Type | Description |
|----------|------|-------------|
| taxonomy_name | String | Taxonomy name |
| taxonomy_term | String | Current term name |
| taxonomy_pages | Array<Page> | Pages for term |

### Term Object

| Property | Type | Description |
|----------|------|-------------|
| name | String | Term name |
| slug | String | URL-safe name |
| count | Int | Number of pages |

## get_taxonomy() Function

Access taxonomy data anywhere:

```jinja
{% set tags = get_taxonomy(kind="tags") %}
{% if tags %}
<div class="tag-cloud">
{% for term in tags.items %}
  <a href="/tags/{{ term.slug }}/">{{ term.name }}</a>
{% endfor %}
</div>
{% endif %}
```

## get_taxonomy_url() Function

Generate taxonomy term URL:

```jinja
<a href="{{ get_taxonomy_url(kind='tags', term='crystal') }}">
  Crystal articles
</a>
```

## Common Patterns

### Tag Cloud

```jinja
{% set tags = get_taxonomy(kind="tags") %}
<div class="tags">
{% for term in tags.items %}
  <a href="/tags/{{ term.slug }}/" 
     class="tag count-{{ term.count }}">
    {{ term.name }}
  </a>
{% endfor %}
</div>
```

### Display Page Tags

```jinja
{% if page.tags %}
<div class="post-tags">
{% for tag in page.tags %}
  <a href="/tags/{{ tag | slugify }}/">{{ tag }}</a>
{% endfor %}
</div>
{% endif %}
```

### Category Navigation

```jinja
{% set categories = get_taxonomy(kind="categories") %}
<nav class="categories">
{% for cat in categories.items %}
  <a href="/categories/{{ cat.slug }}/">
    {{ cat.name }} ({{ cat.count }})
  </a>
{% endfor %}
</nav>
```

## See Also

- [Sections](/writing/sections/) — Group content with directories
- [Configuration](/start/config/) — Taxonomy config reference
- [Data Model](/templates/data-model/) — Taxonomy variables in templates