# 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
Language: en

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

---

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

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, and JSON/XML whitespace is compacted. All code blocks and content structure are preserved.

Everything in `static/` is copied into `public/` and deployed, including hidden dot-paths such as `.well-known/security.txt` and `.domains`, identically for cold and `--cache`/incremental builds. Common OS/editor/VCS cruft (`.DS_Store`, `.git/`, …) is filtered out automatically; see [Static Files](/start/config/#static-files) to tune it.

> **Never deploy `hwaro serve` output.** The dev server builds into its own `.hwaro/serve/` directory (leaving `public/` untouched) with its dev `base_url` (e.g. `http://127.0.0.1:3000`) baked into every link, and stamps that directory with a `.hwaro-dev` marker. `hwaro deploy` refuses any source directory carrying the marker; if you hit that error, run `hwaro build` and deploy the freshly built output instead.

## 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 the first configured target
hwaro deploy s3           # Deploy to a specific target by name
hwaro deploy s3 backup    # Deploy to multiple targets
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
Language: en

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: Codeberg Pages
URL: https://hwaro.hahwul.com/deploy/codeberg-pages/
Source: content/deploy/codeberg-pages/index.md
Language: en

Deploy your Hwaro site to [Codeberg Pages](https://codeberg.page/), free static hosting backed by Codeberg's Forgejo instance.

## How Codeberg Pages Works

Codeberg serves static sites in two modes:

- **User / org site** — a repository named **`pages`** under your account. Codeberg serves the *default branch* of that repo at `https://USERNAME.codeberg.page/`.
- **Project site** — any other repository. Codeberg serves a branch named **`pages`** at `https://USERNAME.codeberg.page/REPO/`.

This distinction matters: a project site pushes to a `pages` *branch*, while a user site pushes to the *default branch* (typically `main`) of the `pages` *repo*. The workflow below defaults to the project-site case and exposes `PAGES_BRANCH` so the user-site case is a one-line change.

## Prerequisites

- Codeberg account
- Repository on Codeberg (either `pages` for a user site, or any repo for a project site)
- A Codeberg access token with `write:repository` scope (Settings → Applications → Generate new token)

## Method 1: Forgejo Actions (Recommended)

Codeberg supports [Forgejo Actions](https://forgejo.org/docs/latest/user/actions/), which is GitHub Actions-compatible. Forgejo Actions is opt-in per repository, so enable it under **Settings → Actions** before the workflow will run.

> Forgejo also accepts workflows under `.gitea/workflows/` for backwards compatibility, but `.forgejo/workflows/` is the upstream-blessed path and the one Hwaro generates.

### Generate the Workflow

```bash
hwaro tool platform codeberg-pages
```

This writes `.forgejo/workflows/deploy.yml`:

```yaml
---
name: Hwaro Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: docker
    container:
      image: ghcr.io/hahwul/hwaro:latest
    env:
      # Project site: "pages" (default). User/org site (repo named
      # "pages"): override to your default branch, e.g. "main".
      PAGES_BRANCH: pages
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build site
        run: hwaro build

      - name: Deploy to Codeberg Pages
        env:
          CODEBERG_TOKEN: ${{ secrets.CODEBERG_TOKEN }}
        run: |
          cd public
          git init -b "$PAGES_BRANCH"
          git config user.name  "${{ github.actor }}"
          git config user.email "${{ github.actor }}@noreply.codeberg.org"
          git add -A
          git commit -m "Deploy: $(date -u +'%Y-%m-%dT%H:%M:%SZ')"
          git push --force \
            "https://${{ github.actor }}:$CODEBERG_TOKEN@codeberg.org/${{ github.repository }}.git" \
            "$PAGES_BRANCH"
```

> **Branch history is not preserved.** Each run starts with a fresh `git init` and force-pushes, so the published branch is treated as a publish-only artifact. Keep your source on `main` (or wherever you develop); never edit the `pages` branch by hand.

### User Site vs Project Site

The default `PAGES_BRANCH: pages` targets a **project site** (any repo, served at `USERNAME.codeberg.page/REPO/`). For a **user / org site** in a repo literally named `pages`, change the branch to your default branch:

```yaml
    env:
      PAGES_BRANCH: main   # default branch of the `pages` repo
```

### Add the Token Secret

1. Go to your repository **Settings → Actions → Secrets**
2. Add a new secret named `CODEBERG_TOKEN`
3. Paste your Codeberg access token (with `write:repository` scope)

### Set Base URL

Update `config.toml`:

```toml
# User/org site (repo named "pages")
base_url = "https://USERNAME.codeberg.page"

# Project site (any other repo)
base_url = "https://USERNAME.codeberg.page/REPO"
```

Push to `main` and the workflow will build and deploy automatically.

## Method 2: Deploy via `hwaro deploy`

If you'd rather deploy from your local machine, wire it up as a `[[deployment.targets]]` entry that calls a small shell script.

Create `scripts/deploy-codeberg.sh`:

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

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

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

cd "$TMPDIR"
git init -b "$PAGES_BRANCH"
git add -A
git commit -m "Deploy to Codeberg Pages"
git push --force "$REMOTE_URL" "$PAGES_BRANCH"

rm -rf "$TMPDIR"
```

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

Add the target to `config.toml`:

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

Then build and deploy:

```bash
hwaro build
hwaro deploy codeberg-pages

# Preview without deploying
hwaro deploy codeberg-pages --dry-run

# User site (push to the default branch instead of `pages`)
PAGES_BRANCH=main hwaro deploy codeberg-pages
```

As with Method 1, the script force-pushes a fresh init, so branch history is not preserved.

## Method 3: Manual Branch Deploy

```bash
hwaro build

cd public
git init -b pages
git add -A
git commit -m "Deploy"
git push --force https://codeberg.org/USERNAME/REPO.git pages
```

For a user site (`pages` repo), substitute the default branch name (e.g. `main`) for `pages` in both the `init` and `push` commands.

## Custom Domain

Codeberg Pages supports custom domains via a `.domains` file plus a DNS record. See the [official Codeberg docs](https://docs.codeberg.org/codeberg-pages/using-custom-domain/) for the authoritative version.

> **Repo names with dots are unsupported.** Use `-` or `_` in the repo name if you plan to attach a custom domain.

### 1. Add a `.domains` file

Place a `.domains` file at the root of the served branch listing the domains, one per line. The **first line is the canonical domain**; all subsequent domains are 301-redirected to it. Empty lines and `#` comments are allowed.

```
www.example.org
example.org
```

Drop it under `static/.domains` so Hwaro copies it into `public/` on every build:

```
static/
└── .domains
```

Hwaro copies hidden dot-paths from `static/` verbatim into `public/` on every build (cold or `--cache`/incremental), so `static/.domains` always reaches the served branch. See [Static Files](/start/config/#static-files) for details.

### 2. Configure DNS

Pick **one** of the three options below.

**Option A — CNAME (recommended, simplest).** Point your domain at one of these names:

| Site type     | CNAME target                              |
|---------------|-------------------------------------------|
| Personal site | `USERNAME.codeberg.page`                  |
| Project site  | `REPO.USERNAME.codeberg.page`             |
| Custom branch | `BRANCH.REPO.USERNAME.codeberg.page`      |

CNAME delegates *the whole hostname*, so you cannot run email (MX) on the same name with this option.

**Option B — ALIAS + TXT.** If your DNS provider supports `ALIAS` (or `ANAME`) records:

| Type  | Name | Value                                |
|-------|------|--------------------------------------|
| ALIAS | @    | `codeberg.page`                      |
| TXT   | @    | `REPO.USERNAME.codeberg.page` (or `USERNAME.codeberg.page` for a user site) |

**Option C — A + AAAA + TXT.** Use this if your provider doesn't support ALIAS, or if your zone uses DNSSEC (which is incompatible with the `codeberg.page` CNAME):

| Type | Name | Value                                |
|------|------|--------------------------------------|
| A    | @    | `217.197.84.141`                     |
| AAAA | @    | `2a0a:4580:103f:c0de::2`             |
| TXT  | @    | `REPO.USERNAME.codeberg.page` (or `USERNAME.codeberg.page` for a user site) |

> Verify the latest IPs on the [Codeberg Pages docs](https://docs.codeberg.org/codeberg-pages/using-custom-domain/) before relying on them. Codeberg occasionally rotates them.

If your zone uses CAA records, add an entry that allows Let's Encrypt so Codeberg can issue a TLS certificate:

```
@   CAA   0 issue "letsencrypt.org"
```

### 3. Update `base_url`

```toml
base_url = "https://www.example.org"
```

## Troubleshooting

### Workflow Doesn't Run

- Make sure Forgejo Actions is enabled under **Settings → Actions** for the repository
- Confirm the workflow file is committed at `.forgejo/workflows/deploy.yml` (or `.gitea/workflows/deploy.yml`)

### Push Fails with 401 / 403

- Re-check the `CODEBERG_TOKEN` secret value and that the token still has `write:repository` scope
- Tokens are tied to your account, so make sure the actor has push access to the target repo

### 404 on the Deployed Site

- Codeberg Pages may take a minute or two to publish after the first push
- For a project site, confirm the branch is named exactly `pages`
- For a user site, confirm the repo is named exactly `pages` and `PAGES_BRANCH` matches its default branch
- Verify `base_url` matches the published URL (no trailing slash)

### Custom Domain Doesn't Resolve to HTTPS

- Confirm the `.domains` file is present at the root of the published branch
- If you have CAA records, make sure `letsencrypt.org` is allowed
- Allow a few minutes for the certificate to be issued after DNS propagates

## See Also

- [Deploy Configuration](/deploy/config/) — Target setup and matchers
- [CLI Reference](/start/cli/) — All deploy command options
- [Codeberg Pages docs](https://docs.codeberg.org/codeberg-pages/) — Upstream reference
- Other platforms: [GitHub Pages](/deploy/github-pages/) | [GitLab CI](/deploy/gitlab-ci/) | [Netlify](/deploy/netlify/) | [Cloudflare Pages](/deploy/cloudflare-pages/)

---

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

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
```

| 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 (any negative value disables the limit) |

`max_deletes` bounds the **built-in** `file://` sync only. Command targets
(`s3://`, `gs://`, `az://`, or an explicit `command`) delete through the
external tool's own flags, which hwaro cannot count in advance.

A deploy also refuses outright when the source directory is empty, or when
`include`/`exclude` selected no files while the destination still holds
some. That combination is almost always "the site was never built" and
would otherwise wipe the destination. Pass `--force` to clear a destination
on purpose. A `command` target that never interpolates `{source}` is exempt.

A source directory containing a `.hwaro-dev` marker is refused as well.
That marker means the directory is `hwaro serve` output, with the dev
server's `base_url` (e.g. `http://127.0.0.1:3000`) baked into every link.
Run `hwaro build` and deploy its output instead; there is no override flag
(deleting the marker file by hand is the deliberate escape hatch).

`workers` is accepted for forward compatibility but not applied: the
built-in sync copies serially and command targets manage their own
concurrency. Setting it prints a warning.

## 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 <container> [--destination <path>]` | Azure CLI |

For `az://container/sub/dir` URLs the path becomes the `--destination` prefix inside the container.

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

A value that starts with a URL scheme is never treated as a local path, so a
single-slash typo (`s3:/bucket`) fails with an unsupported-scheme error
instead of quietly creating a directory named `s3:`. `include`, `exclude`,
and `strip_index_html` apply to the built-in `file://` sync only; on
command targets they warn, because the external tool receives the whole
source tree.

**Local directory sync and symlinks.** The built-in sync keeps every write
inside the destination. A symlink standing where a file or directory belongs
is replaced with the real thing, and a symlink with no counterpart in the
source is unlinked. Neither case reads or deletes through the link, so
content living outside the destination is never touched.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| name | string | — | Target identifier (must be unique; duplicates are warned about and only the first is used) |
| url | string | — | Destination URL (`file://`, `s3://`, `gs://`, `az://`) |
| path | string | — | Alias for `url` when deploying to a local directory (`path = "~/public"`; `~` is expanded) |
| 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 = "^.+\\.html$"
force = true
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| pattern | string | — | Regex pattern to match file paths |
| force | bool | false | Always copy matched files, even when identical at the destination |
| cache_control | string | — | Reserved — not applied by the built-in sync (see below) |
| content_type | string | — | Reserved — not applied by the built-in sync (see below) |
| gzip | bool | false | Reserved — not applied by the built-in sync (see below) |

The built-in sync copies files and runs external CLIs; it does not talk to
an object-store API, so it can only honor `force`. Setting `cache_control`,
`content_type`, or `gzip` prints a warning. Configure headers and
compression at your host or CDN instead.

## 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
Language: en

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
Language: en

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 }}
```

### OG Image Caching

The action automatically caches OG images between deploys. Before each build, it restores previously generated images from the `gh-pages` branch and enables `--cache` mode. Only pages with changed content (title, description, URL) or updated OG config will have their images regenerated. This significantly speeds up builds for large sites.

### 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/) | [Codeberg Pages](/deploy/codeberg-pages/)

---

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

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
Language: en

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
Language: en

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
Language: en

Hwaro ships with a broad set of built-in features, and no plugins are 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, related posts, and named navigation menus.

**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, local and remote data, and content file publishing.

**Platform** — Multilingual support, versioned docs, 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
Language: en

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 |
| `loading="lazy"` attributes | Removed (AMP elements do their own lazy loading and reject the attribute) |

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
Language: en

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"]
```

Bundle `files` may also name `.scss` sources. While `[sass]` is enabled they compile through the [built-in Sass compiler](/features/sass/) before concatenation, then minify and fingerprint like any other CSS. Name such bundles with a `.css` extension so the output serves with the right type.

| 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
Language: en

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.
- **Avoid overlapping directories**: results are not deduplicated. A file reachable from two configured dirs (e.g. `assets` and `assets/css`) is included once per dir, so list non-overlapping 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
Language: en

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, Tailwind/PostCSS, and so on; SCSS has a [built-in compiler](/features/sass/))
- 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`, but only on **full** rebuilds:

- Hooks execute on the **initial build** when the server starts
- Hooks **re-execute on full rebuilds**: a `config.toml` change, a file added or removed, or a change to any file under `data/`
- Hooks are **skipped on partial rebuilds**: editing an existing content or template file re-renders only the affected pages and does not re-run your commands
- 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

This keeps save-to-reload fast. If a hook produces something you need refreshed while the server is running, touch `config.toml` or restart `hwaro serve` to force a full rebuild.

### Rebuild loops

A hook that writes into a watched directory (`content/`, `templates/`, `static/`, `data/`, `i18n/`), or into `config.toml` itself, feeds the watcher its own output. The harmless case is handled for you: when a run lands the **same bytes** the build already read (`curl -o data/team.json` fetching an unchanged payload, a bundler re-emitting an identical file, a hook that only touches `config.toml`), the session settles instead of rebuilding forever. Depending on where the file lives, the rewrite is either ignored outright or absorbed by a partial rebuild that does not re-run your commands.

Two patterns still rebuild on every run, because to the watcher they are genuine changes:

- writing **different** bytes each time: an embedded timestamp, a build counter, a non-deterministic bundle hash
- **creating and deleting** a file under a watched directory on every run

Make the output deterministic, or write it somewhere the watcher does not look (`.hwaro/` is ignored, as is anything outside the directories listed above).

## 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"
]
```

### Fetching Data from an API

For the common case, a GET request whose payload should land in `site.data`, you don't need a hook at all. Declare a [`[[data.remote]]` source](/features/remote-data/) in `config.toml` and Hwaro fetches it once per build, with disk caching and explicit error handling built in.

A pre-build hook remains the right tool when the fetch is more than a single request. `load_data()` reads from disk only, so remote data is baked in by fetching it into `data/` before the build. Every file under `data/` is then exposed as `site.data`:

```toml
[build]
hooks.pre = ["curl -sfL https://api.example.com/team -o data/team.json"]
```

```jinja
{% for member in site.data.team %}
  <li>{{ member.name }}</li>
{% endfor %}
```

`curl -f` exits non-zero on an HTTP error, which aborts the build rather than publishing a site with missing data. For anything beyond a single request (pagination, auth headers, reshaping the response), write a script and call that instead:

```toml
[build]
hooks.pre = ["./scripts/fetch-data.sh"]
```

Commit the fetched file if you want reproducible builds offline; add it to `.gitignore` if you always want it fresh.

### 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 full 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
Language: en

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, so there is 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
Language: en

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, so 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 (copied by default, cruft filtered) |
| Extension filtering | ✅ Yes | ❌ No |
| Path filtering | ✅ Yes (`disallow_paths`) | ✅ Yes (`[static]` `exclude`) |
| 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). See [`[static]`](/start/config/#static-files) to exclude cruft or specific paths.

## Tips

- **Page Bundles**: For the best organization, use [page bundles](/writing/pages/#asset-colocation) and 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: Content Generation
URL: https://hwaro.hahwul.com/features/content-generation/
Source: content/features/content-generation.md
Language: en

`[[content.generate]]` turns each record of a `site.data` array (a local `data/` file or a [remote data source](/features/remote-data/)) into a real content page. Point a rule at an array of records, say which fields become the slug, title and body, and every record builds into a page.

Generated pages are **first-class content**: they join the build at the same point authored files do, so section listings, `[permalinks]` patterns, taxonomies, feeds, the search index, the sitemap, OG images and output formats all apply to them exactly as they do to files in `content/`. Combined with `[[data.remote]]`, this builds an entire section from a headless CMS or any JSON API, with no files committed and no scripts.

## Quick Start

```toml
# config.toml
[[content.generate]]
source = "products.items"       # site.data.products.items — must be an array
section = "products"            # pages land at /products/<slug>/
slug = "sku"                    # record field (slugified)
title = "name"                  # record field
body = "description_md"         # record field holding markdown
date = "released"               # optional
description = "{{ item.name }} — {{ item.price }} USD"  # optional, templated
taxonomies = { tags = "categories" }                    # optional
```

```json
// data/products.json
{"items": [
  {"sku": "blue-widget", "name": "Blue Widget", "price": 19.99,
   "released": "2024-01-15", "description_md": "A **blue** widget.",
   "categories": ["gadgets"]}
]}
```

One build later, `/products/blue-widget/` exists: rendered with your `page.html`, listed by the `products` section, tagged under `/tags/gadgets/`, present in the RSS feed, search index and sitemap.

## Fields or Templates

Every value spec (`slug`, `title`, `body`, `date`, `description`, and each `taxonomies` value) accepts one of two forms:

- **A field name** — `slug = "sku"` reads the record's `sku` field. Dotted paths reach into nested objects: `slug = "meta.id"`. A field that does not exist is a **hard error naming the record and the keys that do exist**, so typos never silently generate wrong pages. A field that exists but holds `null` or `""` simply omits the optional value (records without a date are fine); for required specs (`slug`, `title`) it is an error.
- **A template** — any spec containing `{{` or `{%` renders as a template with the record bound to `item`, with all of hwaro's filters available: `slug = "{{ item.sku | slugify }}"`, `title = "{{ item.name | title }}"`.

## Rule Reference

| Key | Required | Meaning |
|-----|----------|---------|
| `source` | yes | Dotted path to an array under `site.data` (`"products"` or `"products.items"`). Anything else (a missing key, a table) is a hard error spelling out what was found. |
| `section` | yes | Target section. Pages get the path `<section>/<slug>.md`, so an existing `content/<section>/_index.md` lists them and `[permalinks]` patterns for the section apply. |
| `slug` | yes | Field or template producing each page's slug. The result is slugified; duplicates within or across rules are a hard error naming both records. |
| `title` | yes | Field or template producing the page title. |
| `body` | no | Field or template producing the page's **markdown** body. Shortcodes, syntax highlighting and every markdown extension run on it. |
| `body_template` | no | Alternative to `body`: a template file from `templates/`, rendered with the record as `item`. The output is markdown. Mutually exclusive with `body`. |
| `date` | no | Field or template producing the page date, in the same formats authored front matter accepts. Future dates keep the page out of a default build, exactly like authored content. |
| `description` | no | Field or template for the page description. |
| `taxonomies` | no | Table of `taxonomy = "spec"`. A field holding an array contributes every element as a term; a scalar contributes one; `null`/`""` contributes none. |

## The Whole Record in Templates

Templates see the full source record as `page.extra.item`, so there is no need to map every field through the rule:

```html
{% if page.synthesized %}
<p class="price">{{ page.extra.item.price }} USD</p>
<p class="stock">{{ page.extra.item.inventory.count }}</p>
{% endif %}
```

`page.synthesized` is `true` on generated pages and `false` everywhere else, so shared templates can branch. Guard `page.extra.item` reads with it, since authored pages have no `item`.

## Collisions

An authored file always wins a contested path: if `content/products/red-widget.md` exists, a generated page for the same slug is dropped with a warning, never the other way around. Two records producing the same slug fail the build, naming both records.

## Rebuilds and Caching

Generated content moves with its data. Editing a `data/` file (or a changed `[[data.remote]]` payload) invalidates cached pages the same way a config edit does, and `hwaro serve` triggers a rebuild on data edits. Under `build --cache`, generated pages are always re-rendered (they have no source file to fingerprint), while authored pages keep their cache behavior.

If a record disappears from the data, its page is gone from the next build's page set, but a previously written file may linger in a `--cache`/preserved output directory (the same is true for a renamed authored file). A full build (`hwaro build`) starts from a clean output directory.

## Tooling

`hwaro tool list` includes generated pages with their provenance (`products/blue-widget.md ← data.products.items`), planned from local data files. Rules backed by a `[[data.remote]]` key that has not been fetched yet are noted rather than listed row by row. Run a build to materialize them.

## Errors

Every failure names the rule, the record (1-based, in data order) and what to fix:

```
Error [HWARO_E_CONTENT]: [[content.generate]] "products.items": record #37: missing field 'skuu' (available: categories, name, price, released, sku).
```

A rule whose `source` is missing or not an array fails the build too. A typo must never silently generate zero pages.

---

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

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
Language: en

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
Language: en

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: Git Metadata
URL: https://hwaro.hahwul.com/features/git-info/
Source: content/features/git-info.md
Language: en

Read each content file's commit history once per build and expose it to templates and SEO outputs, like Hugo's `enableGitInfo`. With `[git]` enabled, a page that has no `updated` in its front matter gets one from its latest commit, so sitemap `<lastmod>`, feed `<updated>`, and JSON-LD `dateModified` reflect when the file really changed.

## Configuration

Opt in via `config.toml`:

```toml
[git]
enabled = true
use_lastmod = true   # page.updated ← latest commit when front matter has none
use_date = false     # page.date ← first commit when front matter has none
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | false | Collect git metadata for `content/` files |
| use_lastmod | bool | true | Set `page.updated` from the file's latest commit when front matter has no `updated` |
| use_date | bool | false | Set `page.date` from the file's first commit when front matter has no `date` |

Front matter always wins: a fallback only fills a field the file left unset.

## How It Works

1. The build runs **one** `git log` over `content/` (never one process per page) and maps every path to its commits. On a 5,200-page test repository the whole collection step took about 50 ms.
2. Each page whose source file has at least one non-merge commit gets a `page.git` object.
3. `use_lastmod` / `use_date` fill the missing `updated` / `date` fields, after which everything downstream (sitemap, feeds, JSON-LD, OpenGraph, `sort_by = "date"`) sees the git-derived value with no template changes.

`hwaro serve` collects history once per full rebuild, not on every file save. `hwaro build --cache` folds each page's commit id and timestamps into its cache key, so a warm rebuild after a new commit re-renders exactly the pages that commit touched (and the listings that show them).

## Template Variable

| Variable | Type | Description |
|----------|------|-------------|
| page.git | Object? | `nil` when the page has no history (see below) |
| page.git.hash | String | Full commit id of the latest non-merge commit that touched the file |
| page.git.short_hash | String | First 7 characters of `hash` |
| page.git.lastmod | Time | Author date of that latest commit |
| page.git.first_commit | Time | Earliest author date across every commit that touched the file |
| page.git.author_name | String | Author name of the latest commit |
| page.git.author_email | String | Author email of the latest commit |

`lastmod` and `first_commit` are real time values (the author's UTC offset is preserved), so the `date` filter formats them directly. The same object is available on pages iterated from listings (`section.pages`, `site.pages`, taxonomy terms).

```jinja
{% if page.git %}
<p class="meta">
  Last updated {{ page.git.lastmod | date(format="%B %d, %Y") }}
  by {{ page.git.author_name }}
  (<a href="https://github.com/you/site/commit/{{ page.git.hash }}">{{ page.git.short_hash }}</a>)
</p>
{% endif %}
```

`page.git` is `nil`, and no fallback applies, for:

- files that are not committed yet (new or untracked),
- pages materialized from `[[content.generate]]`,
- generated taxonomy and listing pages,
- every page when the site is not inside a git repository.

## Bundles, Translations, Renames

- A page bundle (`posts/hello/index.md` + assets) is keyed by its Markdown file, so committing only an asset does not move `lastmod`.
- Each translation (`hello.md`, `hello.ko.md`) is its own file with its own history.
- Renames are **not** followed: a renamed file's history restarts at the rename commit, so `first_commit` (and `page.date` under `use_date`) is the rename date.

## Graceful Degradation

The feature never aborts a build. Each of these produces a single warning and leaves `page.git` unset:

| Situation | Effect |
|-----------|--------|
| No `git` binary on `PATH` | Warning; no git metadata |
| `content/` is not inside a repository | Warning; no git metadata |
| Shallow clone (`--depth N`) | Warning that `lastmod`/`first_commit` may be wrong for files older than the clone depth; metadata is still used |

Most CI checkouts are shallow by default. Fetch the full history so dates are correct:

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
```

## See Also

- [Data Model](/templates/data-model/) — the full `page` object
- [SEO](/features/seo/) and [Structured Data](/features/structured-data/) — where `page.updated` is emitted
- [Incremental Build](/features/incremental-build/) — how `--cache` decides what to re-render

---

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

Hwaro can automatically generate resized image variants during build. This is useful for responsive images, thumbnails, and performance optimization. No external tools are required, since 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, so no runtime resizing or external services are 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
Language: en

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 what each page actually depends on:

- **Template closure** — the page's template plus everything it transitively
  `extends`, `include`s, or `import`s, plus any shortcode templates the page
  content invokes. Each page's cache entry stores a fingerprint of this
  closure, so editing `partials/footer.html` only rebuilds the pages whose
  template chain renders that partial.
- **Cascade fingerprint** — the merged section `[cascade]` values applied to
  the page, so editing a parent `_index.md` cascade rebuilds its descendants.
- **Config checksum** — a hash of the effective merged config. A config
  change invalidates **all** entries.
- **Render hooks** — a fingerprint of every configured `templates/hooks/render-*`
  template (see [Render Hooks](/templates/render-hooks/)) is folded into every
  page's template closure. Since a hook isn't reached via a page's
  `{% include %}`/`{% extends %}` graph, editing one re-renders **every**
  page rather than a narrowed set.

Template dependency tracking requires every template reference to be a string
literal. If any template uses a dynamic reference (`{% include some_var %}`),
Hwaro falls back to whole-site invalidation: any template change rebuilds
every page. You can also opt out explicitly:

```toml
[build]
template_deps = false  # any template change rebuilds every page
```

### 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 only pages whose template closure includes an edited template (all pages when tracking is off, the graph has dynamic references, or the edited file is under `templates/hooks/`) |
| Config file | Full rebuild |
| Static files only | Copy only changed files |

### Removed pages

A cold build starts from an empty output directory, so a page you delete is
gone from `public/` on the next build. `--cache` keeps the directory — that is
the point — so removals are handled from the cache instead: every entry records
the file the page wrote, and on each build the entries no live page claims have
their output deleted.

That covers a page that was deleted, renamed, moved to a new URL (`slug`,
`path`, a permalink rule), turned into a draft, passed its `expires` date, or
set `render = false`.

Everything a removed page brought with it goes too: its `aliases` redirect
stubs, its AMP mirror, its auto-generated OG image, the taxonomy term page of
a tag nobody uses any more (with that term's feed), and the pagination page a
section no longer fills. Turning a whole feature off — `[amp] enabled = false`
— removes what it used to publish on the next build for the same reason.

A `--cache` build's output is therefore byte-identical to a clean build's, and
`hwaro build --full` is not needed to clear anything.

## 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
  (the output path is also what identifies a removed page's stale file)

Add `.hwaro_cache.json` to your `.gitignore` (the one `hwaro init` scaffolds already lists it):

```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
```

## 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
Language: en

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
Language: en

Hwaro supports optional markdown extensions beyond standard CommonMark. Each extension can be toggled in `config.toml` (see the table below for defaults).

## 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 |
| admonitions | bool | true | GitHub-style `> [!NOTE]` blockquotes become admonition blocks |
| heading_ids | bool | true | Custom heading IDs (`## Heading {#custom-id}`) |
| ins | bool | false | Inserted text (`++text++` → `<ins>text</ins>`) |
| mark | bool | false | Highlighted text (`==text==` → `<mark>text</mark>`) |
| sub | bool | false | Subscript (`~text~` → `<sub>text</sub>`) |
| sup | bool | false | Superscript (`^text^` → `<sup>text</sup>`) |
| attributes | bool | false | Generalized `{#id .class key=val}` blocks on headings and inline images |
| safe | bool | false | Strip raw HTML from output (replaced with comments) |
| lazy_loading | bool | false | Add `loading="lazy"` to `<img>` tags |
| emoji | bool | false | Convert emoji shortcodes (e.g. `:smile:`) to emoji characters |
| smart_punctuation | bool | false | Typographic quotes/dashes/ellipses |
| containers | bool | false | `:::note Title` … `:::` custom containers |
| task_list_classes | bool | false | GFM classes on task-list markup |
| insert_anchor_links | string | "none" | Site-wide heading anchor links (`"none"`/`"left"`/`"right"`) |
| external_links_target_blank | bool | false | `target="_blank" rel="noopener"` on absolute http(s) links |
| external_links_no_follow | bool | false | `rel="nofollow"` on absolute http(s) links |
| external_links_no_referrer | bool | false | `rel="noreferrer"` on absolute http(s) links |

## 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.

This is the one exception to [render hooks](/templates/render-hooks/)' "always applies" rule: with `mermaid = true`, a `` ```mermaid `` fence always goes through this pipeline instead of a `render-codeblock.html` hook, even if one is configured. Set `mermaid = false` to have a codeblock hook own mermaid fences like any other language.

### 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>
```

## Inline Markup (ins, mark, sub, sup)

Four opt-in inline styles, each behind its own flag. All are off by default, so
turning one on never affects the others.

### Syntax

```markdown
++Inserted text++ and ==highlighted text==.
Formula: x~2~ + y^2^ = z~n~
```

```toml
[markdown]
ins = true
mark = true
sub = true
sup = true
```

### Output

```html
<p><ins>Inserted text</ins> and <mark>highlighted text</mark>.
Formula: x<sub>2</sub> + y<sup>2</sup> = z<sub>n</sub></p>
```

### Limitations

- **No backslash escape.** None of the four delimiters supports
  CommonMark-style `\`-escaping to suppress the transform, and results
  from trying are inconsistent: a backslash can leave broken, escaped-tag
  output behind instead of either the literal delimiter or the styled
  result. Use a code span (`` `++literal++` ``) whenever you need the
  syntax to show up as text.
- **Delimiter hazards:** `++`/`==`/`~`/`^` all require non-whitespace on
  both sides of the content to activate, so arithmetic-like text (`a ~ b`,
  `x ^ y`, `a == b` with spaces) is left alone. A single `~` and `^` are
  deliberately disjoint from strikethrough's `~~` and normal `**`/`__`
  emphasis, so `~~del~~` and `~sub~` on the same line both work. But a
  page with lots of literal `~`/`^`/`==`/`++` (shell prompts, C/C++
  snippets, XOR-heavy code) should keep those in code spans or fenced code
  blocks either way, since sub/sup/ins/mark only ever apply outside them.
- `sup` will not mangle a footnote reference (`[^1]`) even when `footnotes`
  is also enabled.

## Attributes (`{#id .class key=val}`)

A pandoc-style attribute block on a heading or inline image, a
generalization of the [custom heading ID](/writing/pages/#custom-heading-ids)
shorthand that also sets classes and arbitrary attributes, and extends to
images.

### Syntax

```markdown
## Section Title {#section-title .highlight data-index=3}

![A diagram](diagram.png){.responsive width=800}
```

```toml
[markdown]
attributes = true
```

### Output

```html
<h2 id="section-title" class="highlight" data-index="3">Section Title</h2>

<img src="diagram.png" alt="A diagram" class="responsive" width="800" />
```

Tokens are whitespace-separated (commas are not separators): `#id` sets
the id, `.class` adds a class (repeatable), and `key=value` / `key="quoted
value"` sets any other attribute. `id=value` and `class=value` are
accepted as aliases for `#value` / `.value`. An id may start with a digit
(`{#1-intro}`), the same charset the [custom heading ID](/writing/pages/#custom-heading-ids)
shorthand accepts; a class name may not. Any single invalid token
invalidates the whole block, leaving the source `{...}` untouched.

### Limitations

- **v1 scope is headings and inline images only** — attribute blocks after
  other elements (paragraphs, links, code spans, list items) are not
  supported and are left as literal text.
- A plain `## Heading {#id}` (no other tokens) is still handled by the
  narrower `heading_ids` mechanism even when `attributes` is also on, so
  turning `attributes` on doesn't change existing `{#id}`-only headings.
- **Safe mode drops the block**: with `markdown.safe = true`, `{...}`
  attribute blocks are stripped from the output (like `heading_ids`), so
  no attributes are applied.

## Smart Punctuation

With `smart_punctuation = true`, straight quotes, double/triple dashes,
and three dots become their typographic forms:

| Input | Output |
|-------|--------|
| `"quoted"` / `'quoted'` | “quoted” / ‘quoted’ |
| `--` | – (en dash) |
| `---` | — (em dash) |
| `...` | … (ellipsis) |

Code spans, code blocks, raw HTML, and math bodies are never rewritten.
Table cells, definition bodies, and footnote bodies are pre-rendered
HTML, so smart punctuation does not apply inside them. The `markdownify`
template filter follows the site's setting.

## Custom Containers

With `containers = true`, fenced `:::` blocks render with the same
markup (and CSS) as admonitions:

```markdown
:::note Optional Title
Any **markdown** body — code fences and task lists included.
:::
```

The title defaults to the capitalized type. Longer runs nest
(`::::outer` … `:::inner` … `:::` … `::::`), a bare `:::` closes the
innermost open container, and unclosed containers auto-close at the end
of the page. `:::` lines inside code fences stay literal. Not supported
with `safe = true` (the raw wrapper would be stripped).

## Task List Classes

With `task_list_classes = true`, task-list markup gets GFM's classes so
GitHub-targeted CSS applies as-is: `<li class="task-list-item">`,
`class="task-list-item-checkbox"` on the checkbox, and
`class="contains-task-list"` on every list that directly contains a
task item. Off by default so existing sites keep byte-identical output.

## Heading Anchor Links

`insert_anchor_links = "left"` (or `"right"`) adds a `🔗` anchor link
to every heading site-wide, before or after the heading text. Page
front matter `insert_anchor_links = true/false` overrides the site
setting per page. Customize the markup entirely with a
[render-heading hook](/templates/render-hooks/).

## External Link Policy

Three flags apply a site-wide policy to absolute `http(s)://` links in
rendered markdown (including table cells and footnotes):

```toml
[markdown]
external_links_target_blank = true # target="_blank" + rel="noopener"
external_links_no_follow = true    # rel="nofollow"
external_links_no_referrer = true  # rel="noreferrer"
```

Links that already carry a `target=` keep it, and `rel` tokens merge
into an existing `rel` attribute without duplicating, so a
render-link hook's explicit choices win. The policy applies to every
absolute http(s) link, including ones pointing at your own domain.

## Multi-line Footnotes and Definitions

Footnote definitions collect 4-space (or tab) indented continuation
lines, including blank-line-separated paragraphs:

```markdown
[^1]: First paragraph of the note,
    soft-wrapped onto a second line.

    Second paragraph of the same note.
```

Definition list bodies soft-wrap the same way (indented lines join the
same `<dd>`). Unindented (lazy) continuation, block elements inside
footnote bodies, and multi-paragraph `<dd>` are not supported.

## See Also

- [Configuration](/start/config/) — Markdown configuration options
- [Syntax Highlighting](/features/syntax-highlighting/) — Code block highlighting
- [Render Hooks](/templates/render-hooks/) — Override how links, images, headings, and code blocks render

---

Title: Menus
URL: https://hwaro.hahwul.com/features/menus/
Source: content/features/menus.md
Language: en

Named navigation menus, resolved into a tree and exposed to templates via `site.menus` / `get_menu()`. A menu can be fully defined in `config.toml`, built entirely from page/section front matter, or both at once. Entries from both sources are merged into the same tree.

There's no automatic derivation from sections (Hugo's `sectionPagesMenu`). See [Follow-ups](#follow-ups).

## Configuring a Menu

```toml
[[menus.main]]
name = "Posts"
url = "/posts/"
weight = 1

[[menus.main]]
name = "About"
url = "/about/"
weight = 2
identifier = "about"
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| name | string | — | **Required.** Display label. An entry missing `name` is skipped with a warning. |
| url | string | "" | Root-relative (`/posts/`) or absolute `http(s)://`/`//` URL. |
| weight | int | 0 | Sort order within the menu (ascending), then by `name`, then `identifier`. |
| identifier | string | `name` | Unique key other entries reference via `parent`. |
| parent | string | none | Another entry's `identifier`, to nest this entry under it. |

Each `[[menus.<name>]]` block is a separate named menu. Add `[[menus.footer]]` for a second menu, rendered with `get_menu(name="footer")`.

## Registering a Page/Section from Front Matter

A page or section can join a menu without touching `config.toml`:

```toml
+++
title = "My Post"
menus = ["main"]
+++
```

`menus` (or the singular alias `menu`; `menus` wins if both are present) also accepts a single string (`menus = "main"`) or table form for per-field overrides:

```toml
+++
title = "My Post"

[menus.main]
name = "Featured Post"
weight = 1
parent = "posts"
+++
```

All table-form fields are optional and fall back to the page's own data: `name` defaults to `page.title`, `weight` to `0`, `identifier` to the resolved `name`, and `parent` to none (a root entry).

A page/section may register into **any** menu name, including one `config.toml` never declares. A fully front-matter-defined menu is a legal, supported setup on its own (`hwaro doctor` only flags an undeclared name when config declares at least one menu elsewhere, on the theory that a site with zero `[[menus.*]]` blocks is intentionally going all-in on front matter).

## Hierarchy

Entries with a `parent` become children of the entry whose `identifier` matches. Render nested menus by walking `item.children`:

```jinja
<ul>
{% for item in get_menu(name="main") %}
  <li>
    <a href="{{ item.href }}">{{ item.name }}</a>
    {% if item.children %}
    <ul>
      {% for child in item.children %}
      <li><a href="{{ child.href }}">{{ child.name }}</a></li>
      {% endfor %}
    </ul>
    {% endif %}
  </li>
{% endfor %}
</ul>
```

A `parent` that doesn't match any `identifier` in the same menu (a typo, or a stale reference) doesn't fail the build. The entry is promoted to the root level instead, with a build-log warning. `hwaro doctor` also flags this in `config.toml` before you build (see [Doctor](/start/tools/doctor/)). A duplicate `identifier` keeps the last-declared entry; the earlier one is dropped.

## Per-Language Menus

A `[languages.<code>]` block with no menus table inherits the global `[[menus.*]]` set wholesale. Declaring `[[languages.<code>.menus.<name>]]` **replaces** that menu entirely for that language and does not merge with the global set:

```toml
[[menus.main]]
name = "Posts"
url = "/posts/"

[languages.ko]
language_name = "한국어"

[[languages.ko.menus.main]]
name = "글"
url = "/ko/posts/"
```

`get_menu()` resolves against the **current page's** language, falling back to the default language when that language has no entries for the requested menu name. `site.menus` is always the default language's menus, so use `get_menu()` inside templates that render on non-default-language pages.

Front-matter registrations follow the registering page/section's own language; they're folded into whichever language's menu set they belong to, independent of any per-language config override.

## Active-State Styling

The `active_path` filter compares a menu entry's `url` against the current page:

```jinja
{% for item in get_menu(name="main") %}
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
{% endfor %}
```

Pass `ancestor=true` to also match descendant pages (useful for keeping a parent nav item highlighted/expanded while browsing inside its section):

```jinja
<a href="{{ item.href }}"{% if item.url | active_path(ancestor=true) %} class="open"{% endif %}>{{ item.name }}</a>
```

The root path (`/`) only ever matches exactly, even with `ancestor=true`. Otherwise the home nav item would read as active/open on every page of the site. External entries never match (there's no "current page" for them to be an ancestor of). See [Filters › URL Filters](/templates/filters/#url-filters).

## `href` vs `url`

Every entry exposes both:

- **`url`** — the bare, root-relative path (or untouched external URL) as configured/registered. Comparable to `page.url`, and this is what `active_path` compares against.
- **`href`** — the value to actually put in an `<a href>`. For internal entries this is `url` prefixed with the site's `base_path` (the path component of `base_url`, e.g. `/repo` for a project site deployed at `https://user.github.io/repo/`), so links resolve correctly under a subpath deployment. External entries are untouched, so `href` and `url` are identical.

Always render `item.href`, and compare against `item.url` (as `active_path` does internally). Mixing them up either breaks subpath deploys (using `url` in `href`) or never matches the current page (using `href` in an `active_path`-style comparison).

## Entry Reference

| Field | Type | Description |
|-------|------|--------------|
| name | String | Display label |
| url | String | Bare root-relative path, or untouched external URL |
| href | String | `url` with `base_path` applied (internal) or unchanged (external) — use this in `<a href>` |
| identifier | String | Unique key within the menu |
| weight | Int | Sort order |
| external | Bool | `true` for `http://`, `https://`, or `//` URLs |
| children | Array\<Entry\> | Nested entries (see [Hierarchy](#hierarchy)) |
| page | Page? | The registering page/section's data, when the entry came from front matter and resolves to a `Page` (nil for config-only entries, and for entries registered on a `Section`'s `_index.md`) |

## Follow-ups

- **`sectionPagesMenu`-style auto-derivation** — Hugo can auto-populate a menu from every top-level section without any `[[menus.*]]` or front-matter registration. Hwaro doesn't do this yet; every entry must be explicit (config or front matter).

## See Also

- [Templates: Functions](/templates/functions/#get-menu) — `get_menu()` reference
- [Templates: Filters](/templates/filters/#url-filters) — `active_path` reference
- [Templates: Data Model](/templates/data-model/#menus) — `site.menus` and the Entry shape
- [Configuration](/start/config/#menus) — `[[menus.*]]` config reference
- [Doctor](/start/tools/doctor/) — `menu-parent-undefined` / `menu-undeclared` validators

---

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

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 | true | 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
Language: en

Hwaro auto-generates 1200x630 Open Graph preview images for every page that has no custom `image` in front matter. The generated path is set as `page.image`, so `og:image` meta tags pick it up automatically, with no template changes needed.

![Auto-generated OG image for the Auto OG Images page](/og-images/features-og-images.png)
*The auto-generated OG image for this page (`style = "terminal"`).*

## Quick Start

```toml
[og.auto_image]
enabled = true
style = "terminal"
accent_color = "#2ee66b"
logo = "static/logo.png"
```

## Configuration

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | bool | `false` | Enable auto OG image generation |
| style | string | `"default"` | Composition preset — see [Style Presets](#style-presets) |
| background | string | `"#171310"` | Background color (hex) |
| text_color | string | `"#f4ede4"` | Title and description text color |
| accent_color | string | `"#ec7a66"` | Accent color for rules, brand marks, and color blocks |
| secondary_color | string | — | Second color for two-tone styles (`split`, `brutalist`, `bauhaus`, …). Auto-derived from `accent_color` when omitted |
| font_size | int | `48` | Title font size in pixels. Every style raises this to its own scale automatically unless you set a larger value |
| logo | string | — | Logo file path (e.g., `static/logo.png`), embedded into the image |
| logo_position | string | `"bottom-left"` | `bottom-left`, `bottom-right`, `top-left`, `top-right` |
| show_title | bool | `true` | Show the site name (bottom brand row, or the style's own placement — eyebrow, kicker, window title bar) |
| output_dir | string | `"og-images"` | Directory for generated images |
| format | string | `"png"` | `"png"` or `"svg"`. Social platforms don't render SVG `og:image`, so PNG is the default |
| font_path | string | — | Custom `.ttf`/`.otf` for PNG output. Leads the font chain; glyphs it lacks fall back to the bundled fonts |
| background_image | string | — | Background photo composited behind the text |
| overlay_opacity | float | `0.45` | How much `background` color covers the photo (0.0 = full photo, 1.0 = hidden) |
| text_panel | float | `0.0` | 0.0–0.6. Soft panel behind the text for legibility on busy backgrounds |
| pattern_opacity | float | `0.35` | Peak alpha of the pattern styles (`dots`, `grid`, …). Each pattern fades internally from this peak |
| pattern_scale | float | `1.0` | Scale multiplier for the pattern styles (min 0.1) |
| accent_bars | bool | `false` | Classic thin top/bottom accent bars on the pattern styles |
| lazy_generate | bool | `false` | Skip bulk generation during `hwaro serve`; images render on first request. Recommended for large sites. No effect on `hwaro build` |

Titles render in Space Grotesk, descriptions in Space Grotesk Medium, and the `terminal` style in JetBrains Mono, all bundled into the binary, so PNG output looks the same on every machine. A CJK-capable system font is appended to the chain automatically when your titles need it, and DejaVu Sans Bold backstops everything else.

## Style Presets

The `style` option controls the entire composition. Click any preview below to zoom.

**Signature** — complete, self-contained compositions:

| Style | Description |
|-------|-------------|
| `terminal` | Code-editor window with traffic lights, `$` prompt, and block cursor. Made for dev blogs and docs |
| `bauhaus` | Flat geometric art-poster shapes in accent/secondary/derived colors |
| `halftone` | Print-style halftone dot field fading in from the right edge |

**Modern** — typography-driven with generated backdrops:

| Style | Description |
|-------|-------------|
| `editorial` | Magazine front: hairline rules, an uppercase site-name kicker, and a vertical accent rule. A safe, harmonious default |
| `artistic` | Mesh-gradient color field with film grain. Rich, high-production feel |
| `hero` | Spotlight glow, oversized ghost echo of the first title word, poster typography |
| `surreal` | Aurora orbs and flowing ribbon bands with grain |
| `monument` | Extreme minimalism — massive type, vast whitespace, an accent rule above the title, brand row bottom-right |
| `framed` | Invitation card: a neutral hairline frame with accent corner brackets and centered type |

**Geometric** — bold flat color blocking:

| Style | Description |
|-------|-------------|
| `split` | Diagonal two-tone color block on the left, title on the right |
| `band` | Full-width color band with the title knocked out of it, echoed by a thin rule above — magazine-cover style |
| `brutalist` | Thick framed panel with a hard offset shadow and oversized type |

**Patterns** — compositions with a focal point (each fades internally from `pattern_opacity`):

| Style | Description |
|-------|-------------|
| `default` | Masthead: uppercase site-name eyebrow on top, a low corner glow, and a gentle vignette |
| `minimal` | Nothing but type — and an accent full stop after the title |
| `dots` | Staggered halftone dots fading in from the top-right corner |
| `grid` | Fine blueprint grid with a focal crosshair and registration marks |
| `diagonal` | 45° stripe wedge in the bottom-right corner with an accent rule on the hypotenuse |
| `gradient` | Accent-tinted duotone wash with a corner glow, vignette, and grain |
| `waves` | Layered tide bands anchored to the bottom edge |

### Preview

<div class="og-style-grid">
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-terminal.png" alt="terminal style" loading="lazy" />
    <span class="og-style-label"><code>terminal</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-terminal.png" alt="terminal style" />
        <p><code>terminal</code> — Code-editor window with prompt and cursor</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-bauhaus.png" alt="bauhaus style" loading="lazy" />
    <span class="og-style-label"><code>bauhaus</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-bauhaus.png" alt="bauhaus style" />
        <p><code>bauhaus</code> — Flat geometric art-poster shapes</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-halftone.png" alt="halftone style" loading="lazy" />
    <span class="og-style-label"><code>halftone</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-halftone.png" alt="halftone style" />
        <p><code>halftone</code> — Print-style halftone dot fade</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-editorial.png" alt="editorial style" loading="lazy" />
    <span class="og-style-label"><code>editorial</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-editorial.png" alt="editorial style" />
        <p><code>editorial</code> — Magazine front: rules, kicker, and a vertical accent rule</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-artistic.png" alt="artistic style" loading="lazy" />
    <span class="og-style-label"><code>artistic</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-artistic.png" alt="artistic style" />
        <p><code>artistic</code> — Mesh-gradient color field with film grain</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-hero.png" alt="hero style" loading="lazy" />
    <span class="og-style-label"><code>hero</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-hero.png" alt="hero style" />
        <p><code>hero</code> — Spotlight glow with a ghost type echo</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-surreal.png" alt="surreal style" loading="lazy" />
    <span class="og-style-label"><code>surreal</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-surreal.png" alt="surreal style" />
        <p><code>surreal</code> — Aurora orbs and flowing ribbons</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-monument.png" alt="monument style" loading="lazy" />
    <span class="og-style-label"><code>monument</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-monument.png" alt="monument style" />
        <p><code>monument</code> — Massive type with an accent rule above the title</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-framed.png" alt="framed style" loading="lazy" />
    <span class="og-style-label"><code>framed</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-framed.png" alt="framed style" />
        <p><code>framed</code> — Hairline frame with accent corner brackets</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-split.png" alt="split style" loading="lazy" />
    <span class="og-style-label"><code>split</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-split.png" alt="split style" />
        <p><code>split</code> — Diagonal two-tone color block</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-band.png" alt="band style" loading="lazy" />
    <span class="og-style-label"><code>band</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-band.png" alt="band style" />
        <p><code>band</code> — Magazine color band behind a knocked-out title</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-brutalist.png" alt="brutalist style" loading="lazy" />
    <span class="og-style-label"><code>brutalist</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-brutalist.png" alt="brutalist style" />
        <p><code>brutalist</code> — Thick framed panel with a hard offset shadow</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-default.png" 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.png" alt="default style" />
        <p><code>default</code> — Masthead: eyebrow, corner glow, and vignette</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-minimal.png" 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.png" alt="minimal style" />
        <p><code>minimal</code> — Nothing but type and an accent full stop</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-dots.png" 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.png" alt="dots style" />
        <p><code>dots</code> — Halftone dots fading from the top-right corner</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-grid.png" 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.png" alt="grid style" />
        <p><code>grid</code> — Blueprint grid with a focal crosshair</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-diagonal.png" 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.png" alt="diagonal style" />
        <p><code>diagonal</code> — Stripe wedge with an accent hypotenuse rule</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-gradient.png" 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.png" alt="gradient style" />
        <p><code>gradient</code> — Duotone wash with glow, vignette, and grain</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-waves.png" 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.png" alt="waves style" />
        <p><code>waves</code> — Layered tide bands along the bottom edge</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>

## Background Image

Composite a photo behind the text:

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

Rendering order: background color → photo → color overlay → style composition → text/logo. `overlay_opacity` controls how much the background color dims the photo. Styles that generate their own backdrop (`artistic`, `hero`, `surreal`) skip it when a photo is set, so the photo shows through.

### Preview

The examples below differ only in `overlay_opacity` (same photo, `style = "editorial"`, near-black `background`). Click to zoom.

<div class="og-style-grid">
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/bg-image-low.png" alt="background image with low overlay" loading="lazy" />
    <span class="og-style-label"><code>overlay_opacity = 0.3</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/bg-image-low.png" alt="background image with low overlay" />
        <p><code>overlay_opacity = 0.3</code> — Photo stays vivid</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/bg-image-mid.png" alt="background image with balanced overlay" loading="lazy" />
    <span class="og-style-label"><code>overlay_opacity = 0.55</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/bg-image-mid.png" alt="background image with balanced overlay" />
        <p><code>overlay_opacity = 0.55</code> — Balanced photo and text</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/bg-image-high.png" alt="background image with high overlay" loading="lazy" />
    <span class="og-style-label"><code>overlay_opacity = 0.8</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/bg-image-high.png" alt="background image with high overlay" />
        <p><code>overlay_opacity = 0.8</code> — Photo dimmed, text dominant</p>
      </div>
    </dialog>
  </div>
</div>

## Output Format

PNG is the default. Rendering is built in via stb_truetype and stb_image_write, so no external tools are required. System fonts are auto-detected (Helvetica/Arial on macOS, DejaVu/Liberation/Noto on Linux), with a bundled DejaVu Sans Bold as the last resort.

Titles with CJK characters need a CJK-capable `font_path` (e.g. Noto Sans CJK), since the bundled fonts cover Latin scripts only.

Set `format = "svg"` for dependency-free SVG output instead. Note that social platforms generally don't render SVG `og:image`.

## Incremental Generation

Hwaro stores a `.og_manifest.json` next to the generated images and skips pages whose inputs haven't changed. Keep the output directory between builds (e.g. `--cache` mode) and incremental generation works automatically. The `hahwul/hwaro` GitHub Action handles this for you.

| Change | Regenerates |
|--------|-------------|
| Page title, description, or URL | That page only |
| OG config, or the logo / background image **file contents** | All pages |
| Image file missing on disk | That page only |

## Faster Dev Server

OG generation is one of the most expensive build steps on large sites. Two options:

- `lazy_generate = true` — `hwaro serve` skips bulk generation; each image renders on the first request for its page and is cached after that. `hwaro build` is unaffected. Pairs well with `hwaro serve --fast-start`.
- `hwaro build --skip-og-image` — skips OG images entirely.

## Behavior

- Pages with a custom `image` in front matter keep it; drafts are skipped
- Long titles word-wrap automatically (CJK-aware)
- Logo and background images are loaded once and reused across all pages

## Output

A page at `/posts/hello-world/` produces `public/og-images/posts-hello-world.png` and:

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

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

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

## 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: Output Formats
URL: https://hwaro.hahwul.com/features/output-formats/
Source: content/features/output-formats.md
Language: en

Beyond the HTML page every page and section always renders, Hwaro can
additionally render sibling non-HTML files: a JSON representation of a post,
an XML feed-like listing for a section, a plain-text export, and so on. HTML
rendering is unaffected; extra formats are strictly additive.

Looking to customize the site's RSS/Atom feed markup instead? That's a
[custom feed template](/features/seo/#custom-feed-templates)
(`templates/rss.xml.jinja`), not an output format.

## Configuration

```toml
[outputs]
page = []                 # e.g. ["json"] — formats every regular page emits
section = ["json"]        # formats every section index emits
sections = []              # optional allowlist of section names; empty = all
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| page | array | [] | Formats every regular page emits |
| section | array | [] | Formats every section index emits |
| sections | array | [] | Section names (and their descendants) to restrict `section` output to; empty = all sections |

Only four formats are supported, and the format name is the file extension:

```
json  txt  xml  csv
```

An unknown format name in `[outputs]` fails the build immediately with a
classified config error, rather than silently producing no output.

`sections` matches a section by name or by any of its descendants (a value of
`"posts"` also matches `"posts/reviews"`), the same rule `[feeds].sections`
uses.

## Front Matter Override

A page (or section) can override the config default with a top-level
`outputs` key in its front matter:

```toml
+++
title = "My Post"
outputs = ["json"]
+++
```

`outputs` is not a first-class front matter field. Like any other unknown
top-level key, it lands in `page.extra["outputs"]` and is exposed to
templates as `page.extra.outputs`. Its *presence* in front matter always
wins over the config default, including an explicit empty list:

```toml
+++
title = "Opt this page out"
outputs = []
+++
```

suppresses every format for that one page even if `[outputs].page` is
non-empty in `config.toml`. When the key is absent entirely, the config
default (and `sections` allowlist, for sections) applies.

Because it's an ordinary `extra` value, it also cascades through a section's
`[cascade.extra]` table like any other extra field:

```toml
+++
title = "Blog"

[cascade.extra]
outputs = ["json"]
+++
```

gives every descendant page `outputs = ["json"]` unless a page sets its own.
A malformed override (not an array, or containing a name outside
`json`/`txt`/`xml`/`csv`) is ignored with a one-time build warning, and the page
falls back to no extra formats rather than failing the build.

## Templates

Each enabled format is rendered from a dedicated Crinja template. Templates
are named by extension, same convention as `page.html`/`section.html`:

```
templates/page.json.jinja
templates/section.json.jinja
templates/page.xml.jinja
```

Only the final, recognized template extension (`.html`, `.j2`, `.jinja2`,
`.jinja`, `.ecr`) is stripped when Hwaro loads templates. The `.json`/`.xml`
part is kept as part of the template's name, e.g. `templates/page.json.jinja`
loads as `page.json`.

A page's own body markdown/content, `toc`, and every other value normally
available to `page.html`/`section.html` (`page`, `section`, `site`, `config`,
…) are available in the format template too, so write whatever the format
needs, for example:

```jinja
{# templates/page.json.jinja #}
{
  "title": {{ page.title | tojson }},
  "url": "{{ page.url }}",
  "date": "{{ page.date }}"
}
```

```jinja
{# templates/section.json.jinja #}
{
  "title": {{ section.title | tojson }},
  "pages": [
    {% for p in section.pages %}
    "{{ p.url }}"{% if not loop.last %},{% endif %}
    {% endfor %}
  ]
}
```

### Template Selection Chain

For a given page/section and enabled format `<fmt>`, Hwaro tries, in order:

1. `<entry-template>.<fmt>` — the format-specific sibling of whatever template
   the page actually resolves to (a custom `template = "post"` front matter
   value looks for `post.json` first)
2. `section.<fmt>` — sections only
3. `page.<fmt>` — the final fallback

**A missing template for an enabled format is a hard build error.** If none
of the candidates exist, the build fails immediately and lists every
template name it tried, e.g.:

```
Error [HWARO_E_TEMPLATE]: No template found for output format 'txt' on about.md. Tried: page.txt.
Create one of: templates/page.txt.jinja.
```

This is intentional: a format enabled in config or front matter that silently
produces nothing is a worse failure mode than a loud one.

## Output Location

A format renders to a sibling `index.<fmt>` next to the page's `index.html`:

```
public/
  posts/hello/index.html
  posts/hello/index.json   <- [outputs].page = ["json"]
```

## Pagination

Formats apply once per page/section, on **page 1 only**. A paginated section's
`/page/2/`, `/page/3/`, … output HTML as usual but never get their own
`index.<fmt>`; only the section's own URL does.

## `alternate_output_tags`

Every enabled format gets a `<link rel="alternate" type="…">` tag, available
as `{{ alternate_output_tags }}` in `page.html`/`section.html` (empty string
when the page has no formats):

```jinja
<head>
  {{ alternate_output_tags }}
</head>
```

renders, for a page with `outputs = ["json"]`:

```html
<link rel="alternate" type="application/json" href="https://example.com/posts/hello/index.json">
```

The href resolves through `base_url` the same way `canonical`/`hreflang`
links do, so it's correct under a subpath deployment
(`base_url = "https://user.github.io/repo"`).

## Determinism

Format templates run through the same rendering pipeline as `page.html`, so
avoid `now()` or other non-deterministic values in a format template if you
want byte-identical output across builds (see
[Incremental Builds](/features/incremental-build/)).

## Known Limitation: Disabling a Format Under `--cache`

Removing a format from `[outputs]` (or from a page's front matter) does not
retroactively delete files that a *previous* build already wrote under
`--cache` — the incremental build only re-renders pages it detects as
changed, and "a format was removed from config" isn't tracked as a
per-file change. Run a full (non-incremental) build after disabling a format
to clean up the stale `index.<fmt>` files.

## See Also

- [Configuration](/start/config/) — Full config reference
- [Cascade](/writing/sections/#cascade) — `[cascade.extra]` and cascadable keys
- [Data Model](/templates/data-model/) — `page.extra`
- [Incremental Builds](/features/incremental-build/) — `--cache` semantics

---

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

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 with the `paginator` object:

```jinja
{% if paginator.number_pagers > 1 %}
<nav class="pagination">
  {% if paginator.current_index > 1 %}
  <a href="{{ paginator.first }}">« First</a>
  {% endif %}

  {% if paginator.previous %}
  <a href="{{ paginator.previous }}" class="prev">‹ Prev</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 %}

  {% 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

Taxonomy term pages support pagination via `paginate_by` in `config.toml`:

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

Each term listing (e.g. `/tags/crystal/`) is split into pages of 20 items, with later pages at `/tags/crystal/page/2/`. The same `pagination` and `paginator` template variables are available in the taxonomy template.

## 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
Language: en

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"]
cache_strategy = "cache-first"
```

| 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: `fullscreen`, `standalone`, `minimal-ui` or `browser` (an unknown value falls back to `standalone`) |
| 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 |
| cache_strategy | string | `"cache-first"` | Asset fetch strategy: `cache-first`, `network-first`, or `stale-while-revalidate` |

> Write `start_url`, `icons`, `offline_page`, and `precache_urls` as plain root-relative paths **without** your `base_url` prefix (e.g. `start_url = "/"`, not `"/repo/"`). When `base_url` includes a subpath (GitHub Pages project sites), Hwaro prepends it automatically in the generated `manifest.json` and `sw.js`.

## Icon Sizing

The `sizes` field of each icon is measured from the file itself: the real
pixel dimensions read out of the PNG, JPEG, or BMP header. Browsers pick the
install icon by this value, so a measured size is always preferred over a
guess.

| Icon | Declared `sizes` |
|------|------------------|
| `logo.png` (200x60 on disk) | 200x60 |
| `icon-2024.jpg` (192x192 on disk) | 192x192 |
| `favicon.svg` | `any` (scalable — no pixel size) |
| `icon-192.png` (unreadable / missing) | 192x192 (from the filename) |
| `icon-512x512.png` (unreadable / missing) | 512x512 (from the filename) |
| `logo.webp`, `https://cdn.example/icon.png` | from the filename, else 512x512 |

The filename heuristic is only a fallback: it applies to formats whose header
Hwaro cannot read (WebP, ICO), to remote `http(s)://` icons, and to files whose
bytes turn out to be unreadable. A build warning names the icon when that
happens.

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

## Template Integration

The easiest wiring is the `{{ pwa_tags }}` template variable. It expands to
the manifest link, a theme-color meta, and the service worker registration
(already base-path-prefixed), and renders as an empty string while `[pwa]` is
disabled. The scaffold header templates include it out of the box:

```jinja
<head>
  {{ pwa_tags }}
</head>
```

To wire things manually instead, add the manifest link and service worker
registration to your base template:

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

> The `{{ base_url }}` prefix is required so the manifest and service worker
> resolve correctly on subpath deploys (e.g. GitHub Pages project sites served
> at `https://user.github.io/repo/`). The generated `manifest.json`/`sw.js`
> already carry the subpath internally, but their `<link>`/`register()` URLs do
> not unless you add it here.

## Caching Strategy

The generated service worker uses:

- **Precache on install** — URLs listed in `precache_urls` plus `start_url` are cached immediately
- **Asset fetching** — Controlled by `cache_strategy` (see below)
- **Network-first for navigation** — Page navigations always try the network first, falling back to the offline page
- **Automatic cache versioning** — Old caches are cleaned up on service worker activation

Set `cache_strategy` to pick how assets (non-navigation requests) are served:

| Value | Behavior |
|-------|----------|
| `cache-first` (default) | Serve from cache if present, otherwise fetch from network and cache the response. Fastest for static sites. |
| `network-first` | Try the network first; fall back to cache on failure. Use when you want fresh content but offline resilience. |
| `stale-while-revalidate` | Serve the cached copy immediately and refresh the cache in the background. Balances speed and freshness. |

Unknown values log a warning and fall back to `cache-first`.

## 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
Language: en

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: Remote Data Sources
URL: https://hwaro.hahwul.com/features/remote-data/
Source: content/features/remote-data.md
Language: en

`[[data.remote]]` fetches an HTTP(S) payload into `site.data` before templates
render. It fits a JSON API, a small headless CMS endpoint, or another
single-request source: templates stay offline and every network dependency is
declared in `config.toml`.

For data committed with the site, use files in `data/` instead. Remote and
local data have the same template interface, so moving a key between them does
not require template changes.

## Quick Start

```toml
[[data.remote]]
key = "team"                # exposed as site.data.team
url = "https://api.example.com/team"
format = "json"             # optional when the response identifies its format
headers = { Authorization = "Bearer ${API_TOKEN}" }
cache = "1h"                # reuse a fresh cached payload
on_error = "fail"           # fail | warn-and-use-cache | warn-and-skip
```

```jinja
{% for person in site.data.team %}
  <h2>{{ person.name }}</h2>
  <p>{{ person.role }}</p>
{% endfor %}
```

## Configuration Reference

| Field | Required | Meaning |
|-------|----------|---------|
| `key` | yes | Name under `site.data`. It accepts letters, digits, `_`, and `-`; each key is unique case-insensitively. |
| `url` | yes | Absolute `http://` or `https://` URL. Other schemes are rejected when loading config. |
| `format` | no | `json`, `toml`, `yaml`, or `csv`. When omitted, Hwaro uses the response `Content-Type`, then the final URL extension after redirects. Set it explicitly if neither identifies a format. |
| `headers` | no | Extra request headers. They are treated as credentials: never logged, and dropped if a redirect leaves the original origin. |
| `cache` | no | Disk-cache TTL such as `"90s"`, `"30m"`, `"1h"`, `"7d"`, or `"1h30m"`. A fresh cache skips the request. |
| `on_error` | no | Fetch/parse failure policy: `fail` (default), `warn-and-use-cache`, or `warn-and-skip`. |

CSV data becomes an array of rows; each row is an array of trimmed strings,
matching `load_data()` for local CSV files.

## Environment Variables

`${VAR}` placeholders in `url` and `headers` are expanded from the environment.
Unlike ordinary config interpolation, a missing variable here fails the build
and names the variable, preventing a request with an accidental empty token.
Use `${VAR:-default}` where a safe fallback exists. Expansion happens only when
a build fetches the source, so `hwaro deploy`, `hwaro new`, and `hwaro tool ...`
do not require those variables.

## Cache, Offline Builds, and Serve

Payloads live in `.hwaro/remote_data/`, outside the directories watched by
`hwaro serve`. The cache survives `hwaro build --full` and is ignored by Git.

- With `cache` set, builds reuse a payload while its TTL is fresh. Without it,
  each new `hwaro build` refetches, while retaining the last successful payload
  for `warn-and-use-cache`.
- `warn-and-use-cache` warns and uses any saved payload when a fetch or parse
  fails. `warn-and-skip` warns and leaves `site.data.<key>` unset; guard that
  key in templates. `fail` stops the build.
- In one `hwaro serve` session, an unchanged source is held in memory. A
  TTL-controlled source is retried on the first full rebuild after expiry. If
  that refresh fails, serve keeps the previously loaded payload so editing can
  continue offline.
- A changed payload invalidates cached pages in the same way an edited local
  `data/` file does.

Each source allows 10 seconds to connect, 30 seconds per read, and 120 seconds
overall across redirects and the full response body. Timeout failures follow
the selected `on_error` policy.

## Boundaries and Collisions

Remote sources are intentionally config-only: `load_data()` and shortcodes
cannot fetch URLs. For pagination, POST requests, authentication flows, or
reshaping several responses, use a [pre-build hook](/features/build-hooks/#fetching-data-from-an-api)
to write a local file under `data/`.

A remote key cannot share a name with a local data file. For example,
`data/team.json` and `key = "team"` are a configuration error; Hwaro names both
sources rather than silently choosing one.

To turn a remote array into pages, combine it with
[Content Generation](/features/content-generation/). Generated pages take part
in listings, taxonomies, feeds, search, sitemap, and output formats just like
authored content.

## See Also

- [Data Model](/templates/data-model/#data-files) — local `data/` files and template access
- [Content Generation](/features/content-generation/) — materialize data records as pages
- [Build Hooks](/features/build-hooks/) — multi-step or non-GET integrations

---

Title: Sass/SCSS
URL: https://hwaro.hahwul.com/features/sass/
Source: content/features/sass.md
Language: en

Hwaro compiles SCSS at build time with a built-in, pure-Crystal compiler. There is no dart-sass binary to install, no npm toolchain, and no C library, consistent with Hwaro's zero-external-dependency philosophy.

## Quick Start

```toml
[sass]
enabled = true
```

Put SCSS files under `static/`:

```
static/
├── css/
│   ├── _variables.scss   # partial — never published
│   ├── _mixins.scss      # partial — never published
│   └── style.scss        # entry — compiles to /css/style.css
```

```scss
// static/css/style.scss
@use "variables";
@use "mixins";

.card {
  color: variables.$primary;
  &:hover { color: variables.$accent; }

  @include mixins.respond(768px) {
    padding: 2rem;
  }
}
```

Every non-partial `*.scss` compiles to a sibling `.css` in the output (`static/css/style.scss` → `/css/style.css`), so stylesheets keep stable URLs:

```html
<link rel="stylesheet" href="{{ url_for(path="/css/style.css") }}">
```

## Rules

- **Entries** — `*.scss` files whose name does not start with `_` compile to a sibling `.css` at the same relative path in the output.
- **Partials** — `_*.scss` files never compile standalone and never publish; they are only reachable via `@use`/`@import`.
- **Raw sources are not published** — while `[sass]` is enabled, `.scss` files are excluded from the verbatim static copy.
- **Bundles** — `[[assets.bundles]]` `files` entries may name `.scss` files; while `[sass]` is enabled they compile before concatenation and then flow through the normal minify → fingerprint pipeline. With `[sass]` disabled, bundle entries concatenate verbatim (the escape hatch for pre-compiled or out-of-subset sources).
- **Watch** — `hwaro serve` recompiles on `.scss` changes. Editing a partial recompiles every entry (there is no dependency graph; whole-tree recompilation is fast at static-site scale). Compile errors appear in the browser error overlay.

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | bool | `false` | Enable SCSS compilation |
| `minify` | bool | `true` | Minify compiled CSS (same minifier as the asset pipeline) |

## Supported Subset

Hwaro implements a practical SCSS subset, the features hand-written site stylesheets actually use:

| Feature | Support |
|---------|---------|
| `$variables` | ✅ with `!default` / `!global`, lexical scoping and shadowing |
| Nested rules | ✅ including selector lists (cartesian combination) |
| `&` parent selector | ✅ `&:hover`, `&.mod`, BEM `&__elem` / `&--mod` |
| `#{...}` interpolation | ✅ selectors, property names, values, at-rule preludes, strings, `url()`. Full expressions inside; strings render unquoted at every nesting level, lists included (`#{("a", "b")}` → `a, b`) |
| Partials + `@use` | ✅ namespaces (`colors.$primary`), `as x`, `as *`, load-once, `with (...)` configuration |
| `@forward` | ✅ `show` / `hide` filters, `as prefix-*` |
| `@import` (Sass files) | ✅ classic global-merge semantics, including a partial that only `@forward`s (`@import "components"` → `components/_index.scss`); plain-CSS forms pass through |
| `@mixin` / `@include` | ✅ default values, keyword arguments, variadic `$args...` (extra keywords land in `meta.keywords()`), spreads (keywords forward through `$args...`), `@content` blocks with arguments (`@content(1px)` / `@include m using ($a)`) |
| `@function` / `@return` | ✅ user functions callable in values, defaults/keywords/variadic, recursion |
| `@extend` + `%placeholders` | ✅ simple-selector targets, compound unification, `!optional`; un-extended placeholders never emit (see deviations) |
| `&` in SassScript | ✅ `if(&, "&", "")` and friends. The parent selector as a value, `null` at the root |
| Control flow | ✅ `@if` / `@else if` / `@else`, `@each` (with destructuring), `@for` (`through`/`to`, descending), `@while` |
| SassScript expressions | ✅ arithmetic (`+ - * / %`, classic slash-division rule), comparisons, `and`/`or`/`not`, strings, lists, maps (see deviations for `/`) |
| Unit conversion | ✅ `px`/`cm`/`mm`/`q`/`in`/`pt`/`pc`, `deg`/`grad`/`rad`/`turn`, `s`/`ms`, `Hz`/`kHz`, `dpi`/`dpcm`/`dppx` convert in arithmetic, comparisons, `==`, and `math.*` |
| Nested properties | ✅ `font: 12px serif { family: sans; }` → `font`, `font-family` (recursive) |
| Built-in functions | ✅ `sass:math` (incl. `log` / `hypot` / trigonometry), `sass:string` (incl. `insert` / `split`), `sass:list` (incl. `zip` / `set-nth` / `slash` / `is-bracketed`), `sass:map` (incl. `set` / `deep-merge` / `deep-remove`), `sass:meta` (incl. `keywords` / `variable-exists` / `function-exists` / `mixin-exists` / `content-exists` / `get-function` / `call`), `sass:selector` (string-level `parse` / `nest` / `append` / `unify` / `replace` / `is-superselector` / `simple-selectors`; `replace` shares the `@extend` subset's limits: compound `$original` only, no pseudo-class recursion, first prefix order only), `sass:color` subset (incl. `channel` / `hwb` / `ie-hex-str`) + legacy global names (`map-get`, `nth`, `darken`, `if()`, …) |
| Module constants | ✅ `math.$pi`, `math.$e`, `math.$epsilon`, `math.$max-safe-integer`, `math.$min-safe-integer`, `math.$max-number`, `math.$min-number` |
| `@debug` / `@warn` / `@error` | ✅ `@error` fails the build with a located message |
| `@at-root` | ✅ selector and block forms, `#{&}` suffixing, `(with: ...)` / `(without: ...)` queries |
| `@media` / `@supports` in rules | ✅ bubbled out of nesting automatically; nested `@media` merge with `and` (comma lists cross-multiply); feature values evaluate expressions |
| `@keyframes`, `@font-face`, custom properties | ✅ pass through correctly |
| Plain CSS | ✅ any valid `.css` compiles to itself (whitespace-normalized) |

Unknown functions (`var()`, `clamp()`, `color-mix()`, …) pass through untouched. Arguments still evaluate (`translate($x * 2, -50%)` works), a static `calc()` folds to its number (see deviations), and a whole-token `url($v)` / `url(ns.$img)` substitutes the variable (`$` is not valid in a raw URL). A `$` embedded in a larger url token (`url(plain$x.png)`) is valid plain CSS and passes through byte-identical. dart-sass hard-errors there, and evaluates expression contents like `url($a + $b)` that Hwaro keeps verbatim.

```scss
@use "sass:math";
$breakpoints: (sm: 640px, md: 768px, lg: 1024px);

@function rem($px, $base: 16px) { @return math.div($px, $base) * 1rem; }

@mixin respond($name) {
  @if not map-has-key($breakpoints, $name) { @error "unknown breakpoint #{$name}"; }
  @media (min-width: map-get($breakpoints, $name)) { @content; }
}

@each $name, $bp in $breakpoints {
  .container-#{$name} { max-width: $bp - 24px; }
}
@for $i from 1 through 12 {
  .col-#{$i} { width: math.percentage(math.div($i, 12)); }
}
.hero {
  font-size: rem(28px);
  @include respond(md) { font-size: rem(40px); }
}
```

### Colors

Color functions operate on hex literals (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`), the CSS color keywords (`red`, `rebeccapurple`, `transparent`), and the legacy comma spellings `rgb(…)` / `rgba(…)` / `hsl(…)` / `hsla(…)`. A color built from `hsl()` remembers its declared hue/saturation, so `hue(hsl(221, 14%, 100%))` answers `221deg`:

```scss
$brand: #336699;

.button {
  background: $brand;
  border-color: darken($brand, 10%);      // #264d73
  color: scale-color($brand, $lightness: 60%);
  box-shadow: 0 1px 2px rgba($brand, 0.4); // rgba(51, 102, 153, 0.4)
}
```

| Group | Functions |
|-------|-----------|
| Lightness | `darken`, `lighten` |
| Saturation | `saturate`, `desaturate`, `grayscale` |
| Hue | `adjust-hue`, `complement` |
| Blending | `mix`, `invert` |
| Alpha | `rgba($color, $alpha)`, `opacify` / `fade-in`, `transparentize` / `fade-out` |
| Compound | `adjust-color`, `scale-color`, `change-color` |
| Components | `red`, `green`, `blue`, `hue`, `saturation`, `lightness`, `alpha` / `opacity`, `color.channel` |
| Misc | `ie-hex-str`, `color.hwb` (both `color.hwb($h $w $b)` and `color.hwb($h, $w, $b)`) |

The same functions are available under `sass:color` with the modern names: `color.adjust`, `color.scale`, `color.change`, `color.mix`, `color.complement`, `color.grayscale`, `color.invert`, and the component getters:

```scss
@use "sass:color";
.a { border-color: color.scale(#336699, $lightness: -20%); }
```

A computed color serializes as `#rrggbb` when opaque and `rgba(r, g, b, a)` otherwise. A color you *don't* modify keeps the exact spelling you wrote, so `#FFF` stays `#FFF`.

Colors compare by channel across spellings: `#ffffff == #FFF`, `red == #f00`, and `rgb(255, 0, 0) == #ff0000` are all true (dart-sass semantics).

### @extend

`@extend` works on simple-selector targets (a class, `%placeholder`, id, element, or pseudo), which covers how real stylesheets (Bootstrap included) use it. The target's compound is unified with the extender's final compound, ancestor compounds are prepended, and un-extended `%placeholder` rules never reach the output:

```scss
%visually-hidden { position: absolute; clip: rect(0 0 0 0); }
.sr-only { @extend %visually-hidden; }
// → .sr-only { position: absolute; clip: rect(0 0 0 0); }
```

A missing target fails the build with a located error; append `!optional` to tolerate it. See the deviations list for how the subset differs from dart-sass's full extend algorithm.

### Not supported (yet)

Compound units (`px*em`, `px/s`, multiplication/division that would need numerator/denominator unit lists), `@forward ... with (...)`, `math.random` / `unique-id()` (builds must stay deterministic), the indented `.sass` syntax, and source maps.

**Unsupported directives fail the build with a located error** — Hwaro never emits silently broken CSS:

```
Error [HWARO_E_CONTENT]: Sass: static/css/style.scss:14:3: @forward ... with (...) is not supported
```

### Expression semantics

The compiler's first duty is the plain-CSS guarantee, so expressions follow a two-tier policy:

- **Value contexts are lenient.** A declaration or variable value is evaluated only when it visibly computes something: an operator between numbers, or a call to a known function. Anything else, and anything that *fails* to evaluate (`$a + 2em` with incompatible units, `min(100% - 10px, 20rem)`), keeps its verbatim text exactly as before. Existing stylesheets compile byte-identically.
- **New syntax is strict.** `@if`/`@while` conditions, `@each`/`@for` headers, `@return`, and `@use ... with` report every failure as a located build error.

### Deviations from dart-sass

- `/` follows the classic Sass division rule (dart-sass 1.x): it divides when an operand is a variable, a known function call, or parenthesized, or when the slash sits in a computing context (adjacent arithmetic, a Sass function argument, a variable declaration, interpolation, control flow). Literal-only slashes (`font: 12px/1.5`, `grid-area: 1 / 2`) stay verbatim **with the author's spacing**, whereas dart-sass reprints them compacted (`1/2`).
- Values are stored as CSS text between evaluations; types are re-derived on use. An unquoted string that *looks* like a list (`"a, b"` unquoted) is treated as one.
- Unit arithmetic converts within the standard groups (length, angle, time, frequency, resolution), the left operand's unit winning. Compound units (`1px * 1em`, `math.div(1px, 1s)`) are not modeled and fall back to verbatim text.
- `and`/`or` in *value* positions only operate on real booleans, so `font-family: Franklin and Marshall` stays text. Conditions have full Sass truthiness.
- Global `min()`/`max()`/`round()`/`abs()` evaluate only when all arguments are statically comparable numbers; CSS forms (`min(5vw, 100px)`, `round(up, 101px, 10px)`) pass through.
- `rgb()`/`rgba()`/`hsl()`/`hsla()` are **not** folded in their CSS forms: `rgb(0, 0, 0)` stays verbatim where dart-sass would emit `black` (a color *function* handed such a literal still reads it as a color). Only the Sass-only `rgba($color, $alpha)` spelling, which is not valid CSS, evaluates. Likewise `grayscale()`, `invert()`, `saturate()` and `opacity()` are color functions when handed a color and plain CSS filters when handed a number (`filter: grayscale(50%)` passes through).
- A computed color serializes with integer channels: by CSS keyword when the rounded channels match one exactly (`mix(red, blue)` → `purple`, aliases in dart's spelling: `aqua`, `gray`, `fuchsia`), else as hex/`rgba()`. dart-sass 1.79+ keeps fractional channels instead (`mix(red, blue)` is `rgb(50%, 0%, 50%)` there), so the keyword form matches dart only when the computation lands on exact integers; values are off by at most one per channel either way.
- Built-in functions accept their documented keyword names (`list.append($l, x, $separator: comma)`, `string.slice($string: …, $start-at: 2)`, `darken($c, $amount: 10%)`, `map.get($map: …, $key: …)`). Variadic builtins (`math.min`, `list.zip`, `map.set`, `selector.nest`) stay positional. User-defined `@mixin`/`@function` keyword arguments work normally.
- `@extend` is a practical subset of dart-sass's algorithm: targets must be simple selectors, extends apply document-wide (dart-sass scopes them per module and forbids crossing `@media` boundaries), and when both the extended selector and the extender have ancestor compounds only the first prefix order is emitted (dart-sass "weaves" both). Shared leading prefixes merge (`.nav %p` extended by `.nav > .c` → `.nav > .c`).
- A `calc()` whose contents fold to a single static number is simplified the way dart-sass does: `calc(10px + 5px * 2)` → `20px`, `calc(9 / 21 * 100%)` → `42.8571428571%`, nested `calc`/`min`/`max`/`clamp` included (`clamp` bounds win at exact boundaries, unit spelling included). Anything not fully foldable keeps its verbatim text: `calc(100% - 20px)`, `var()`, interpolated `calc(#{…})`, unitless↔united addition or clamp, `+`/`-` without surrounding whitespace (invalid CSS that dart-sass errors on), and division producing NaN. `@supports (width: calc(…))` never folds, because the query tests calc support itself. A slash after a literal `calc()` (`font: calc(16px)/1.5`) stays verbatim like every literal slash.
- Variables in at-rule preludes and values substitute directly (`@media (min-width: $bp)` works); selectors and property names require `#{...}` interpolation (same as dart-sass).
- At-rule preludes evaluate expressions only inside `(feature: value)` spans; the query structure itself stays verbatim.
- `@media` nested inside `@media` merges the conditions with `and` (comma lists cross-multiply outer-major; type-conflicting pairs are dropped). Queries the merge can't express (`not …`) and nestings interrupted by another at-rule (`@supports`) keep the literal nested form (valid modern CSS) where dart-sass drops or rewrites them.
- `&` substitution is textual, so `&__elem` concatenates without validating the compound selector.
- Custom property values are verbatim: `$var` stays literal, only `#{...}` interpolates (dart-sass semantics), but leading/trailing whitespace is trimmed.
- `@import` of the same file re-emits its CSS each time (classic Sass behavior); `@use` loads once.
- Configuring a module that itself uses `@forward` (`@use "lib" with (...)`) is an error rather than silently ignored.
- Output with non-ASCII content gets a single leading `@charset "UTF-8";`; source `@charset` declarations are dropped (dart-sass behavior).
- Values are substituted as text: interpolating a variable whose value contains an unbalanced quote character can confuse downstream whitespace/quote handling. Keep quote characters inside quoted strings.
- Only lowercase `.scss` extensions are treated as Sass sources; other casings publish verbatim like any static file.

## Errors

Compile failures are classified content errors (exit code 5) with `path:line:column` locations:

```
Error [HWARO_E_CONTENT]: Sass: static/css/_mixins.scss:7:12: undefined variable: "$primry"
```

During `hwaro serve`, errors show in the browser overlay and the previous output stays on disk.

## Interplay with Other Features

- **Asset pipeline** — compiled standalone entries keep stable (non-fingerprinted) URLs and resolve through `asset()`'s passthrough. For fingerprinting, reference the `.scss` file from a bundle instead.
- **Build hooks** — Tailwind/PostCSS and full dart-sass projects can still run through `[build] hooks.pre` and point Hwaro at the compiled output.
- **Cache** — Sass recompiles on every full build (it does not participate in the incremental page cache). Deleting an entry `.scss` leaves its previously compiled `.css` in a stale output dir; clean builds remove it.

---

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

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 — by default only `title` and `content` (`url` is always added) |
| filename | string | "search.json" | Output filename |
| exclude | array | [] | Paths (prefixes) to exclude from search index |
| tokenize_cjk | bool | false | Enable CJK bigram tokenization |
| shards | string | "none" | Split the index into lazy-loadable shards: `"section"`, `"language"`, or `"section-language"` — see [Sharded index](#sharded-index) |
| single_file | bool | true | With `shards` on, keep emitting the classic `search.json` alongside the shards; `false` emits shards only |
| content_max_length | int | 0 | When > 0, truncate each entry's `content` to that many characters at a word boundary; `0` keeps the full text |

## 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

Only fields listed in `fields` are emitted (`url` is always included):

| 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;
});
```

## Sharded Index

A single `search.json` grows with the site, and every visitor pays for the whole file before the first search. Sharding splits the index into several JSON files plus a manifest so a client can load only what it needs: the current section first, or one language at a time.

```toml
[search]
enabled = true
shards = "section"          # "section" | "language" | "section-language"
single_file = false         # emit shards only (default true keeps search.json too)
content_max_length = 500    # optional: cap each entry's content
```

| Mode | Shards | Example ids |
|------|--------|-------------|
| `"section"` | One per top-level content section; pages outside any section go to `_root` | `blog`, `docs`, `_root` |
| `"language"` | One per language (multilingual sites); the default language uses its code | `en`, `ko` |
| `"section-language"` | Language, then section | `en/blog`, `ko/blog`, `ko/_root` |

Nested sections fold into their top-level section: `blog/news/post.md` lands in the `blog` shard. Every eligibility rule of the classic index applies unchanged (`fields`, `exclude`, `in_search_index = false`, drafts, `render = false`, per-language `build_search_index`, `tokenize_cjk`).

### Generated Files

```
public/
├── search.json          # unless single_file = false
└── search/
    ├── index.json       # manifest
    ├── _root.json
    ├── blog.json
    └── docs.json        # nested ids use directories: search/ko/blog.json
```

Each shard is a plain JSON array with exactly the same entry schema as `search.json` (shards are always JSON, whatever `format` says; the `*_javascript` wrapper only serves `<script src>` loading). `search/index.json` describes the layout:

```json
{
  "version": 1,
  "fields": ["title", "content", "url", "lang"],
  "shards": [
    {"id": "_root", "url": "/search/_root.json", "language": null, "section": "", "count": 2, "bytes": 200},
    {"id": "blog",  "url": "/search/blog.json",  "language": null, "section": "blog", "count": 42, "bytes": 12345}
  ]
}
```

- `url` honors `base_url`'s subpath (`/docs/search/blog.json` on a `https://example.com/docs` deploy) and percent-encodes section names.
- `language` is set in the `language` and `section-language` modes, `section` in the `section` and `section-language` modes; the other is `null`.
- Shards are listed in id order and the file never carries a timestamp, so the output is deterministic and diff-friendly. A shard whose last page disappears is removed on the next build.
- `--cache` builds and `hwaro serve` regenerate the shards from the same page set as `search.json`.

### Lazy-Loading Shards with Fuse.js

Fetch the manifest once, then load shards on demand. A global search box loads all of them; a section-aware one loads the current section's shard first and the rest in the background:

```html
<script src="https://cdn.jsdelivr.net/npm/fuse.js@7.0.0"></script>
<script>
const loaded = new Map();       // shard id → entries
let manifest = null;
let fuse = null;

async function loadManifest() {
  if (manifest) return manifest;
  manifest = await (await fetch('/search/index.json')).json();
  return manifest;
}

async function loadShard(shard) {
  if (loaded.has(shard.id)) return;
  loaded.set(shard.id, await (await fetch(shard.url)).json());
  fuse = new Fuse([...loaded.values()].flat(), {
    keys: ['title', 'content', 'description', 'tags'],
    threshold: 0.3,
    ignoreLocation: true
  });
}

// Which shards matter for this page? Match the manifest against the
// document language and the first URL segment; fall back to everything.
async function loadRelevantShards() {
  const { shards } = await loadManifest();
  const lang = (document.documentElement.lang || '').split('-')[0];
  const section = location.pathname.split('/').filter(Boolean)[0] || '';
  const local = shards.filter(s =>
    (s.language === null || s.language === lang) &&
    (s.section === null || s.section === section));
  await Promise.all((local.length ? local : shards).map(loadShard));
  // Warm the remaining shards without blocking the first results.
  shards.filter(s => !loaded.has(s.id)).forEach(s => loadShard(s));
}

function search(query) {
  return fuse ? fuse.search(query) : [];
}

document.getElementById('search-input').addEventListener('focus', loadRelevantShards, { once: true });
</script>
```

For a purely global box replace `loadRelevantShards` with `shards.map(loadShard)`. Everything after loading is the same Fuse.js code as the single-file setup above.

## 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
Language: en

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 (한국어)"`).

### Custom Feed Templates

To take full control of the feed markup, create a template named after the feed output:

| Feed type | Template file | Loaded as key |
|-----------|---------------|---------------|
| RSS | `templates/rss.xml.jinja` | `rss.xml` |
| Atom | `templates/atom.xml.jinja` | `atom.xml` |

Any template extension works (`.jinja`, `.j2`, `.jinja2`, `.html`). Only the final extension is stripped, so `rss.xml.jinja` loads under the key `rss.xml`. Whatever the extension, the file is always rendered as **Jinja** (an `.ecr` file is picked up too, but ECR `<%= %>` tags pass through as literal text, so use Jinja syntax). The template file itself is the opt-in: when it's absent, Hwaro emits its built-in feed exactly as before, and deleting the template falls back to the built-in output. The override applies to **all four feed kinds** (the main feed, per-section feeds, per-language feeds, and per-taxonomy-term feeds), and a custom `[feeds] filename` still controls the output path.

`{% include %}` works inside feed templates, and a broken template fails the build with a template error naming the file.

#### Context variables

`feed` — metadata about the feed being rendered:

| Variable | Type | Description |
|----------|------|-------------|
| `feed.type` | string | `"rss"` or `"atom"` (follows `[feeds] type`) |
| `feed.kind` | string | `"main"`, `"section"`, `"language"`, or `"taxonomy"` |
| `feed.title` | string | Feed title (site title, `Site - Section`, `Site (한국어)`, …) |
| `feed.description` | string | Site description |
| `feed.url` | string | Absolute, percent-encoded self URL of this feed file |
| `feed.home_url` | string | Canonical HTML URL the feed represents (site root, section page, or language home) |
| `feed.base_url` | string | `base_url` without a trailing slash |
| `feed.language` | string? | Language code for per-language feeds, else none |
| `feed.updated` | time | Newest entry date (deterministic; epoch when no entry has a date) |
| `feed.updated_rfc3339` | string | `feed.updated` as RFC 3339 (Atom `<updated>`) |
| `feed.updated_rfc822` | string | `feed.updated` as RFC 822 (RSS `<lastBuildDate>`/`<pubDate>` style) |
| `feed.author` | string | Site title (falls back to the feed title) |
| `feed.section_url` | string? | Section URL — section feeds only |
| `feed.taxonomy` / `feed.term` | string? | Taxonomy name and term — taxonomy feeds only |

`pages` — the sorted, limit-applied entry list. Each entry:

| Variable | Type | Description |
|----------|------|-------------|
| `title` | string | Page title (site title when the page title is empty) |
| `url` | string | Absolute, percent-encoded page URL |
| `date` / `updated` | time? | Raw front-matter dates (usable with the `date` filter) |
| `date_rfc822` | string? | Preformatted RFC 822 date; none for dateless pages |
| `updated_rfc3339` | string | RFC 3339 timestamp from `updated`/`date` (epoch fallback) |
| `description` | string? | Front-matter description |
| `summary` | string | Plain-text summary (description → `<!-- more -->` summary → excerpt) |
| `content` | string | Body honoring `full_content`/`truncate` (plain text when truncating) |
| `content_html` | string | Full HTML body with links absolutized for out-of-context readers |
| `content_is_html` | bool | Whether `content` is HTML (`false` under `truncate`/`full_content = false`) |
| `authors` | array | Front-matter authors |
| `categories` | array | Taxonomy terms — `tags` first, then other taxonomies, deduplicated |
| `section` | string | Page section path |
| `language` | string? | Page language code |

#### Example

Values are **not** pre-escaped. Applying `xml_escape` (or emitting CDATA) is the template author's job:

```jinja
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>{{ feed.title | xml_escape }}</title>
    <link>{{ feed.home_url | xml_escape }}</link>
    <description>{{ feed.description | xml_escape }}</description>
    {% if feed.language %}<language>{{ feed.language | xml_escape }}</language>{% endif %}
    <atom:link href="{{ feed.url | xml_escape }}" rel="self" type="application/rss+xml" />
    {% for p in pages %}
    <item>
      <title>{{ p.title | xml_escape }}</title>
      <link>{{ p.url | xml_escape }}</link>
      <guid>{{ p.url | xml_escape }}</guid>
      <description>{{ p.summary | xml_escape }}</description>
      {% if p.date_rfc822 %}<pubDate>{{ p.date_rfc822 }}</pubDate>{% endif %}
      {% for term in p.categories %}<category>{{ term | xml_escape }}</category>{% endfor %}
    </item>
    {% endfor %}
  </channel>
</rss>
```

### 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 for content pages (default: `"article"`; listing pages always emit `"website"`) |
| 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
Language: en

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
Language: en

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 500 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.

Setting either also disables the GC heap presize that `hwaro build` normally applies (`GC_INITIAL_HEAP_SIZE=256M`): a presized heap never shrinks below its floor, which would work against the memory cap you asked for.

### 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=500 |
| - | 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 —
   but only when nothing downstream reads it back (see below)
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

### When `page.content` is kept

The search index and every feed surface read each page's rendered body back
during the Generate phase. Releasing it under them would leave those generators
with a markdown-only re-render of `raw_content` — no shortcode expansion, no
`@/` link resolution, no anchor links, no `base_path` prefix — so `search.json`
and `rss.xml` would carry raw `{% shortcode %}` markup and broken links.

So step 3 is skipped whenever any of these is on:

- `[search] enabled`
- `[feeds] enabled`
- any `[[taxonomies]]` with `feed = true`
- any section with `generate_feeds` in its `_index.md`

With all of them off, batches are released as before. Either way the render
itself still runs in batches, so the per-batch peak (worker template output,
Crinja value caches) stays bounded.

## Output

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

> This did not hold on releases up to v0.20.1: on a site with a search index
> or feeds, `--stream` shipped unexpanded shortcodes and unresolved `@/` links
> into `search.json` and every feed. Rebuild such a site once after upgrading.

Use `--verbose` to see batch progress:

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

```
Building site...
  Streaming mode enabled (batch size: 500)
  ...
  Streaming batch 1 (500 pages)
  Streaming batch 2 (500 pages)
  Streaming batch 3 (234 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
Language: en

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
Language: en

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
mode = "server"
```

| 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) |
| mode | string | "server" | `"server"` highlights at build time; `"client"` highlights in the browser via Highlight.js |
| line_numbers | bool | false | Add line numbers to every fenced code block by default (see below) |
| copy | bool | false | Add a copy-to-clipboard button to fenced code blocks (see below) |

## Server-Side Highlighting (Default)

With `mode = "server"` (the default), code blocks are highlighted during
the build. No JavaScript ships to the browser, and code is colored even
with JavaScript disabled.

The build-time highlighter emits Highlight.js-compatible CSS classes, so
every theme above keeps working unchanged: `{{ highlight_css }}` still
injects the theme stylesheet, while `{{ highlight_js }}` becomes empty.

Over 250 languages are supported (via [Tartrazine](https://github.com/ralsina/tartrazine)
lexers, ported from Pygments/Chroma). Code blocks in languages without a
lexer fall back to plain, unhighlighted output.

## Client-Side Highlighting

Set `mode = "client"` to highlight in the browser with Highlight.js
instead:

```toml
[highlight]
mode = "client"
theme = "github-dark"
```

In client mode `{{ highlight_js }}` injects the Highlight.js script (from
the CDN or your local assets, see below), and code blocks ship as plain
`<pre><code class="language-...">` markup for the browser to colorize.

## Line Numbers and Highlighted Lines

A fenced code block's language can be followed by an options block,
`{...}`, to add line numbers and/or highlight specific lines:

````markdown
```python {linenos=true, hl_lines="2-4 7", linenostart=5}
def main():
    setup()
    run()
    teardown()
    return 0
```
````

| Option | Value | Description |
|--------|-------|--------------|
| `linenos` | `true` / `false` | Show a line-number gutter. Overrides the `[highlight] line_numbers` default for this block. |
| `hl_lines` | e.g. `"2-4 7"` | Highlight these lines. Space/comma-separated line numbers and/or ranges. Always the block's own **physical** 1-based lines, never shifted by `linenostart`. |
| `linenostart` | e.g. `5` | First displayed line number (default `1`). Only affects the numbers shown; it does not change which physical lines `hl_lines` highlights. |
| `hide_lines` | e.g. `"1 9-12"` | Omit these lines from the rendered output (server mode only, see below). Same syntax and physical-line semantics as `hl_lines`. |
| `copy` | `true` / `false` | Show a copy-to-clipboard button on this block. Overrides the `[highlight] copy` default. Ignored on `mermaid` fences. |
| `name` | e.g. `"main.cr"` | Filename/title label rendered above the block (`title=` is accepted as an alias). Ignored on `mermaid` fences. |

A named block is wrapped for styling (the `<pre>` inside is unchanged):

```html
<div class="code-block"><div class="code-filename">main.cr</div>
<pre><code class="language-crystal hljs">…</code></pre>
</div>
```

Scaffolded sites ship matching `.code-block` / `.code-filename` styles;
bring your own CSS otherwise.

The block accepts a couple of equivalent forms: `python {linenos=true}`,
`python{linenos=true}` (no space), or `{linenos=true}` alone (no
language). A malformed or unrecognized options block (e.g. `{oops}`) is
left as literal text in the language token, exactly as if fence options
didn't exist.

Setting `[highlight] line_numbers = true` turns line numbers on for
*every* fenced code block with a language; a per-block `{linenos=false}`
opts back out.

Hidden lines keep consuming their physical line numbers, so with
`linenos=true` the gutter shows a **gap** where lines were elided,
unlike Zola, which renumbers the remaining lines. This keeps the
documented invariant that `hl_lines` and `linenostart` always target the
block's physical lines, hidden or not (highlighting a hidden line is
simply a no-op).

Only `mode = "server"` actually removes hidden lines from the HTML. In
client mode `hide_lines` is presentational-only metadata (an inert
`data-hide-lines` attribute), and the lines remain in the page source. Do
**not** use `hide_lines` to redact secrets in client mode.

**Server vs client mode:**

- `mode = "server"` (default) renders the full result at build time: each
  line is wrapped in its own element, so line numbers and highlighted
  lines appear with no JavaScript.
- `mode = "client"` does not re-render the body. Instead the
  `<pre>` tag gets `data-linenos="true"`, `data-linenostart="N"` (when
  greater than 1), `data-hl-lines="2-4 7"`, and/or
  `data-hide-lines="1 9-12"` attributes, so a client-side script or
  custom CSS can act on them. Hwaro ships no such script for client
  mode; full rendering (and actual line hiding) requires
  `mode = "server"`.

Scaffold sites style the server-mode markup out of the box. For a
non-scaffold site, or a custom theme, add:

```css
pre code .line.hl { display: inline-block; width: 100%; background: color-mix(in srgb, var(--code-keyword) 12%, transparent); }
pre code .ln { user-select: none; -webkit-user-select: none; opacity: .45; }
```

(Swap `var(--code-keyword)` for any color that fits your theme if you
aren't using the Hwaro Ember token system.)

## Copy Button

`[highlight] copy = true` adds a copy-to-clipboard button to every fenced
code block; a per-fence `{copy=false}` (or `{copy=true}` with the global
default off) overrides it:

```toml
[highlight]
copy = true
```

The markup contract: each opted-in block's `<pre>` gets a
`data-copy="true"` attribute, and `{{ highlight_js }}` injects a small
inline, dependency-free runtime (works in both server and client mode).
With `copy = true` the runtime ships site-wide; with the global default
off, pages whose body contains an opted-in block get it appended to
their own `{{ highlight_js }}`; pages without one stay JavaScript-free.
The runtime wraps each `pre[data-copy]` in a `<div class="code-wrapper">`
(reusing an existing `.code-block` wrapper from a named fence as the anchor
instead), appends a `<button class="code-copy-btn">`, and copies the
code's text on click (server-mode `.ln` line-number gutters are stripped
from the copied text). The inline styles are theme-neutral
(currentColor, hover-reveal); scaffolded sites override them with
token-based styles.

`mermaid` fences never get the attribute, since their `<pre>` shape is owned
by the Mermaid pipeline.

New scaffolded sites enable `copy = true` out of the box.

## 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`.
In the default server mode only the theme stylesheet is referenced; the
`<script>` tags above appear only with `mode = "client"`.

## 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: Versioned Docs
URL: https://hwaro.hahwul.com/features/versioned-docs/
Source: content/features/versioned-docs.md
Language: en

Hwaro can publish several versions of the same documentation (v1, v2, …) from one site, with a version switcher, per-version navigation and SEO that points search engines at the current release. Versioning is **directory-based** and modeled on [multilingual](/features/multilingual/) support: a page belongs to the version whose content directory contains it.

## Configuration

```toml
[versions]
latest_at_root = true     # latest version renders at its section's natural URL
noindex_old = true        # older versions: <meta name="robots" content="noindex"> + canonical to the latest counterpart
search = "latest"         # "latest" | "all" — which versions enter search.json AND sitemap.xml
feeds = "latest"          # "latest" | "all" — which versions feed RSS/Atom
taxonomies = "latest"     # "latest" | "all" — which versions taxonomy term pages collect from

[[versions.list]]
name = "v2"               # URL segment, must be URL-safe (letters, digits, - _ . ~)
label = "2.x (latest)"    # switcher label (defaults to name)
path = "docs/v2"          # content directory relative to content/ (defaults to name)
latest = true

[[versions.list]]
name = "v1"
label = "1.x"
path = "docs/v1"
```

TOML cannot make one key both a table and an array of tables, so the switches live in `[versions]` and the entries in `[[versions.list]]`. If you only need the defaults, a bare array works too:

```toml
[[versions]]
name = "v2"
path = "docs/v2"
latest = true

[[versions]]
name = "v1"
path = "docs/v1"
```

Validation (all of these fail the build with `HWARO_E_CONFIG`):

- `name` is required, URL-safe and unique.
- `path` must be a directory relative to `content/`; two versions can neither share a path nor nest inside each other.
- Exactly one entry is `latest = true`. If none is marked, the **first** entry is the latest; two or more marked entries are an error.
- `search`, `feeds` and `taxonomies` accept only `"latest"` or `"all"`.

`hwaro doctor` warns (`version-path-missing`) when a version points at a content directory that does not exist.

## Content Structure

Each version is a normal content tree under its own directory. Files with the same path relative to the version root are treated as the same page in different versions. That is how the switcher finds counterparts.

```
content/
└── docs/
    ├── v2/
    │   ├── _index.md
    │   ├── install.md
    │   └── plugins.md      # only in v2
    └── v1/
        ├── _index.md
        ├── install.md
        └── legacy.md       # only in v1
```

### URL Mapping

The version directory is swapped for the directory the version *publishes* under. With `latest_at_root = true` (the default) the latest version takes the parent's natural URL and older versions get a `/<name>/` segment:

| Source | URL |
|--------|-----|
| `content/docs/v2/_index.md` | `/docs/` |
| `content/docs/v2/install.md` | `/docs/install/` |
| `content/docs/v1/_index.md` | `/docs/v1/` |
| `content/docs/v1/install.md` | `/docs/v1/install/` |

With `latest_at_root = false` every version keeps its segment (`/docs/v2/install/`, `/docs/v1/install/`) and `/docs/` becomes a redirect stub to the latest version's root, unless you author your own `content/docs/_index.md`, which then keeps that URL.

The URL segment is the version **name**, not the directory basename: `name = "2.x"` with `path = "docs/v2"` publishes at `/docs/2.x/…` when it is not at root. Version directories may also sit at the top level (`content/v2/…`), in which case the latest version *is* the site root.

Notes:

- With `latest_at_root = true` do not also author `content/docs/_index.md`: it claims the same `/docs/` URL as the latest version's root and the build reports a duplicate output path (the authored file wins, the version root is not written).
- `[permalinks]` rules and `slug` apply to the published path (`docs/install.md`), not the source path.
- An explicit `path = "…"` in front matter wins outright, exactly as it does for languages. A custom path is not prefixed, so keep them distinct across versions.
- Everything under a version directory is versioned: page bundles, assets, `_index.md` cascades and `[[content.generate]]` output whose target path falls inside it.

### Multilingual

Languages and versions combine: the language prefix comes first, the version after. `content/docs/v1/install.ko.md` renders at `/ko/docs/v1/install/`, and `foo.ko.md` files inside a version directory behave exactly as they do elsewhere (translations, hreflang, per-language menus).

## Template Variables

### page.version

`nil` for unversioned pages (so `{% if page.version %}` is the guard), otherwise:

| Property | Type | Description |
|----------|------|-------------|
| `.name` | String | Version name (`"v2"`) |
| `.label` | String | Display label (`"2.x (latest)"`) |
| `.latest` | Bool | Is this the latest version |
| `.url` | String | Root URL of the version in the page's language (`/docs/`, `/ko/docs/v1/`) |

### page.version_links

One entry per configured version, in config order. These are the switcher rows. Empty for unversioned pages.

| Property | Type | Description |
|----------|------|-------------|
| `.name` | String | Version name |
| `.label` | String | Display label |
| `.latest` | Bool | Is the latest version |
| `.url` | String | The **same page** in that version when it exists, else that version's root |
| `.exists` | Bool | Whether the counterpart page exists (`false` → `url` is the version root) |
| `.current` | Bool | Whether this row is the page's own version |

Counterparts are matched by path relative to the version root, in the same language: `docs/v1/install.md` ↔ `docs/v2/install.md`, `docs/v1/install.ko.md` ↔ `docs/v2/install.ko.md`. A `render = false` counterpart does not count as existing.

### versions (global)

Available on every page of a versioned site. It is a list (`{% for v in versions %}`) of `{name, label, latest, url}` entries whose `url` is each version's root in the current page's language, plus:

| Property | Description |
|----------|-------------|
| `versions.latest` | The latest version entry |
| `versions.all` | The same list as a plain array |
| `versions.size` | Number of versions |

Like `page.url`, every URL above is site-relative, so prefix it with `{{ base_url }}` (or `{{ base_path }}`) in links so [subpath deployments](/start/config/#base-url) work.

## Version Switcher Example

```jinja
{% if page.version %}
<details class="version-switch">
  <summary aria-label="Switch documentation version">
    {{ page.version.label }}
    {% if not page.version.latest %}<span class="badge">old</span>{% endif %}
  </summary>
  <ul>
    {% for v in page.version_links %}
    <li>
      <a href="{{ base_url }}{{ v.url }}"
         {% if v.current %}class="current" aria-current="page"{% endif %}
         {% if not v.exists %}title="This page does not exist in {{ v.label }} — opens the {{ v.label }} start page"{% endif %}>
        {{ v.label }}{% if v.latest %} (latest){% endif %}
      </a>
    </li>
    {% endfor %}
  </ul>
</details>

{% if not page.version.latest %}
<div class="version-banner">
  You are reading the {{ page.version.label }} documentation.
  {% for v in page.version_links %}{% if v.latest %}
  <a href="{{ base_url }}{{ v.url }}">{% if v.exists %}Read this page in {{ v.label }}{% else %}Go to the {{ v.label }} docs{% endif %}</a>
  {% endif %}{% endfor %}
</div>
{% endif %}
{% endif %}
```

A site-wide entry point that does not depend on the current page:

```jinja
<a href="{{ base_url }}{{ versions.latest.url }}">Docs ({{ versions.latest.label }})</a>
<select onchange="location.href=this.value">
  {% for v in versions %}
  <option value="{{ base_url }}{{ v.url }}">{{ v.label }}</option>
  {% endfor %}
</select>
```

## Scoping Rules

Every version is its own tree; nothing leaks across the boundary:

| Surface | Behavior |
|---------|----------|
| `page.lower` / `page.higher` | The reading order is built per `{language, version}`. The last v1 page has no "next"; it never jumps into v2. |
| `page.ancestors` (breadcrumbs) | Stop at the version root. An unversioned `docs/_index.md` is not an ancestor of `docs/v1/…`. |
| `get_section()`, `section.pages`, `section.subsections` | A version root is not a subsection or page of its unversioned parent; listings inside a version only see that version. |
| Menus (`get_menu`) | Config `[[menus.*]]` entries appear everywhere. Front-matter `menus = […]` registrations from a versioned page appear only in that version's menus; unversioned pages additionally see the **latest** version's registrations. |
| Related posts | Never cross a version boundary. |
| Taxonomies | Term pages collect from unversioned content plus the latest version (`taxonomies = "latest"`, the default). Set `taxonomies = "all"` to list every version. |

Series are not version-aware: a `series` shared by a v1 and a v2 page groups them together.

## SEO & Discovery

### Canonical and noindex

Pages of an older version emit a canonical link to their **latest counterpart** when it exists (self-canonical otherwise) and, with `noindex_old = true` (default), a `<meta name="robots" content="noindex">` right after it. Both come out of `{{ canonical_tag }}`, so templates that already print it need no change; `seo.canonical_url` follows the same rule and `seo.noindex` exposes the flag.

```html
<link rel="canonical" href="https://example.com/docs/install/">
<meta name="robots" content="noindex">
```

Latest-version pages self-canonicalize as usual. Paginated listings keep self-canonicalizing (`page/2/` of an old section is not `page/2/` of the new one). `hreflang_tags` are unaffected, since they link translations of the same version.

### Discovery surfaces

| Surface | Switch | Default |
|---------|--------|---------|
| `search.json` | `[versions] search` | latest only |
| `sitemap.xml` | `[versions] search` (same switch) | latest only |
| RSS / Atom (main, section, per-language) | `[versions] feeds` | latest only |
| Taxonomy term pages | `[versions] taxonomies` | latest only |
| `llms.txt` / `llms-full.txt` | — | always latest only |

Unversioned pages always pass. With `search = "all"` every record in `search.json` carries a `version` field (the version name) so a client can filter results to the version being read:

```js
const current = document.documentElement.dataset.version; // e.g. from data-version="{{ page.version.name }}"
const hits = results.filter((r) => !r.version || r.version === current);
```

## Build Cache, Serve and Doctor

- `[versions]` is part of the config hash and version membership is part of the page-set fingerprint, so `hwaro build --cache` rebuilds what changes when you move a file between version directories, add a counterpart (the other version's `version_links` flips `exists`) or change the switches.
- `hwaro serve` builds versioned sites like any other; edits inside a version directory are picked up incrementally.
- `hwaro doctor` reports `version-path-missing` for a `[[versions.list]]` entry whose directory is absent.

## Not Included

- Redirect rules for URLs that exist only in the latest version (an old-version 404 is a plain 404).
- Version-aware series.
- The `docs` scaffold is unchanged; add `[versions]` to a generated site by hand using the snippet above.

## See Also

- [Multilingual](/features/multilingual/) — the language layer versions compose with
- [Data Model](/templates/data-model/) — every `page.*` and global variable
- [SEO](/features/seo/) — canonical, robots and sitemap details
- [Configuration](/start/config/) — full `config.toml` reference

---

Title: Integrations
URL: https://hwaro.hahwul.com/integrations/
Source: content/integrations/_index.md
Language: en

Hwaro is built to play well with the rest of your toolchain, especially AI
coding agents. The classified error codes, `--json` output, and `AGENTS.md`
generation all exist so an agent can drive Hwaro reliably.

This section collects drop-in integrations.

## In This Section

- **[Agent Skills](/integrations/skills/)** — installable `SKILL.md` files that
  teach Claude Code, Cursor, OpenCode, Codex, and other skill-aware agents how
  to operate the Hwaro CLI and how to design great Hwaro sites.

---

Title: Agent Skills
URL: https://hwaro.hahwul.com/integrations/skills/
Source: content/integrations/skills.md
Language: en

Hwaro ships two [Agent Skills](https://github.com/hahwul/hwaro/tree/main/skills),
self-contained `SKILL.md` files that teach a skill-aware AI agent how to work
with Hwaro. Once installed, the agent loads the relevant skill automatically
when it detects a Hwaro task.

| Skill | What it teaches |
|-------|-----------------|
| **`hwaro`** | Operating the CLI: scaffolding (`init`), content (`new`), preview (`serve`), production builds (`build`), and the `doctor`/`tool`/`deploy` subcommands. Emphasizes the agent-safe output contract: `--json`, `--quiet`, `NO_COLOR`, and the classified `HWARO_E_*` error/exit codes, plus safe `config.toml` and Crinja template edits. |
| **`hwaro-design`** | Designing and restyling a site. It **reads your brief, declares a one-line Design Read, and sets three design dials** (asking questions only when your intent is ambiguous), then produces distinctive, production-grade design within Hwaro's Crinja templates and CSS-variable token system, under a strict anti-slop discipline and a mechanical pre-flight check that filter out generic AI aesthetics. |

## Install with `npx skills`

The [`skills` CLI](https://www.npmjs.com/package/skills) is the easiest way to
install and keep skills up to date. Adding the repo installs **both** Hwaro
skills (`hwaro` and `hwaro-design`).

```bash
# Add to the current project — prompts you to pick the agent (.claude/skills, .cursor/, …)
npx skills add hahwul/hwaro

# Install globally for every project
npx skills add hahwul/hwaro -g

# Target a specific agent (e.g. Claude Code)
npx skills add hahwul/hwaro -a claude-code

# Non-interactive — good for CI
npx skills add hahwul/hwaro -g -a claude-code -y
```

Update or remove later by skill name:

```bash
npx skills update hwaro hwaro-design
npx skills remove hwaro hwaro-design
```

## Install manually

If you would rather not use `npx`, copy the files straight from the repository.
For **Claude Code** the target path is `~/.claude/skills/<name>/SKILL.md`:

```bash
# hwaro — the CLI skill
mkdir -p ~/.claude/skills/hwaro
curl -o ~/.claude/skills/hwaro/SKILL.md \
  https://raw.githubusercontent.com/hahwul/hwaro/main/skills/hwaro/SKILL.md

# hwaro-design — the design skill
mkdir -p ~/.claude/skills/hwaro-design
curl -o ~/.claude/skills/hwaro-design/SKILL.md \
  https://raw.githubusercontent.com/hahwul/hwaro/main/skills/hwaro-design/SKILL.md
```

Other agents use different skill directories (for example `.cursor/` or a
project-local `skills/` folder). Check your agent's documentation for the
correct location.

## What the skills cover

### `hwaro` — driving the CLI

- **When it triggers:** any Hwaro task, or a directory with `config.toml` plus
  `content/` and `templates/`.
- **Output contract:** prefer `--json` and branch on the classified exit codes
  (`HWARO_E_USAGE`, `HWARO_E_CONFIG`, `HWARO_E_TEMPLATE`, `HWARO_E_CONTENT`, …)
  instead of scraping human-readable text.
- **Workflows:** `init` scaffolds, `new` + archetypes, the `serve` live-reload
  dev loop, production `build` (`--minify`, `--cache`, `--base-url`, env
  overrides), `doctor` / `tool validate` / `tool check-links`, content tools,
  `tool platform`, and `deploy`.
- **Safe edits:** TOML config rules and Crinja template gotchas (`| safe`, nil
  guards, `url_for`/`asset` for URLs), plus a verify-by-exit-code loop.

### `hwaro-design` — designing the site

- **Design Read first:** reads your brief and declares a one-line design
  direction plus three dials (`DESIGN_VARIANCE` / `MOTION_INTENSITY` /
  `VISUAL_DENSITY`) before writing any CSS. It asks a short, focused question
  round only when your intent is ambiguous, and runs a full taste
  interview only when you ask for one, so the result reflects **your** taste
  rather than a default.
- **Anti-slop discipline:** an extensive list of hard bans on the signatures of
  AI-generated design (em-dashes in page copy, eyebrow-label overuse, repeated
  section layouts, hero-overflow, fake screenshots built from `<div>`s,
  AI-purple gradients, decorative dots and locale strips, "Jane Doe" demo
  content) plus layout, copy-density, and imagery rules, all enforced by a
  mechanical pre-flight checklist before anything is declared done.
- **Hwaro mechanics:** Crinja template structure, the three CSS-delivery options
  (inline, `[auto_includes]`, the `[assets]` pipeline), the shared `light-dark()`
  design-token vocabulary all built-in scaffolds theme through (light and dark
  come automatically; retheme by overriding the token pairs), responsive images
  via `resize_image`, and static-site motion via CSS scroll-driven animations
  and `IntersectionObserver`, with no framework required.

## Prerequisite

Install the Hwaro CLI so the agent can actually run builds and previews. See
[Installation](/start/installation/). A skill is only as useful as the binary it
drives.

The `hwaro` skill complements your project's `AGENTS.md`: the skill is portable
guidance that travels with the agent across any Hwaro project, while `AGENTS.md`
(generated by [`hwaro tool agents-md`](/start/tools/agents-md/)) carries
project-specific conventions. Agents should read `AGENTS.md` first, since it can
override the skill's defaults.

## Authoring tips

Both skills live under [`skills/`](https://github.com/hahwul/hwaro/tree/main/skills)
in the Hwaro repository. When contributing:

- Write for **agent interaction patterns** (what to run, when, and how to
  recover) rather than duplicating the full CLI/template reference (link to
  these docs instead).
- Keep the `description` front matter precise: it is what the agent reads to
  decide *when* to load the skill.
- Open a pull request on [GitHub](https://github.com/hahwul/hwaro).

## See Also

- [CLI Reference](/start/cli/) — every command and flag the `hwaro` skill drives.
- [AGENTS.md](/start/tools/agents-md/) — per-project instructions for AI agents.
- [Templates](/templates/) — the data model, functions, and filters the design skill builds on.

---

Title: Hwaro 문서
URL: https://hwaro.hahwul.com/ko/
Source: content/index.ko.md
Language: ko

Hwaro(화로)는 Crystal로 만든 빠르고 가벼운 정적 사이트 생성기입니다.

---

Title: 배포
URL: https://hwaro.hahwul.com/ko/deploy/
Source: content/deploy/_index.ko.md
Language: ko

Hwaro 사이트는 어떤 정적 호스팅 서비스에도 배포할 수 있습니다.

## 프로덕션 빌드

```bash
hwaro build
```

`public/`에 정적 파일이 생성됩니다. 필요하면 출력을 압축(minify)합니다:

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

보수적인 최적화만 수행합니다. HTML 주석과 줄 끝 공백을 제거하고 JSON/XML 공백을 줄이며, 코드 블록과 콘텐츠 구조는 모두 그대로 유지됩니다.

`static/`의 모든 파일은 `public/`으로 복사되어 함께 배포됩니다. `.well-known/security.txt`, `.domains` 같은 숨김 dot 경로도 포함되며, 콜드 빌드와 `--cache`/증분 빌드에서 동일하게 동작합니다. `.DS_Store`, `.git/` 같은 OS·에디터·VCS 잔여 파일은 자동으로 걸러집니다. 조정 방법은 [설정](/ko/start/config/#정적-파일) 문서의 정적 파일 항목을 참고합니다.

> **`hwaro serve` 출력은 절대 배포하지 마세요.** 개발 서버는 전용 디렉터리 `.hwaro/serve/`에 빌드하고(`public/`은 건드리지 않습니다), 모든 링크에 개발용 `base_url`(예: `http://127.0.0.1:3000`)을 박아 넣으며, 그 디렉터리에 `.hwaro-dev` 마커를 찍습니다. `hwaro deploy`는 마커가 있는 소스 디렉터리를 거부합니다. 이 에러를 만나면 `hwaro build`를 실행해 새로 빌드한 출력을 배포하세요.

## 기본 절차

1. 사이트 빌드: `hwaro build`
2. `public/` 디렉터리를 호스트에 업로드 (또는 `hwaro deploy` 사용)
3. 도메인 설정

## 내장 배포 명령

Hwaro에는 설정해 둔 타깃으로 배포하는 `hwaro deploy` 명령이 내장되어 있습니다:

```bash
hwaro deploy              # 첫 번째로 설정된 타깃에 배포
hwaro deploy s3           # 이름으로 특정 타깃에 배포
hwaro deploy s3 backup    # 여러 타깃에 배포
hwaro deploy --dry-run    # 변경 사항 미리 보기
```

타깃 설정, 매처, 옵션 전체는 [배포 설정](/ko/deploy/config/)을 참고합니다.

## 플랫폼 가이드

플랫폼별 배포 절차는 아래 가이드에서 단계별로 안내합니다.

---

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

Cloudflare Pages에 Hwaro 사이트를 배포해 전 세계에 빠르게 서비스합니다.

## 빠른 시작

### 설정 파일 생성

```bash
hwaro tool platform cloudflare
```

프로젝트 설정과 사이트 버킷 구성이 담긴 `wrangler.toml`이 생성됩니다.

### 대시보드로 배포

1. [Cloudflare Dashboard](https://dash.cloudflare.com) > **Workers & Pages**로 이동
2. **Create application** > **Pages** > **Connect to Git** 클릭
3. 저장소 선택
4. 빌드 설정 입력:
   - **Build command**: `hwaro build`
   - **Build output directory**: `public`
5. **Save and Deploy** 클릭

### Wrangler CLI로 배포

```bash
# Wrangler 설치
npm install -g wrangler

# 사이트 빌드
hwaro build

# 배포
wrangler pages deploy public --project-name my-site
```

## 수동 설정

직접 설정하려면 Cloudflare Pages 대시보드에서 다음 값을 지정합니다:

| 설정 | 값 |
|---------|-------|
| Build command | `hwaro build` |
| Build output directory | `public` |

또는 `wrangler.toml`을 작성합니다:

```toml
name = "my-site"
compatibility_date = "2024-01-01" # 배포 시점의 날짜 사용

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

## 리다이렉트

Cloudflare Pages는 출력 디렉터리의 `_redirects` 파일을 사용합니다. 페이지 별칭(alias)에 대한 리다이렉트 규칙을 `static/_redirects`에 작성합니다:

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

별칭은 페이지 프론트 매터에 정의합니다:

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

`hwaro tool platform cloudflare`로 생성한 `wrangler.toml`에는 이 리다이렉트 목록이 주석으로 포함되어 있어 `static/_redirects`로 그대로 복사하면 됩니다.

## 커스텀 도메인

1. **Workers & Pages** > 프로젝트 > **Custom domains**로 이동
2. **Set up a custom domain** 클릭
3. DNS 설정 안내를 따라 진행
4. `config.toml`의 `base_url` 갱신:

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

## 프리뷰 배포

Cloudflare Pages는 브랜치에 푸시할 때마다 프리뷰 배포를 자동 생성합니다. 프리뷰 URL은 `<branch>.<project>.pages.dev` 형식을 따릅니다.

## 함께 보기

- [platform](/ko/start/tools/platform/) — 플랫폼 설정 생성기 상세 옵션
- [CLI](/ko/start/cli/#tool) — tool 명령 전체
- 다른 플랫폼: [Netlify](/ko/deploy/netlify/) | [Vercel](/ko/deploy/vercel/) | [GitHub Pages](/ko/deploy/github-pages/)

---

Title: Codeberg Pages
URL: https://hwaro.hahwul.com/ko/deploy/codeberg-pages/
Source: content/deploy/codeberg-pages/index.ko.md
Language: ko

[Codeberg Pages](https://codeberg.page/)에 Hwaro 사이트를 배포합니다. Codeberg의 Forgejo 인스턴스가 뒷받침하는 무료 정적 호스팅입니다.

## Codeberg Pages 동작 방식

Codeberg는 정적 사이트를 두 가지 방식으로 제공합니다:

- **사용자/조직 사이트** — 계정 아래 **`pages`**라는 이름의 저장소. Codeberg는 이 저장소의 *기본 브랜치*를 `https://USERNAME.codeberg.page/`에서 제공합니다.
- **프로젝트 사이트** — 그 외 모든 저장소. **`pages`**라는 이름의 브랜치를 `https://USERNAME.codeberg.page/REPO/`에서 제공합니다.

이 구분이 중요합니다. 프로젝트 사이트는 `pages` *브랜치*에 푸시하고, 사용자 사이트는 `pages` *저장소*의 *기본 브랜치*(보통 `main`)에 푸시합니다. 아래 워크플로는 프로젝트 사이트를 기본값으로 하되 `PAGES_BRANCH` 변수를 노출해, 사용자 사이트는 한 줄만 바꾸면 되도록 했습니다.

## 사전 준비

- Codeberg 계정
- Codeberg 저장소 (사용자 사이트는 `pages`, 프로젝트 사이트는 아무 저장소나)
- `write:repository` 스코프를 가진 Codeberg 액세스 토큰 (Settings → Applications → Generate new token)

## 방법 1: Forgejo Actions (권장)

Codeberg는 GitHub Actions와 호환되는 [Forgejo Actions](https://forgejo.org/docs/latest/user/actions/)를 지원합니다. Forgejo Actions는 저장소별로 직접 켜야 하는 옵트인 기능이므로, 워크플로를 실행하기 전에 **Settings → Actions**에서 활성화합니다.

> Forgejo는 하위 호환을 위해 `.gitea/workflows/` 경로도 허용하지만, 업스트림이 권장하는 경로이자 Hwaro가 생성하는 경로는 `.forgejo/workflows/`입니다.

### 워크플로 생성

```bash
hwaro tool platform codeberg-pages
```

다음 내용이 `.forgejo/workflows/deploy.yml`에 생성됩니다:

```yaml
---
name: Hwaro Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: docker
    container:
      image: ghcr.io/hahwul/hwaro:latest
    env:
      # 프로젝트 사이트: "pages" (기본값). 사용자/조직 사이트("pages"라는
      # 이름의 저장소): 기본 브랜치(예: "main")로 바꿉니다.
      PAGES_BRANCH: pages
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build site
        run: hwaro build

      - name: Deploy to Codeberg Pages
        env:
          CODEBERG_TOKEN: ${{ secrets.CODEBERG_TOKEN }}
        run: |
          cd public
          git init -b "$PAGES_BRANCH"
          git config user.name  "${{ github.actor }}"
          git config user.email "${{ github.actor }}@noreply.codeberg.org"
          git add -A
          git commit -m "Deploy: $(date -u +'%Y-%m-%dT%H:%M:%SZ')"
          git push --force \
            "https://${{ github.actor }}:$CODEBERG_TOKEN@codeberg.org/${{ github.repository }}.git" \
            "$PAGES_BRANCH"
```

> **브랜치 히스토리는 보존되지 않습니다.** 실행할 때마다 새로 `git init`한 뒤 강제 푸시하므로, 게시 브랜치는 게시 전용 산출물로 취급합니다. 소스는 `main`(또는 개발에 쓰는 브랜치)에 두고, `pages` 브랜치는 직접 수정하지 않습니다.

### 사용자 사이트와 프로젝트 사이트

기본값 `PAGES_BRANCH: pages`는 **프로젝트 사이트**(아무 저장소, `USERNAME.codeberg.page/REPO/`에서 제공)를 대상으로 합니다. 저장소 이름이 정확히 `pages`인 **사용자/조직 사이트**라면 브랜치를 기본 브랜치로 바꿉니다:

```yaml
    env:
      PAGES_BRANCH: main   # `pages` 저장소의 기본 브랜치
```

### 토큰 시크릿 추가

1. 저장소 **Settings → Actions → Secrets**로 이동
2. `CODEBERG_TOKEN`이라는 이름으로 새 시크릿 추가
3. `write:repository` 스코프를 가진 Codeberg 액세스 토큰 붙여넣기

### Base URL 설정

`config.toml`을 수정합니다:

```toml
# 사용자/조직 사이트 ("pages"라는 이름의 저장소)
base_url = "https://USERNAME.codeberg.page"

# 프로젝트 사이트 (그 외 저장소)
base_url = "https://USERNAME.codeberg.page/REPO"
```

`main`에 푸시하면 워크플로가 자동으로 빌드하고 배포합니다.

## 방법 2: `hwaro deploy`로 배포

로컬 머신에서 배포하려면 간단한 셸 스크립트를 호출하는 `[[deployment.targets]]` 항목으로 연결합니다.

`scripts/deploy-codeberg.sh`를 작성합니다:

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

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

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

cd "$TMPDIR"
git init -b "$PAGES_BRANCH"
git add -A
git commit -m "Deploy to Codeberg Pages"
git push --force "$REMOTE_URL" "$PAGES_BRANCH"

rm -rf "$TMPDIR"
```

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

`config.toml`에 타깃을 추가합니다:

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

이제 빌드하고 배포합니다:

```bash
hwaro build
hwaro deploy codeberg-pages

# 배포하지 않고 미리 보기
hwaro deploy codeberg-pages --dry-run

# 사용자 사이트 (`pages` 대신 기본 브랜치에 푸시)
PAGES_BRANCH=main hwaro deploy codeberg-pages
```

방법 1과 마찬가지로 스크립트는 새로 초기화한 저장소를 강제 푸시하므로, 브랜치 히스토리는 보존되지 않습니다.

## 방법 3: 브랜치 수동 배포

```bash
hwaro build

cd public
git init -b pages
git add -A
git commit -m "Deploy"
git push --force https://codeberg.org/USERNAME/REPO.git pages
```

사용자 사이트(`pages` 저장소)라면 `init`과 `push` 명령의 `pages` 자리에 기본 브랜치 이름(예: `main`)을 넣습니다.

## 커스텀 도메인

Codeberg Pages는 `.domains` 파일과 DNS 레코드로 커스텀 도메인을 지원합니다. 정확한 최신 내용은 [공식 Codeberg 문서](https://docs.codeberg.org/codeberg-pages/using-custom-domain/)를 참고합니다.

> **점(`.`)이 들어간 저장소 이름은 지원되지 않습니다.** 커스텀 도메인을 붙일 계획이라면 저장소 이름에 `-`나 `_`를 사용합니다.

### 1. `.domains` 파일 추가

제공되는 브랜치의 루트에 `.domains` 파일을 두고 도메인을 한 줄에 하나씩 나열합니다. **첫 줄이 대표(canonical) 도메인**이며, 나머지 도메인은 모두 첫 줄로 301 리다이렉트됩니다. 빈 줄과 `#` 주석을 쓸 수 있습니다.

```
www.example.org
example.org
```

`static/.domains`에 두면 Hwaro가 빌드할 때마다 `public/`으로 복사합니다:

```
static/
└── .domains
```

Hwaro는 콜드 빌드든 `--cache`/증분 빌드든 매번 `static/`의 숨김 dot 경로를 그대로 `public/`에 복사하므로, `static/.domains`는 항상 게시 브랜치에 포함됩니다. 자세한 내용은 [설정](/ko/start/config/#정적-파일) 문서의 정적 파일 항목을 참고합니다.

### 2. DNS 설정

아래 세 가지 옵션 중 **하나만** 선택합니다.

**옵션 A — CNAME (권장, 가장 간단).** 도메인을 다음 이름 중 하나로 연결합니다:

| 사이트 유형     | CNAME 대상                              |
|---------------|-------------------------------------------|
| 개인 사이트 | `USERNAME.codeberg.page`                  |
| 프로젝트 사이트  | `REPO.USERNAME.codeberg.page`             |
| 커스텀 브랜치 | `BRANCH.REPO.USERNAME.codeberg.page`      |

CNAME은 *호스트네임 전체*를 위임하므로, 이 옵션에서는 같은 이름으로 이메일(MX)을 운영할 수 없습니다.

**옵션 B — ALIAS + TXT.** DNS 제공자가 `ALIAS`(또는 `ANAME`) 레코드를 지원하는 경우:

| 타입  | 이름 | 값                                |
|-------|------|--------------------------------------|
| ALIAS | @    | `codeberg.page`                      |
| TXT   | @    | `REPO.USERNAME.codeberg.page` (사용자 사이트는 `USERNAME.codeberg.page`) |

**옵션 C — A + AAAA + TXT.** 제공자가 ALIAS를 지원하지 않거나, 존이 DNSSEC를 사용하는 경우(`codeberg.page` CNAME과 호환되지 않음) 사용합니다:

| 타입 | 이름 | 값                                |
|------|------|--------------------------------------|
| A    | @    | `217.197.84.141`                     |
| AAAA | @    | `2a0a:4580:103f:c0de::2`             |
| TXT  | @    | `REPO.USERNAME.codeberg.page` (사용자 사이트는 `USERNAME.codeberg.page`) |

> Codeberg는 이 IP를 가끔 교체하므로, 사용하기 전에 [Codeberg Pages 문서](https://docs.codeberg.org/codeberg-pages/using-custom-domain/)에서 최신 IP를 확인합니다.

존에 CAA 레코드가 있다면 Codeberg가 TLS 인증서를 발급할 수 있도록 Let's Encrypt를 허용하는 항목을 추가합니다:

```
@   CAA   0 issue "letsencrypt.org"
```

### 3. `base_url` 갱신

```toml
base_url = "https://www.example.org"
```

## 문제 해결

### 워크플로가 실행되지 않을 때

- 저장소 **Settings → Actions**에서 Forgejo Actions가 활성화되어 있는지 확인합니다
- 워크플로 파일이 `.forgejo/workflows/deploy.yml`(또는 `.gitea/workflows/deploy.yml`)에 커밋되어 있는지 확인합니다

### 푸시가 401/403으로 실패할 때

- `CODEBERG_TOKEN` 시크릿 값과 토큰에 `write:repository` 스코프가 아직 있는지 다시 확인합니다
- 토큰은 계정에 귀속되므로, 해당 계정에 대상 저장소 푸시 권한이 있는지 확인합니다

### 배포된 사이트가 404일 때

- Codeberg Pages는 첫 푸시 후 게시까지 1~2분 걸릴 수 있습니다
- 프로젝트 사이트라면 브랜치 이름이 정확히 `pages`인지 확인합니다
- 사용자 사이트라면 저장소 이름이 정확히 `pages`이고 `PAGES_BRANCH`가 기본 브랜치와 일치하는지 확인합니다
- `base_url`이 게시된 URL과 일치하는지(끝 슬래시 없음) 확인합니다

### 커스텀 도메인이 HTTPS로 연결되지 않을 때

- `.domains` 파일이 게시 브랜치 루트에 있는지 확인합니다
- CAA 레코드가 있다면 `letsencrypt.org`가 허용되어 있는지 확인합니다
- DNS 전파 후 인증서 발급까지 몇 분 기다립니다

## 함께 보기

- [배포 설정](/ko/deploy/config/) — 타깃 설정과 매처
- [CLI](/ko/start/cli/) — 배포 명령 옵션 전체
- [Codeberg Pages 문서](https://docs.codeberg.org/codeberg-pages/) — 업스트림 레퍼런스
- 다른 플랫폼: [GitHub Pages](/ko/deploy/github-pages/) | [GitLab CI](/ko/deploy/gitlab-ci/) | [Netlify](/ko/deploy/netlify/) | [Cloudflare Pages](/ko/deploy/cloudflare-pages/)

---

Title: 배포 설정
URL: https://hwaro.hahwul.com/ko/deploy/config/
Source: content/deploy/config.ko.md
Language: ko

`hwaro deploy` 명령이 사용할 배포 타깃을 `config.toml`에 설정합니다.

## 전역 옵션

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| target | string | — | 기본으로 배포할 타깃 이름 |
| source_dir | string | "public" | 빌드된 사이트가 있는 디렉터리 |
| confirm | bool | false | 배포 전 확인 프롬프트 표시 |
| dry_run | bool | false | 실제 변경 없이 배포될 내용만 표시 |
| force | bool | false | 변경 사항이 없어도 강제로 배포 |
| max_deletes | int | 256 | 파일 삭제 개수의 안전 한도(음수를 지정하면 한도 해제) |

`max_deletes`는 **내장** `file://` 동기화에만 적용됩니다. 커맨드 타깃
(`s3://`, `gs://`, `az://`, 또는 명시적 `command`)은 외부 도구가 자체
플래그로 삭제하므로 hwaro가 미리 개수를 셀 수 없습니다.

소스 디렉터리가 비어 있거나, `include`/`exclude`가 아무 파일도 고르지
못했는데 대상에는 파일이 남아 있는 경우에도 배포를 거부합니다. 이 조합은
대부분 "사이트를 빌드하지 않았다"는 뜻이고, 그대로 진행하면 대상을 통째로
지우게 됩니다. 의도적으로 비우려면 `--force`를 넘기세요. `{source}`를 쓰지 않는
`command` 타깃은 소스를 읽지 않으므로 제외됩니다.

`.hwaro-dev` 마커가 있는 소스 디렉터리도 거부합니다. 이 마커는 해당
디렉터리가 `hwaro serve` 출력이라는 뜻이며, 모든 링크에 개발 서버의
`base_url`(예: `http://127.0.0.1:3000`)이 박혀 있습니다. `hwaro build`를
실행해 그 출력을 배포하세요. 우회 플래그는 없습니다(마커 파일을 직접
지우는 것이 의도적인 탈출구입니다).

`workers`는 앞으로를 위해 파싱만 하고 적용하지 않습니다. 내장 동기화는
순차적으로 복사하고, 커맨드 타깃은 각자 동시성을 관리합니다. 값을 지정하면
경고가 출력됩니다.

## 타깃

배포 타깃을 하나 이상 정의합니다:

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

[[deployment.targets]]
name = "s3"
url = "s3://my-bucket"
# 자동 생성: 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/*'"
# 사용자 지정 명령이 자동 생성보다 우선합니다
```

**URL 스킴별 자동 생성 명령:**

| 스킴 | 명령 | 필요 도구 |
|--------|---------|----------|
| `file://` | 내장 디렉터리 동기화 | — |
| `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 <container> [--destination <path>]` | Azure CLI |

`az://container/sub/dir` 형태의 URL에서는 경로가 컨테이너 내부의 `--destination` 접두사가 됩니다.

`command` 필드를 지정하면 항상 자동 생성보다 우선합니다.

URL 스킴으로 시작하는 값은 로컬 경로로 취급하지 않습니다. 따라서 슬래시를
하나 빠뜨린 오타(`s3:/bucket`)는 `s3:`라는 디렉터리를 조용히 만드는 대신
지원하지 않는 스킴 오류로 실패합니다. `include`, `exclude`,
`strip_index_html`은 내장 `file://` 동기화에만 적용되며, 커맨드 타깃에서는
외부 도구가 소스 트리 전체를 받기 때문에 경고만 출력합니다.

**로컬 디렉터리 동기화와 심볼릭 링크.** 내장 동기화는 모든 쓰기를 대상
디렉터리 안에 가둡니다. 파일이나 디렉터리가 있어야 할 자리의 링크는 실제
파일/디렉터리로 교체하고, 소스에 대응하는 항목이 없는 링크는 제거합니다.
어느 쪽도 링크를 따라가서 읽거나 지우지 않으므로, 대상 밖에 있는 내용은
절대 건드리지 않습니다.

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| name | string | — | 타깃 식별자(고유해야 합니다. 중복되면 경고하고 첫 번째만 사용) |
| url | string | — | 대상 URL (`file://`, `s3://`, `gs://`, `az://`) |
| path | string | — | 로컬 디렉터리로 배포할 때 쓰는 `url` 별칭 (`path = "~/public"`, `~`는 확장됨) |
| include | string | — | 포함할 파일의 글롭 패턴 |
| exclude | string | — | 제외할 파일의 글롭 패턴 |
| strip_index_html | bool | false | URL에서 `index.html` 제거 |
| command | string | — | 사용자 지정 명령(자동 생성보다 우선) |

사용자 지정 명령에서는 플레이스홀더를 사용할 수 있습니다:

| 플레이스홀더 | 설명 |
|-------------|-------------|
| `{source}` | 소스 디렉터리(기본값: `public`) |
| `{url}` | 타깃 URL |
| `{target}` | 타깃 이름 |

## 매처

패턴 매처로 파일별 배포 설정을 지정합니다:

```toml
[[deployment.matchers]]
pattern = "^.+\\.html$"
force = true
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| pattern | string | — | 파일 경로에 매칭할 정규식 패턴 |
| force | bool | false | 대상에 동일한 파일이 있어도 매칭된 파일을 항상 복사 |
| cache_control | string | — | 예약됨 — 내장 동기화에서는 적용되지 않음(아래 참고) |
| content_type | string | — | 예약됨 — 내장 동기화에서는 적용되지 않음(아래 참고) |
| gzip | bool | false | 예약됨 — 내장 동기화에서는 적용되지 않음(아래 참고) |

내장 동기화는 파일을 복사하고 외부 CLI를 실행할 뿐 오브젝트 스토어 API와 직접 통신하지 않으므로, 실제로 반영되는 옵션은 `force`뿐입니다. `cache_control`, `content_type`, `gzip`을 설정하면 경고가 출력됩니다. 헤더와 압축은 호스트나 CDN에서 설정합니다.

## 함께 보기

- [CLI](/ko/start/cli/) — 배포 명령줄 옵션 전체
- [배포 명령](/ko/features/deployment/) — 간단한 개요

---

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

Docker로 Hwaro 사이트를 배포합니다.

## 공식 이미지

공식 Docker 이미지는 `ghcr.io/hahwul/hwaro`에서 받을 수 있습니다.

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

## 멀티 스테이지 빌드

멀티 스테이지 빌드로 사이트를 빌드한 뒤 Nginx 같은 경량 웹 서버로 서비스할 수 있습니다.

프로젝트 루트에 `Dockerfile`을 만듭니다:

```dockerfile
# 1단계: 사이트 빌드
FROM ghcr.io/hahwul/hwaro:latest AS builder

WORKDIR /site
COPY . .

# 사이트 빌드
RUN hwaro build

# 2단계: Nginx로 서비스
FROM nginx:alpine

# 빌더 스테이지에서 빌드 결과 복사
COPY --from=builder /site/public /usr/share/nginx/html

# 80 포트 노출
EXPOSE 80

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

### 빌드 및 실행

```bash
# 이미지 빌드
docker build -t my-hwaro-site .

# 컨테이너 실행
docker run -d -p 8080:80 my-hwaro-site
```

`http://localhost:8080`에 접속해 사이트를 확인합니다.

## CLI 사용

Crystal이나 Hwaro를 로컬에 설치하지 않고도 Docker 이미지로 Hwaro 명령을 바로 실행할 수 있습니다.

```bash
# 사이트 빌드
docker run --rm -v $(pwd):/site -w /site ghcr.io/hahwul/hwaro build

# 대화형 셸
docker run --rm -it -v $(pwd):/site -w /site ghcr.io/hahwul/hwaro /bin/sh
```

## 함께 보기

- [배포 설정](/ko/deploy/config/) — 타깃 설정과 매처
- [CLI](/ko/start/cli/) — 빌드/배포 옵션 전체
- 다른 플랫폼: [GitHub Pages](/ko/deploy/github-pages/) | [Netlify](/ko/deploy/netlify/) | [Vercel](/ko/deploy/vercel/)

---

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

GitHub Pages에 Hwaro 사이트를 배포해 무료로 호스팅합니다.

## 사전 준비

- GitHub 저장소
- 빌드할 수 있는 Hwaro 사이트

## 방법 1: GitHub Actions (권장)

공식 [`hahwul/hwaro`](https://github.com/hahwul/hwaro) 액션을 사용하면 Hwaro를 직접 설치하지 않고도 빌드와 배포를 처리할 수 있습니다.

### 워크플로 생성

다음 명령으로 워크플로 파일을 자동 생성합니다:

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

또는 `.github/workflows/deploy.yml`을 직접 작성합니다:

```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 }}
```

### 액션 입력값

| 입력 | 설명 | 기본값 |
|-------|-------------|---------|
| `build_dir` | Hwaro 사이트가 있는 디렉터리 | `.` (저장소 루트) |
| `build_only` | 배포 없이 빌드만 수행 | `false` |
| `token` | 배포에 사용할 GitHub 토큰 | — |

Hwaro 사이트가 하위 디렉터리(예: `docs/`)에 있다면 `build_dir`를 지정합니다:

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

### OG 이미지 캐시

이 액션은 배포 사이에 OG 이미지를 자동으로 캐시합니다. 매 빌드 전에 `gh-pages` 브랜치에서 이전에 생성한 이미지를 복원하고 `--cache` 모드를 켭니다. 제목·설명·URL 같은 콘텐츠가 바뀌었거나 OG 설정이 갱신된 페이지만 이미지를 다시 생성하므로, 규모가 큰 사이트에서 빌드가 크게 빨라집니다.

### GitHub Pages 설정

1. 저장소 **Settings** → **Pages**로 이동
2. "Build and deployment"에서 **Deploy from a branch** 선택
3. `gh-pages` 브랜치와 `/ (root)` 폴더 선택
4. `main` 브랜치에 푸시하면 배포가 시작됩니다

### Base URL 설정

`config.toml`을 수정합니다:

```toml
# 사용자/조직 사이트 (username.github.io)
base_url = "https://username.github.io"

# 프로젝트 사이트 (username.github.io/repo)
base_url = "https://username.github.io/repo"
```

## 방법 2: `hwaro deploy`로 배포

배포 스크립트 `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
```

`config.toml`에 타깃을 추가합니다:

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

이제 빌드하고 배포합니다:

```bash
hwaro build
hwaro deploy github-pages

# 배포하지 않고 미리 보기
hwaro deploy github-pages --dry-run
```

### GitHub Pages 설정

1. 저장소 **Settings** → **Pages**로 이동
2. "Build and deployment"에서 **Deploy from a branch** 선택
3. `gh-pages` 브랜치와 `/ (root)` 폴더 선택
4. **Save** 클릭

## 방법 3: 브랜치 수동 배포

```bash
hwaro build

# orphan 브랜치 생성
git checkout --orphan gh-pages

# 모든 파일 제거
git rm -rf .

# 빌드된 사이트 복사
cp -r public/* .

# 커밋 후 푸시
git add .
git commit -m "Deploy site"
git push origin gh-pages --force

# main 브랜치로 복귀
git checkout main
```

## 커스텀 도메인

### DNS 설정

`username.github.io`를 가리키는 CNAME 레코드를 추가합니다:

| 타입 | 이름 | 값 |
|------|------|-------|
| 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 |

### CNAME 파일 추가

`static/CNAME` 파일을 만듭니다:

```
www.yourdomain.com
```

### 설정 변경

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

### HTTPS 활성화

1. 저장소 **Settings** → **Pages**로 이동
2. **Enforce HTTPS** 체크

## 문제 해결

### 404 오류

- `base_url`이 GitHub Pages URL과 일치하는지 확인합니다
- CNAME 파일이 `static/` 디렉터리에 있는지 확인합니다
- 배포가 완료될 때까지 몇 분 기다립니다

### 에셋이 로드되지 않을 때

- `base_url` 끝에 슬래시가 없는지 확인합니다
- 에셋 경로가 `{{ base_url }}` 접두사를 사용하는지 확인합니다

### 빌드 실패

- Actions 로그에서 오류 메시지를 확인합니다
- `build_dir`가 올바른 디렉터리를 가리키는지 확인합니다

## 저장소 구조 예시

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

## 함께 보기

- [배포 설정](/ko/deploy/config/) — 타깃 설정과 매처
- [CLI](/ko/start/cli/) — 배포 명령 옵션 전체
- 다른 플랫폼: [GitLab CI](/ko/deploy/gitlab-ci/) | [Netlify](/ko/deploy/netlify/) | [Vercel](/ko/deploy/vercel/) | [Codeberg Pages](/ko/deploy/codeberg-pages/)

---

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

GitLab CI/CD로 Hwaro 사이트를 배포합니다.

## 빠른 시작

설정 파일을 자동 생성합니다:

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

## 설정

또는 저장소에 `.gitlab-ci.yml`을 직접 추가합니다:

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

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

이 설정은 공식 Hwaro Docker 이미지로 사이트를 빌드하고 `public` 디렉터리를 GitLab Pages에 배포합니다.

## 함께 보기

- [배포 설정](/ko/deploy/config/) — 타깃 설정과 매처
- [CLI](/ko/start/cli/) — 배포 명령 옵션 전체
- 다른 플랫폼: [GitHub Pages](/ko/deploy/github-pages/) | [Netlify](/ko/deploy/netlify/) | [Vercel](/ko/deploy/vercel/)

---

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

Netlify에 Hwaro 사이트를 배포하면 자동 빌드와 글로벌 CDN을 이용할 수 있습니다.

## 빠른 시작

### 설정 파일 생성

```bash
hwaro tool platform netlify
```

빌드 설정, 별칭(alias) 기반 리다이렉트, 캐시 헤더가 담긴 `netlify.toml`이 생성됩니다.

### Git으로 배포

1. 저장소를 GitHub, GitLab 또는 Bitbucket에 푸시
2. [Netlify](https://app.netlify.com)에서 **Add new site** > **Import an existing project** 클릭
3. 저장소 연결
4. Netlify가 `netlify.toml` 설정을 자동 감지
5. **Deploy site** 클릭

## 수동 설정

생성기 대신 직접 설정하려면 `netlify.toml`을 작성합니다:

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

[build.environment]
  # 필요한 환경 변수를 설정합니다
```

## 리다이렉트

`hwaro tool platform netlify`를 사용하면 프론트 매터에 정의한 페이지 별칭이 301 리다이렉트로 자동 포함됩니다:

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

생성 결과:

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

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

## 커스텀 도메인

1. **Site settings** > **Domain management**로 이동
2. **Add custom domain** 클릭
3. DNS 설정 안내를 따라 진행
4. `config.toml`의 `base_url` 갱신:

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

## 배포 프리뷰

Netlify는 풀 리퀘스트마다 배포 프리뷰를 자동 생성합니다. 프리뷰 빌드는 임시 URL을 사용하므로, 배포 컨텍스트에서 base URL을 재정의합니다:

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

`$DEPLOY_PRIME_URL`은 Netlify가 제공하는 환경 변수로, 고유한 프리뷰 URL이 담겨 있습니다(예: `https://deploy-preview-42--your-site.netlify.app`).

## 함께 보기

- [platform](/ko/start/tools/platform/) — 플랫폼 설정 생성기 상세 옵션
- [CLI](/ko/start/cli/#tool) — tool 명령 전체
- 다른 플랫폼: [Vercel](/ko/deploy/vercel/) | [Cloudflare Pages](/ko/deploy/cloudflare-pages/) | [GitHub Pages](/ko/deploy/github-pages/)

---

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

Vercel에 Hwaro 사이트를 배포합니다. 별도 설정 없이도 바로 배포됩니다.

## 빠른 시작

### 설정 파일 생성

```bash
hwaro tool platform vercel
```

빌드 설정, 별칭(alias) 기반 리다이렉트, 캐시 헤더가 담긴 `vercel.json`이 생성됩니다.

### Git으로 배포

1. 저장소를 GitHub, GitLab 또는 Bitbucket에 푸시
2. [Vercel](https://vercel.com)에서 **Add New** > **Project** 클릭
3. 저장소 가져오기
4. Vercel이 `vercel.json` 설정을 자동 감지
5. **Deploy** 클릭

## 수동 설정

직접 설정하려면 `vercel.json`을 작성합니다:

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

## 리다이렉트

`hwaro tool platform vercel`을 사용하면 프론트 매터에 정의한 페이지 별칭이 301 리다이렉트로 자동 포함됩니다:

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

생성 결과:

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

## 커스텀 도메인

1. **Settings** > **Domains**로 이동
2. 커스텀 도메인 추가
3. DNS 설정 안내를 따라 진행
4. `config.toml`의 `base_url` 갱신:

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

## 프리뷰 배포

Vercel은 프로덕션이 아닌 브랜치에 푸시할 때마다 프리뷰 배포를 자동 생성합니다. 추가 설정은 필요 없습니다.

## 함께 보기

- [platform](/ko/start/tools/platform/) — 플랫폼 설정 생성기 상세 옵션
- [CLI](/ko/start/cli/#tool) — tool 명령 전체
- 다른 플랫폼: [Netlify](/ko/deploy/netlify/) | [Cloudflare Pages](/ko/deploy/cloudflare-pages/) | [GitHub Pages](/ko/deploy/github-pages/)

---

Title: 기능
URL: https://hwaro.hahwul.com/ko/features/
Source: content/features/_index.ko.md
Language: ko

Hwaro는 플러그인 없이도 폭넓은 기능을 기본으로 제공합니다. 모든 기능은 `config.toml`에서 설정하며, 활성화하면 바로 동작합니다.

## 한눈에 보기

**SEO & 탐색** — 사이트맵, RSS/Atom 피드, robots.txt, OpenGraph, Twitter 카드, 구조화된 데이터(JSON-LD), 자동 생성 OG 이미지.

**콘텐츠** — 구문 강조, 검색 인덱스 생성, 페이지네이션, 마크다운 확장(각주, 작업 목록, 수식, mermaid), 시리즈, 관련 글, 이름 있는 내비게이션 메뉴.

**성능** — 증분 빌드, 대규모 사이트를 위한 스트리밍 빌드, 압축(minify)과 핑거프린트를 지원하는 에셋 파이프라인, 반응형 변형과 LQIP 플레이스홀더를 만드는 이미지 처리, 캐시 버스팅.

**파일 & 환경** — 환경 변수, 환경별 설정 오버라이드, CSS/JS 자동 인클루드, 로컬·원격 데이터, 콘텐츠 파일 게시.

**플랫폼** — 다국어 지원, 버전별 문서, 이미지 처리, PWA, AMP, 여러 대상으로의 기본 제공 배포.

---

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

Hwaro는 일반 페이지와 함께 콘텐츠의 AMP(Accelerated Mobile Pages) 버전을 자동으로 생성할 수 있습니다.

## 동작 방식

1. 일반 페이지를 먼저 렌더링합니다
2. 렌더링이 끝나면 Hwaro가 각 페이지의 HTML을 읽어 AMP 호환 버전을 만듭니다
3. AMP 페이지는 설정 가능한 경로 접두사(기본값: `/amp/`) 아래에 기록됩니다
4. 캐노니컬 페이지의 `<head>`에 `<link rel="amphtml">` 태그가 주입됩니다

## 설정

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | AMP 페이지 생성 활성화 |
| path_prefix | string | "amp" | AMP 페이지의 URL 접두사 |
| sections | array | [] | AMP를 생성할 섹션 (비워 두면 전체) |

## 변환 내용

AMP 변환기는 다음 변환을 자동으로 적용합니다:

| 원본 | AMP 버전 |
|----------|-------------|
| `<html>` | `<html amp>` |
| `<img>` | `<amp-img layout="responsive">` |
| `<video>` | `<amp-video layout="responsive">` |
| `<iframe>` | `<amp-iframe layout="responsive">` |
| `<script>` (인라인) | 제거 |
| `style="..."` 속성 | 제거 |
| `onclick` 핸들러 | 제거 |
| `loading="lazy"` 속성 | 제거 (AMP 요소는 자체 지연 로딩을 하며 이 속성을 허용하지 않음) |

추가로 다음이 주입됩니다:
- AMP 보일러플레이트 CSS
- AMP 런타임 스크립트 (`cdn.ampproject.org/v0.js`)
- 원본 페이지를 가리키는 `<link rel="canonical">`

## 출력 구조

`/posts/hello/` 페이지가 있을 때 출력은 다음과 같습니다:

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

## 섹션 필터링

기본적으로 AMP 페이지는 모든 섹션에 대해 생성됩니다. `sections`로 대상을 제한합니다:

```toml
[amp]
enabled = true
sections = ["posts", "blog"]   # 이 섹션들만 AMP 버전 생성
```

## 사용자 지정 경로 접두사

```toml
[amp]
enabled = true
path_prefix = "mobile"    # /amp/posts/hello/ 대신 /mobile/posts/hello/
```

## 함께 보기

- [설정](/ko/start/config/) — 전체 설정 레퍼런스
- [SEO](/ko/features/seo/) — 사이트맵, 피드, OpenGraph

---

Title: 에셋 파이프라인
URL: https://hwaro.hahwul.com/ko/features/asset-pipeline/
Source: content/features/asset-pipeline.ko.md
Language: ko

Hwaro에는 CSS와 JS 파일을 번들링·압축(minify)·핑거프린트해 프로덕션에 바로 쓸 수 있는 출력물을 만드는 에셋 파이프라인이 내장되어 있습니다.

## 기능

- **번들링** — 여러 CSS/JS 파일을 하나의 번들로 결합
- **압축** — 주석과 공백을 제거해 파일 크기 축소
- **핑거프린트** — 캐시 버스팅을 위한 콘텐츠 해시 파일명(예: `style.a1b2c3d4.css`)
- **템플릿 헬퍼** — `{{ asset(name="style.css") }}`가 핑거프린트된 경로로 해석

## 설정

`config.toml`에 `[assets]` 섹션을 추가합니다.

```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"]
```

번들 `files`에는 `.scss` 소스도 지정할 수 있습니다. `[sass]`가 활성화된 동안에는 [Sass/SCSS](/ko/features/sass/) 내장 컴파일러로 컴파일된 뒤 이어 붙고, 다른 CSS와 똑같이 압축·핑거프린트됩니다. 이런 번들은 출력이 올바른 타입으로 제공되도록 `.css` 확장자로 이름을 짓습니다.

| 옵션 | 타입 | 기본값 | 설명 |
|--------|------|---------|-------------|
| `enabled` | bool | `false` | 에셋 파이프라인 활성화 |
| `minify` | bool | `true` | CSS/JS 출력 압축 |
| `fingerprint` | bool | `true` | 파일명에 콘텐츠 해시 추가 |
| `source_dir` | string | `"static"` | 소스 파일이 있는 디렉터리 |
| `output_dir` | string | `"assets"` | 빌드 출력 내 출력 하위 디렉터리 |

### 번들 정의

`[[assets.bundles]]` 항목 하나가 출력 파일 하나를 정의합니다.

| 필드 | 타입 | 설명 |
|-------|------|-------------|
| `name` | string | 출력 파일명(예: `"main.css"`) |
| `files` | array | `source_dir` 기준 상대 경로의 소스 파일 |

파일은 나열한 순서대로 이어 붙입니다.

## 템플릿에서 사용

템플릿에서 번들된 에셋을 참조하려면 `asset()` 함수를 사용합니다.

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

핑거프린트가 활성화되어 있으면 해시가 붙은 경로로 해석됩니다.

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

에셋이 파이프라인 매니페스트에 없으면(예: 번들로 설정하지 않은 경우) `base_url` 아래의 경로를 그대로 반환합니다.

`asset`의 별칭으로 `asset_url`도 쓸 수 있습니다.

## 동작 방식

1. Initialize 단계에서 파이프라인이 `source_dir`의 소스 파일을 읽습니다
2. 각 번들에 나열된 파일을 순서대로 이어 붙입니다
3. `minify`가 활성화되어 있으면 CSS/JS별 압축을 적용합니다
4. `fingerprint`가 활성화되어 있으면 확장자 앞에 8자리 SHA-256 해시를 삽입합니다
5. 출력은 빌드 디렉터리의 `{output_dir}/{output_name}`에 기록됩니다
6. 원본 이름과 출력 경로를 매핑한 매니페스트가 템플릿 해석용으로 저장됩니다

### 압축

내장 압축기는 보수적이고 안전하게 동작합니다.

**CSS:**
- 주석 제거(`/* ... */`)
- 공백 축소
- `{`, `}`, `:`, `;`, `,` 주변 공백 제거
- `}` 앞의 불필요한 세미콜론 제거

**JS:**
- 문자열 밖의 한 줄 주석(`// ...`) 제거
- 여러 줄 주석(`/* ... */`) 제거
- 문자열 리터럴 보존(작은따옴표, 큰따옴표, 템플릿)
- 빈 줄 제거

더 강한 압축이 필요하면 [빌드 훅](/ko/features/build-hooks/)에서 `esbuild`나 `terser` 같은 외부 도구를 사용합니다.

## 예시

### 기본 CSS 번들

```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') }}">
```

### 여러 번들

```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"]
```

### 핑거프린트 없는 개발 설정

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

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

## 함께 보기

- [캐시 버스팅](/ko/features/cache-busting/) — 파이프라인을 거치지 않는 에셋을 위한 쿼리 스트링 기반 캐시 무효화
- [자동 인클루드](/ko/features/auto-includes/) — 정적 디렉터리의 CSS/JS 자동 로드
- [빌드 훅](/ko/features/build-hooks/) — 빌드 전후 외부 도구 실행

---

Title: 자동 인클루드
URL: https://hwaro.hahwul.com/ko/features/auto-includes/
Source: content/features/auto-includes.ko.md
Language: ko

자동 인클루드는 지정한 정적 디렉터리의 CSS/JS 파일을 모든 페이지에 자동으로 불러옵니다. 에셋 파일을 하나하나 템플릿에 추가할 필요가 없어집니다.

## 설정

`config.toml`에서 활성화합니다.

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | 자동 인클루드 활성화 |
| dirs | array | [] | 스캔할 `static/` 아래 디렉터리 |

## 디렉터리 구조

CSS와 JS 파일을 `static/`의 하위 디렉터리에 둡니다.

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

파일은 `static/{dir}/**/*.css`와 `static/{dir}/**/*.js` 패턴으로 재귀적으로 스캔됩니다.

## 파일 순서

파일은 **알파벳 순서**로 포함됩니다. 로드 순서를 제어하려면 숫자 접두사를 사용합니다.

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

## 템플릿 변수

### CSS만

CSS 파일만 포함하려면 `<head>`에 넣습니다.

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

### JS만

JS 파일만 포함하려면 `</body>` 앞에 넣습니다.

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

### 전체 에셋

CSS와 JS를 한꺼번에 포함합니다.

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

| 변수 | 설명 |
|----------|-------------|
| auto_includes_css | CSS 파일용 `<link>` 태그 |
| auto_includes_js | JS 파일용 `<script>` 태그 |
| auto_includes | CSS와 JS 태그 결합 |

## 생성되는 출력

위 예시 디렉터리 구조라면 템플릿 변수는 다음을 생성합니다.

**`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>
```

## 전체 템플릿 예시

```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>
```

## 팁

- **역할 분리**: 페이지 로딩을 최적화하려면 `auto_includes_css`는 `<head>`에, `auto_includes_js`는 `</body>` 앞에 둡니다.
- **여러 디렉터리**: 스캔할 디렉터리를 여러 개 나열할 수 있습니다. 각 디렉터리는 독립적으로 스캔됩니다.
- **겹치는 디렉터리 피하기**: 결과는 중복 제거되지 않습니다. 설정된 두 디렉터리(예: `assets`와 `assets/css`)에서 모두 도달할 수 있는 파일은 디렉터리마다 한 번씩 포함되므로, 겹치지 않는 디렉터리만 나열합니다.
- **정적 파일 전용**: 자동 인클루드는 `static/` 디렉터리를 스캔합니다. `content/`의 파일은 포함되지 않습니다.

## 함께 보기

- [설정](/ko/start/config/) — 설정 전체 참조
- [구문 강조](/ko/features/syntax-highlighting/) — Highlight.js 에셋 포함
- [데이터 모델](/ko/templates/data-model/) — 에셋 템플릿 변수

---

Title: 빌드 훅
URL: https://hwaro.hahwul.com/ko/features/build-hooks/
Source: content/features/build-hooks.ko.md
Language: ko

빌드 훅으로 빌드 전후에 사용자 정의 셸 명령을 실행할 수 있습니다. 의존성 설치, 데이터 전처리, 에셋 최적화, 배포 트리거 같은 작업에 유용합니다.

## 설정

`config.toml`에 훅을 정의합니다.

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| hooks.pre | array | [] | 빌드 **전에** 실행할 명령 |
| hooks.post | array | [] | 빌드 **후에** 실행할 명령 |

## 동작 방식

### 빌드 전 훅

빌드 전 훅은 콘텐츠 처리가 시작되기 **전에** 실행됩니다. 다음 작업에 적합합니다.

- 의존성 설치
- 에셋 컴파일(TypeScript, Tailwind/PostCSS 등. SCSS는 [Sass/SCSS](/ko/features/sass/) 내장 컴파일러로 처리합니다)
- 데이터 가져오기 스크립트 실행
- 콘텐츠 전처리

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

빌드 전 훅이 **실패**하면(0이 아닌 상태로 종료) 빌드가 **중단**됩니다. 의존성이 빠졌거나 에셋이 깨진 상태로 빌드되는 일을 막기 위해서입니다.

### 빌드 후 훅

빌드 후 훅은 사이트가 출력 디렉터리에 생성된 **후에** 실행됩니다. 다음 작업에 적합합니다.

- 이미지 최적화
- 에셋 압축(minify)
- 검색 인덱스 생성(예: Pagefind)
- 사이트 배포
- 검증 검사 실행

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

빌드 후 훅이 **실패**하면 경고만 표시되고 빌드 자체는 실패로 처리되지 **않습니다**. 생성된 사이트는 그대로 유지됩니다.

## 실행 순서

명령은 정의된 순서대로 **차례로** 실행됩니다.

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

출력:

```
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 모드

빌드 훅은 `hwaro serve` 중에도 실행되지만, **전체 재빌드**에서만 실행됩니다.

- 서버 시작 시 **최초 빌드**에서 훅이 실행됩니다
- **전체 재빌드**에서 다시 실행됩니다. `config.toml` 변경, 파일 추가나 삭제, `data/` 아래 파일 변경이 여기에 해당합니다
- **부분 재빌드에서는 건너뜁니다** — 기존 콘텐츠나 템플릿 파일을 수정하면 영향받는 페이지만 다시 렌더링하고 훅 명령은 다시 실행하지 않습니다
- 설정 변경은 자동으로 반영됩니다. `config.toml`의 `hooks.pre`나 `hooks.post`를 수정하면 다음 재빌드부터 새 명령이 적용됩니다

덕분에 저장 후 새로고침이 빠르게 유지됩니다. 서버가 켜져 있는 동안 훅의 결과물을 갱신해야 한다면 `config.toml`을 건드리거나 `hwaro serve`를 재시작해 전체 재빌드를 유도하세요.

### 재빌드 루프

감시 대상 디렉터리(`content/`, `templates/`, `static/`, `data/`, `i18n/`)나 `config.toml` 자체에 쓰는 훅은 자기 결과물을 다시 감시자에게 흘려보냅니다. 무해한 경우는 하와로가 알아서 처리합니다. 빌드가 이미 읽은 것과 **같은 바이트**를 다시 쓰는 실행(변하지 않은 응답을 받아오는 `curl -o data/team.json`, 동일한 결과물을 다시 내보내는 번들러, `config.toml`의 시각만 건드리는 훅)은 무한 재빌드로 이어지지 않고 잦아듭니다. 파일 위치에 따라 그 변경은 아예 무시되거나, 훅을 다시 실행하지 않는 부분 재빌드로 흡수됩니다.

반면 다음 두 가지는 감시자 입장에서 실제 변경이므로 매번 재빌드를 유발합니다.

- 실행할 때마다 **다른 바이트**를 쓰는 경우. 타임스탬프, 빌드 카운터, 비결정적 번들 해시 등
- 실행할 때마다 감시 대상 디렉터리에 파일을 **만들었다 지우는** 경우

결과물을 결정적으로 만들거나, 감시하지 않는 위치에 쓰세요(`.hwaro/`는 무시되며, 위에 나열한 디렉터리 밖도 마찬가지입니다).

## 활용 사례

### TypeScript 컴파일

```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"
]
```

### API에서 데이터 가져오기

가장 흔한 경우, 즉 GET 요청 하나의 페이로드를 `site.data`에 넣는 것이라면 훅이 필요 없습니다. `config.toml`에 [`[[data.remote]]` 소스](/ko/features/remote-data/)를 선언하면 Hwaro가 빌드당 한 번 가져오며, 디스크 캐싱과 명시적인 오류 처리가 내장되어 있습니다.

가져오기가 요청 하나로 끝나지 않을 때는 여전히 사전 빌드 훅이 맞는 도구입니다. `load_data()`는 디스크만 읽습니다. 따라서 원격 데이터는 빌드 전에 `data/`로 내려받아 정적으로 굽습니다. `data/` 아래 파일은 그대로 `site.data`로 노출됩니다.

```toml
[build]
hooks.pre = ["curl -sfL https://api.example.com/team -o data/team.json"]
```

```jinja
{% for member in site.data.team %}
  <li>{{ member.name }}</li>
{% endfor %}
```

`curl -f`는 HTTP 오류에서 0이 아닌 코드로 종료하므로, 데이터가 빠진 사이트를 배포하는 대신 빌드가 중단됩니다. 페이지네이션, 인증 헤더, 응답 가공처럼 요청 하나로 끝나지 않는 작업은 스크립트로 분리해 호출하세요.

```toml
[build]
hooks.pre = ["./scripts/fetch-data.sh"]
```

오프라인에서도 동일한 빌드를 원한다면 내려받은 파일을 커밋하고, 항상 최신 데이터를 원한다면 `.gitignore`에 추가하세요.

### Pagefind 검색

빌드 후 클라이언트 사이드 검색 인덱스를 생성합니다.

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

### 이미지 최적화

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

### 사용자 정의 배포 스크립트

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

### 전체 파이프라인 예시

```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!'"
]
```

## 오류 처리

| 훅 유형 | 실패 시 |
|-----------|------------|
| 빌드 전 | ❌ 빌드 **중단** — 콘텐츠를 처리하지 않음 |
| 빌드 후 | ⚠️ 경고 표시 — 생성된 사이트는 유지 |

필수 준비 작업(빌드 전)은 반드시 성공해야 하고, 선택적 최적화 작업(빌드 후)은 빌드 출력을 막지 않도록 설계되어 있습니다.

## 팁

- **훅은 빠르게 유지**: 느린 훅은 `hwaro serve` 중 전체 재빌드마다 실행됩니다. 캐싱이나 조건부 실행을 고려합니다.
- **복잡한 작업은 스크립트로**: 여러 단계가 필요하면 셸 스크립트를 작성해 훅에서 호출합니다: `hooks.pre = ["./scripts/setup.sh"]`
- **의존성 확인**: 도구를 실행하기 전에 `command -v`로 사용 가능 여부를 확인합니다:
  ```bash
  command -v npx >/dev/null 2>&1 && npx pagefind --site public
  ```
- **자동 인클루드와 조합**: 빌드 전 훅으로 CSS/JS를 컴파일하고, [자동 인클루드](/ko/features/auto-includes/)가 자동으로 불러오게 합니다.

## 함께 보기

- [설정](/ko/start/config/) — 설정 전체 참조
- [자동 인클루드](/ko/features/auto-includes/) — CSS/JS 자동 로드
- [검색](/ko/features/search/) — Pagefind 빌드 후 훅으로 만드는 검색 인덱스
- [배포](/ko/deploy/) — 배포 옵션

---

Title: 캐시 버스팅
URL: https://hwaro.hahwul.com/ko/features/cache-busting/
Source: content/features/cache-busting.ko.md
Language: ko

캐시 버스팅은 로컬에서 제공되는 CSS/JS 리소스 URL에 `?v=<hash>` 쿼리 파라미터를 자동으로 붙입니다. 에셋 내용이 바뀌면 브라우저가 최신 버전을 다시 받아오므로, 오래된 캐시 파일이 쓰이는 일을 막습니다.

## 동작 방식

Hwaro는 로컬 CSS/JS 파일의 MD5 콘텐츠 해시를 계산해 앞 8자를 쿼리 파라미터로 붙입니다. 해시는 파일 내용이 실제로 바뀔 때만 달라지므로, 진짜 업데이트가 있기 전까지 브라우저는 캐시를 계속 사용합니다.

```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">
```

## 콘텐츠 해시 vs 타임스탬프

Hwaro는 빌드 타임스탬프가 아니라 **콘텐츠 기반 해시**를 사용합니다. 따라서:

- 파일이 바뀌지 않으면 빌드를 반복해도 해시가 그대로 유지되어 불필요한 캐시 무효화가 없습니다
- CSS/JS 파일 내용이 수정되면 해시가 즉시 바뀝니다
- 파일이 같으면 다른 빌드 머신에서도 같은 해시가 나옵니다

## CDN URL은 수정하지 않음

캐시 버스팅은 **로컬** 리소스 URL에만 적용됩니다. CDN URL(예: cdnjs.cloudflare.com)은 경로에 이미 버전 번호가 들어 있으므로 수정하지 않습니다.

```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">
```

## 적용 대상 템플릿 변수

캐시 버스팅은 다음 템플릿 변수에 적용됩니다.

| 변수 | 설명 |
|----------|-------------|
| `highlight_css` | 구문 강조 CSS(로컬만) |
| `highlight_js` | 구문 강조 JS(로컬만) |
| `highlight_tags` | 구문 강조 CSS + JS 결합(로컬만) |
| `auto_includes_css` | 자동 인클루드된 CSS 파일 |
| `auto_includes_js` | 자동 인클루드된 JS 파일 |
| `auto_includes` | 자동 인클루드된 CSS + JS 결합 |

## 캐시 버스팅 비활성화

캐시 버스팅은 기본으로 활성화되어 있습니다. 끄려면 `--skip-cache-busting` 플래그를 사용합니다.

```bash
# 캐시 버스팅 없이 빌드
hwaro build --skip-cache-busting

# 캐시 버스팅 없이 serve
hwaro serve --skip-cache-busting
```

파일명 해싱이나 CDN 퍼지 등 다른 방법으로 캐시 무효화를 관리한다면 유용합니다.

## 함께 보기

- [구문 강조](/ko/features/syntax-highlighting/) — Highlight.js 설정
- [자동 인클루드](/ko/features/auto-includes/) — CSS/JS 자동 로드
- [CLI](/ko/start/cli/) — 명령줄 옵션

---

Title: 콘텐츠 파일
URL: https://hwaro.hahwul.com/ko/features/content-files/
Source: content/features/content-files.ko.md
Language: ko

`content/` 디렉터리에 놓인 마크다운 이외 파일을 출력 디렉터리로 자동 게시할 수 있습니다. 이미지, PDF처럼 콘텐츠 옆에 함께 두는 에셋을 다룰 때 유용합니다.

## 설정

`config.toml`에서 콘텐츠 파일 게시를 활성화합니다:

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| allow_extensions | array | [] | 게시할 파일 확장자 |
| disallow_extensions | array | [] | 제외할 파일 확장자 |
| disallow_paths | array | [] | 제외할 경로의 글롭(glob) 패턴 |

## 동작 방식

콘텐츠 파일 게시가 활성화되면 Hwaro는 `content/`의 마크다운 이외 파일을 디렉터리 구조를 유지한 채 출력 디렉터리로 복사합니다.

### 예시

```
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
```

파일은 대응하는 출력 경로로 그대로 복사되며, `content/` 접두사는 자동으로 제거됩니다.

## 확장자 매칭

### 허용 목록

`allow_extensions`에 있는 확장자의 파일만 게시됩니다:

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

확장자는 정규화되므로 `"jpg"`와 `".jpg"` 둘 다 쓸 수 있습니다.

### 차단 목록

`disallow_extensions`로 특정 확장자를 제외합니다:

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

차단 목록이 허용 목록보다 우선합니다.

### 경로 제외

글롭 문법으로 경로 패턴에 맞는 파일을 제외합니다:

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

| 패턴 | 매칭 대상 |
|---------|---------|
| `drafts/**` | `content/drafts/` 아래 모든 파일 |
| `**/_*` | 밑줄로 시작하는 모든 파일 |
| `private/**` | `content/private/` 아래 모든 파일 |

경로는 `content/` 디렉터리 기준 상대 경로로 매칭됩니다.

## 콘텐츠 파일 참조

### 마크다운에서

같은 위치에 둔 파일은 상대 경로로 참조합니다:

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

[Download Resume](resume.pdf)

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

### 템플릿에서

페이지 번들에서는 함께 둔 에셋을 `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 %}
```

## 콘텐츠 파일 vs 정적 파일

| 항목 | 콘텐츠 파일 (`content/`) | 정적 파일 (`static/`) |
|---------|---------------------------|--------------------------|
| 콘텐츠와 같은 위치에 배치 | ✅ 가능 | ❌ 불가 |
| 설정 필요 | ✅ 필요 | ❌ 불필요 (기본으로 복사, 불필요 파일은 필터링) |
| 확장자 필터링 | ✅ 지원 | ❌ 미지원 |
| 경로 필터링 | ✅ 지원 (`disallow_paths`) | ✅ 지원 (`[static]` `exclude`) |
| 적합한 용도 | 페이지별 에셋 | 사이트 전역 에셋 |

특정 페이지에 속한 에셋(스크린샷, 다이어그램, 첨부 파일)에는 **콘텐츠 파일**을, 사이트 전역 에셋(CSS, JS, 로고, 파비콘)에는 **정적 파일**을 사용합니다. 불필요한 파일이나 특정 경로를 제외하는 방법은 [설정](/ko/start/config/#정적-파일)의 `[static]` 섹션을 참고하면 됩니다.

## 팁

- **페이지 번들**: 구성을 깔끔하게 유지하려면 [페이지 번들](/ko/writing/pages/#에셋-코로케이션)을 사용합니다. `index.md`와 그 에셋을 한 디렉터리에 함께 둡니다.
- **이미지 포맷**: 일반적인 웹 이미지 포맷을 포함합니다: `["jpg", "jpeg", "png", "gif", "svg", "webp"]`.
- **보안**: `disallow_paths`로 소스 파일이나 초안이 게시되지 않게 막습니다.
- **최소한만 허용**: 실제로 필요한 확장자만 허용합니다. 대용량 소스 파일이 실수로 게시되는 일을 막을 수 있습니다.

## 함께 보기

- [이미지 처리](/ko/features/image-processing/) — 자동 이미지 리사이즈
- [페이지](/ko/writing/pages/#에셋-코로케이션) — 페이지 번들과 에셋 배치
- [섹션](/ko/writing/sections/#에셋-코로케이션) — 섹션 에셋
- [설정](/ko/start/config/) — 전체 설정 레퍼런스

---

Title: 콘텐츠 생성
URL: https://hwaro.hahwul.com/ko/features/content-generation/
Source: content/features/content-generation.ko.md
Language: ko

`[[content.generate]]`는 `site.data` 배열의 각 레코드(로컬 `data/` 파일 또는 [원격 데이터 소스](/ko/features/remote-data/))를 실제 콘텐츠 페이지로 만듭니다. 규칙 하나로 레코드 배열을 가리키고 어떤 필드가 슬러그·제목·본문이 될지 지정하면, 레코드마다 페이지가 빌드됩니다.

생성된 페이지는 **일급 콘텐츠**입니다. 작성한 파일과 같은 지점에서 빌드에 합류하므로 섹션 목록, `[permalinks]` 패턴, 택소노미, 피드, 검색 인덱스, 사이트맵, OG 이미지, 출력 포맷이 `content/`의 파일과 완전히 동일하게 적용됩니다. `[[data.remote]]`와 조합하면 헤드리스 CMS나 임의의 JSON API로 섹션 전체를 만들 수 있습니다. 커밋할 파일도, 스크립트도 필요 없습니다.

## 빠른 시작

```toml
# config.toml
[[content.generate]]
source = "products.items"       # site.data.products.items — 배열이어야 함
section = "products"            # 페이지는 /products/<slug>/ 에 생성
slug = "sku"                    # 레코드 필드 (슬러그화됨)
title = "name"                  # 레코드 필드
body = "description_md"         # 마크다운을 담은 레코드 필드
date = "released"               # 선택
description = "{{ item.name }} — {{ item.price }} USD"  # 선택, 템플릿
taxonomies = { tags = "categories" }                    # 선택
```

```json
// data/products.json
{"items": [
  {"sku": "blue-widget", "name": "Blue Widget", "price": 19.99,
   "released": "2024-01-15", "description_md": "A **blue** widget.",
   "categories": ["gadgets"]}
]}
```

빌드 한 번이면 `/products/blue-widget/`이 생깁니다. `page.html`로 렌더링되고, `products` 섹션 목록에 나오고, `/tags/gadgets/`에 등록되고, RSS 피드·검색 인덱스·사이트맵에 포함됩니다.

## 필드 또는 템플릿

모든 값 스펙(`slug`, `title`, `body`, `date`, `description`, 각 `taxonomies` 값)은 두 형태 중 하나입니다.

- **필드 이름** — `slug = "sku"`는 레코드의 `sku` 필드를 읽습니다. 점 표기로 중첩 객체에 접근합니다: `slug = "meta.id"`. 존재하지 않는 필드는 **레코드 번호와 실제 존재하는 키를 알려주는 하드 에러**입니다. 오타가 조용히 잘못된 페이지를 만드는 일은 없습니다. 필드가 존재하지만 `null`/`""`이면 선택 값은 그냥 생략됩니다(날짜 없는 레코드도 괜찮습니다). 필수 스펙(`slug`, `title`)에서는 에러입니다.
- **템플릿** — `{{` 또는 `{%`를 포함한 스펙은 레코드를 `item`으로 바인딩한 템플릿으로 렌더링되며, hwaro의 모든 필터를 쓸 수 있습니다: `slug = "{{ item.sku | slugify }}"`, `title = "{{ item.name | title }}"`.

## 규칙 레퍼런스

| 키 | 필수 | 의미 |
|-----|------|------|
| `source` | 예 | `site.data` 아래 배열의 점 표기 경로(`"products"` 또는 `"products.items"`). 키가 없거나 테이블이면 무엇이 발견됐는지 알려주는 하드 에러입니다. |
| `section` | 예 | 대상 섹션. 페이지 경로가 `<section>/<slug>.md`가 되므로 기존 `content/<section>/_index.md`가 목록을 만들고 해당 섹션의 `[permalinks]` 패턴이 적용됩니다. |
| `slug` | 예 | 각 페이지의 슬러그를 만드는 필드/템플릿. 결과는 슬러그화되며, 규칙 내·규칙 간 중복은 두 레코드를 모두 지목하는 하드 에러입니다. |
| `title` | 예 | 페이지 제목을 만드는 필드/템플릿. |
| `body` | 아니요 | 페이지의 **마크다운** 본문을 만드는 필드/템플릿. 숏코드, 구문 강조, 모든 마크다운 확장이 적용됩니다. |
| `body_template` | 아니요 | `body`의 대안: `templates/`의 템플릿 파일을 레코드를 `item`으로 렌더링합니다. 출력은 마크다운입니다. `body`와 상호 배타적입니다. |
| `date` | 아니요 | 페이지 날짜를 만드는 필드/템플릿. 작성 front matter와 같은 형식을 받습니다. 미래 날짜는 작성 콘텐츠와 똑같이 기본 빌드에서 제외됩니다. |
| `description` | 아니요 | 페이지 설명 필드/템플릿. |
| `taxonomies` | 아니요 | `taxonomy = "스펙"` 테이블. 배열 필드는 모든 원소를 term으로, 스칼라는 하나를, `null`/`""`은 아무것도 기여하지 않습니다. |

## 템플릿에서 레코드 전체 쓰기

템플릿은 소스 레코드 전체를 `page.extra.item`으로 보므로 필드마다 규칙에 매핑할 필요가 없습니다.

```html
{% if page.synthesized %}
<p class="price">{{ page.extra.item.price }} USD</p>
<p class="stock">{{ page.extra.item.inventory.count }}</p>
{% endif %}
```

`page.synthesized`는 생성된 페이지에서만 `true`이므로 공유 템플릿에서 분기할 수 있습니다. 작성 페이지에는 `item`이 없으니 `page.extra.item` 접근은 이 플래그로 가드하세요.

## 충돌

경로가 겹치면 항상 작성한 파일이 이깁니다. `content/products/red-widget.md`가 있으면 같은 슬러그의 생성 페이지는 경고와 함께 버려지며, 반대 방향은 없습니다. 두 레코드가 같은 슬러그를 만들면 두 레코드를 지목하며 빌드가 실패합니다.

## 리빌드와 캐시

생성 콘텐츠는 데이터와 함께 움직입니다. `data/` 파일 수정(또는 `[[data.remote]]` 페이로드 변경)은 config 수정과 같은 방식으로 캐시된 페이지를 무효화하고, `hwaro serve`는 데이터 수정 시 리빌드합니다. `build --cache`에서 생성 페이지는 항상 다시 렌더링됩니다. 지문을 만들 소스 파일이 없기 때문입니다. 작성 페이지의 캐시 동작은 그대로입니다.

레코드가 데이터에서 사라지면 다음 빌드의 페이지 집합에서도 사라지지만, `--cache`/보존된 출력 디렉터리에는 이전에 쓴 파일이 남을 수 있습니다(작성 파일의 이름 변경과 동일). 전체 빌드(`hwaro build`)는 깨끗한 출력 디렉터리에서 시작합니다.

## 툴링

`hwaro tool list`는 생성 페이지를 출처와 함께 보여줍니다(`products/blue-widget.md ← data.products.items`). 로컬 데이터 파일 기준으로 계획하며, 아직 가져오지 않은 `[[data.remote]]` 키 기반 규칙은 행 대신 안내 문구로 표시됩니다. 빌드를 실행하면 구체화됩니다.

## 에러

모든 실패는 규칙, 레코드(1부터, 데이터 순서), 고칠 내용을 지목합니다.

```
Error [HWARO_E_CONTENT]: [[content.generate]] "products.items": record #37: missing field 'skuu' (available: categories, name, price, released, sku).
```

`source`가 없거나 배열이 아닌 규칙도 빌드를 실패시킵니다. 오타가 조용히 0개의 페이지를 생성하는 일은 없어야 합니다.

---

Title: 배포 명령
URL: https://hwaro.hahwul.com/ko/features/deployment/
Source: content/features/deployment.ko.md
Language: ko

Hwaro에는 빌드된 사이트를 설정된 대상으로 동기화하는 `hwaro deploy` 명령이 내장되어 있습니다. 로컬 디렉터리, 클라우드 스토리지는 물론 사용자 지정 명령으로 어떤 도구든 연결할 수 있습니다.

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

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

[[deployment.targets]]
name = "s3"
url = "s3://my-bucket"
# command 없이 URL 스킴에서 자동 생성 (aws CLI 필요)

[[deployment.targets]]
name = "gcs"
url = "gs://my-bucket"
# 자동 생성 (gsutil 필요)
```

**지원 URL 스킴:**

| 스킴 | 자동 명령 | 필요 도구 |
|--------|-------------|----------|
| `file://` | 로컬 디렉터리 동기화 | — |
| `s3://` | `aws s3 sync` | AWS CLI |
| `gs://` | `gsutil -m rsync` | Google Cloud SDK |
| `az://` | `az storage blob sync` | Azure CLI |

언제든 `command` 필드에 명령을 직접 지정해 완전히 제어할 수도 있습니다.

```bash
hwaro deploy              # 기본 대상으로 배포
hwaro deploy --target s3  # 특정 대상으로 배포
hwaro deploy --dry-run    # 변경 사항 미리 보기
```

전체 설정(대상, 매처, 옵션)과 플랫폼별 가이드는 [배포](/ko/deploy/) 섹션을 참고합니다.

---

Title: 환경별 설정
URL: https://hwaro.hahwul.com/ko/features/env-config/
Source: content/features/env-config.ko.md
Language: ko

Hwaro는 환경별 설정 재정의를 지원합니다. 개발, 스테이징, 프로덕션마다 다른 설정을 쓸 수 있습니다.

## 동작 방식

1. 기본 설정을 `config.toml`에서 불러옵니다
2. 환경이 지정되면 `config.<env>.toml`을 불러와 그 위에 병합합니다
3. 중첩 섹션(테이블)은 깊은 병합(deep merge)되고, 최상위 값과 말단 값은 교체됩니다

## 환경 지정

`--env` 플래그나 `HWARO_ENV` 환경 변수를 사용합니다.

```bash
# CLI 플래그로
hwaro build --env production
hwaro serve --env development

# 환경 변수로
HWARO_ENV=staging hwaro build

# CLI 플래그가 HWARO_ENV보다 우선
```

## 파일 구조

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

## 예시

**config.toml** (기본):

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

[sitemap]
enabled = true
changefreq = "weekly"

[search]
enabled = true
```

**config.production.toml** (재정의):

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

[sitemap]
changefreq = "daily"
```

`hwaro build --env production`을 실행하면 다음과 동일한 설정이 됩니다.

```toml
title = "My Blog"                     # 기본 설정에서
base_url = "https://myblog.com"       # production이 재정의

[sitemap]
enabled = true                        # 기본 설정에서(깊은 병합)
changefreq = "daily"                  # production이 재정의

[search]
enabled = true                        # 기본 설정에서(변경 없음)
```

## 깊은 병합 동작

하위 테이블은 통째로 교체되지 않고 재귀적으로 병합됩니다. 바꾸고 싶은 값만 지정하면 됩니다.

| 기본 | 재정의 | 결과 |
|------|----------|--------|
| `[sitemap] enabled = true, changefreq = "weekly"` | `[sitemap] changefreq = "daily"` | `[sitemap] enabled = true, changefreq = "daily"` |

최상위 스칼라와 배열은 병합되지 않고 교체됩니다.

| 기본 | 재정의 | 결과 |
|------|----------|--------|
| `title = "Base"` | `title = "Prod"` | `title = "Prod"` |

## 환경 변수

환경별 설정 파일에서도 [환경 변수](/ko/features/env-variables/) 치환을 사용할 수 있습니다.

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

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

## 활용 사례

### 환경별로 다른 base URL

```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"
```

### 프로덕션에서만 기능 활성화

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

[feeds]
enabled = true
```

### 환경별로 다른 애널리틱스

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

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

## 함께 보기

- [설정](/ko/start/config/) — 설정 전체 참조
- [환경 변수](/ko/features/env-variables/) — 설정과 템플릿의 환경 변수 치환
- [CLI](/ko/start/cli/) — 명령줄 옵션

---

Title: 환경 변수
URL: https://hwaro.hahwul.com/ko/features/env-variables/
Source: content/features/env-variables.ko.md
Language: ko

Hwaro는 `config.toml`과 템플릿 양쪽에서 환경 변수 치환을 지원합니다. CI/CD 파이프라인, 시크릿 관리, 개발자별 설정 같은 동적 구성이 가능합니다.

## 설정 치환

`config.toml`의 환경 변수는 TOML 파싱 전에 해석됩니다.

### 문법

| 패턴 | 설명 |
|---------|-------------|
| `${VAR}` | `VAR`의 값으로 치환 |
| `$VAR` | 동일(축약형) |
| `${VAR:-default}` | `VAR`가 없거나 비어 있으면 `default` 사용 |

### 예시

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

# 축약형
title = "$SITE_TITLE"

# 기본값
description = "${SITE_DESC:-My awesome site}"

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

기본값이 없는 미설정 변수는 그대로 남고 빌드 시 경고가 출력됩니다.

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

## 템플릿 함수

템플릿 안에서 환경 변수를 읽으려면 `env()` 함수를 사용합니다.

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

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| name | String | 변수 이름 |
| default | String? | 미설정 시 대체값(선택) |

변수가 설정되어 있지 않고 기본값도 없으면 빈 문자열이 반환되고 경고가 기록됩니다.

### 예시

**조건부 애널리틱스 스니펫:**

```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 엔드포인트:**

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

## 활용 사례

### CI/CD 파이프라인

배포 환경별로 base URL을 지정합니다.

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

### 시크릿 관리

API 키와 트래킹 ID를 버전 관리 바깥에 둡니다.

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

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

### 개발자별 설정

`config.toml`을 수정하지 않고도 각 개발자가 자기 셸 환경에서 값을 로컬로 재정의할 수 있습니다.

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

## 함께 보기

- [설정](/ko/start/config/) — 설정 전체 참조
- [함수](/ko/templates/functions/) — 템플릿 함수 전체 목록

---

Title: Git 메타데이터
URL: https://hwaro.hahwul.com/ko/features/git-info/
Source: content/features/git-info.ko.md
Language: ko

빌드마다 각 콘텐츠 파일의 커밋 이력을 한 번 읽어 템플릿과 SEO 출력에 노출합니다. Hugo의 `enableGitInfo`와 같은 기능입니다. `[git]`을 켜면 프론트 매터에 `updated`가 없는 페이지는 최신 커밋 시각을 받으므로 사이트맵 `<lastmod>`, 피드 `<updated>`, JSON-LD `dateModified`가 파일이 실제로 바뀐 시점을 반영합니다.

## 설정

`config.toml`에서 옵트인합니다.

```toml
[git]
enabled = true
use_lastmod = true   # 프론트 매터에 updated가 없으면 page.updated ← 최신 커밋
use_date = false     # 프론트 매터에 date가 없으면 page.date ← 첫 커밋
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | `content/` 파일의 git 메타데이터 수집 |
| use_lastmod | bool | true | 프론트 매터에 `updated`가 없으면 파일의 최신 커밋으로 `page.updated` 설정 |
| use_date | bool | false | 프론트 매터에 `date`가 없으면 파일의 첫 커밋으로 `page.date` 설정 |

프론트 매터가 항상 우선합니다. 폴백은 파일이 비워 둔 필드만 채웁니다.

## 동작 방식

1. 빌드가 `content/` 전체에 대해 `git log`를 **한 번** 실행하고(페이지마다 프로세스를 띄우지 않음) 모든 경로를 커밋에 매핑합니다. 5,200페이지 테스트 저장소에서 수집 단계 전체가 약 50ms 걸렸습니다.
2. 소스 파일에 비병합 커밋이 하나라도 있는 페이지는 `page.git` 객체를 갖습니다.
3. `use_lastmod` / `use_date`가 비어 있는 `updated` / `date`를 채우면 사이트맵, 피드, JSON-LD, OpenGraph, `sort_by = "date"` 등 하위 모든 곳이 템플릿 수정 없이 git에서 유도한 값을 봅니다.

`hwaro serve`는 파일을 저장할 때마다가 아니라 전체 재빌드마다 한 번 이력을 수집합니다. `hwaro build --cache`는 각 페이지의 커밋 ID와 타임스탬프를 캐시 키에 포함하므로, 새 커밋 후의 웜 재빌드는 그 커밋이 건드린 페이지(와 이를 보여주는 목록)만 정확히 다시 렌더링합니다.

## 템플릿 변수

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| page.git | Object? | 페이지에 이력이 없으면 `nil`(아래 참고) |
| page.git.hash | String | 파일을 건드린 최신 비병합 커밋의 전체 커밋 ID |
| page.git.short_hash | String | `hash`의 앞 7자 |
| page.git.lastmod | Time | 최신 커밋의 작성자 날짜 |
| page.git.first_commit | Time | 파일을 건드린 모든 커밋 중 가장 이른 작성자 날짜 |
| page.git.author_name | String | 최신 커밋의 작성자 이름 |
| page.git.author_email | String | 최신 커밋의 작성자 이메일 |

`lastmod`와 `first_commit`은 실제 시간 값(작성자의 UTC 오프셋 유지)이므로 `date` 필터로 바로 포맷할 수 있습니다. 목록에서 순회하는 페이지(`section.pages`, `site.pages`, 택소노미 항목)에서도 같은 객체를 쓸 수 있습니다.

```jinja
{% if page.git %}
<p class="meta">
  Last updated {{ page.git.lastmod | date(format="%Y-%m-%d") }}
  by {{ page.git.author_name }}
  (<a href="https://github.com/you/site/commit/{{ page.git.hash }}">{{ page.git.short_hash }}</a>)
</p>
{% endif %}
```

다음 경우에는 `page.git`이 `nil`이고 폴백도 적용되지 않습니다.

- 아직 커밋되지 않은(새로 만든 또는 추적되지 않는) 파일
- `[[content.generate]]`로 생성된 페이지
- 생성된 택소노미 및 목록 페이지
- 사이트가 git 저장소 안에 있지 않은 경우의 모든 페이지

## 번들, 번역, 이름 변경

- 페이지 번들(`posts/hello/index.md` + 에셋)은 Markdown 파일 기준이므로 에셋만 커밋해도 `lastmod`는 움직이지 않습니다.
- 각 번역본(`hello.md`, `hello.ko.md`)은 별도 파일이며 이력도 별도입니다.
- 이름 변경은 **따라가지 않습니다**. 이름을 바꾼 파일의 이력은 이름 변경 커밋에서 다시 시작하므로 `first_commit`(그리고 `use_date`일 때 `page.date`)은 이름 변경 날짜가 됩니다.

## 우아한 성능 저하

이 기능은 빌드를 중단시키지 않습니다. 아래 상황은 각각 경고 한 번을 남기고 `page.git`을 비워 둡니다.

| 상황 | 결과 |
|-----------|--------|
| `PATH`에 `git` 바이너리가 없음 | 경고, git 메타데이터 없음 |
| `content/`가 저장소 안에 없음 | 경고, git 메타데이터 없음 |
| 얕은 클론(`--depth N`) | 클론 깊이보다 오래된 파일의 `lastmod`/`first_commit`이 틀릴 수 있다는 경고, 메타데이터는 계속 사용 |

대부분의 CI 체크아웃은 기본이 얕은 클론입니다. 날짜가 정확하도록 전체 이력을 가져오세요.

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
```

## 함께 보기

- [데이터 모델](/ko/templates/data-model/) — 전체 `page` 객체
- [SEO](/ko/features/seo/), [구조화 데이터](/ko/features/structured-data/) — `page.updated`가 출력되는 곳
- [증분 빌드](/ko/features/incremental-build/) — `--cache`가 재렌더링 대상을 정하는 방식

---

Title: 이미지 처리
URL: https://hwaro.hahwul.com/ko/features/image-processing/
Source: content/features/image-processing.ko.md
Language: ko

Hwaro는 빌드 중에 리사이즈된 이미지 변형을 자동으로 생성할 수 있습니다. 반응형 이미지, 썸네일, 성능 최적화에 유용합니다. 외부 도구는 필요 없습니다. 이미지 처리는 [stb](https://github.com/nothings/stb) 라이브러리 기반으로 바이너리에 내장되어 있습니다.

## 지원 포맷

| 포맷 | 읽기 | 쓰기 |
|--------|------|-------|
| JPEG (.jpg, .jpeg) | 가능 | 가능 |
| PNG (.png) | 가능 | 가능 |
| BMP (.bmp) | 가능 | 가능 |

## 설정

`config.toml`에서 이미지 처리를 활성화합니다:

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | 이미지 리사이즈 활성화 |
| widths | array | [] | 생성할 대상 너비(픽셀) |
| quality | int | 85 | JPEG 출력 품질 (1-100) |

### LQIP (저화질 이미지 플레이스홀더)

LQIP를 활성화하면 빌드 시점에 작은 base64 인코딩 플레이스홀더 이미지를 만들고 대표 색상을 추출합니다. CLS(Cumulative Layout Shift)를 없애고, 원본 이미지가 로드되는 동안 즉시 시각적 피드백을 보여줍니다.

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | LQIP 생성 활성화 |
| width | int | 32 | 플레이스홀더 이미지 너비(픽셀, 8-128) |
| quality | int | 20 | 플레이스홀더 JPEG 품질 (1-100, 낮을수록 작음) |

너비 32, 품질 20이면 이미지당 보통 400-800바이트 정도의 base64 문자열이 나옵니다. HTML에 바로 인라인해도 될 만큼 작습니다.

## 동작 방식

1. 빌드 중 Hwaro는 세 위치의 이미지를 스캔합니다:
   - **페이지 번들 에셋** (`index.md`와 함께 둔 이미지)
   - **콘텐츠 파일** (`[content.files]` 설정으로 게시되는 이미지)
   - **정적 파일** (`static/` 디렉터리의 이미지)
2. 각 이미지마다 설정된 모든 너비의 리사이즈 변형을 생성합니다
3. 종횡비는 항상 유지됩니다
4. 대상 너비가 원본보다 크면 업스케일 없이 원본을 그대로 복사합니다
5. 원본 이미지는 한 번만 디코딩한 뒤 모든 너비로 리사이즈합니다 (효율적)

## 출력 파일 이름

리사이즈된 이미지에는 `{name}_{width}w.{ext}` 규칙으로 이름이 붙습니다. 예를 들어 `static/hwaro.png`라면:

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

## 템플릿에서 사용

`resize_image()` 함수로 리사이즈 변형의 URL을 얻습니다:

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

`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"
>
```

이 함수는 가장 가까운 너비를 선택합니다. `width=500`을 요청했는데 설정된 너비가 `[320, 640, 1024]`라면 640px 변형(요청값 이상 중 가장 작은 너비)을 반환합니다. 충분히 큰 변형이 없으면 가장 큰 변형으로 폴백합니다.

### LQIP 플레이스홀더 사용

LQIP가 활성화되면 `resize_image()`가 두 속성을 추가로 반환합니다: `lqip`(base64 데이터 URI)와 `dominant_color`(16진수 색상 문자열)입니다. 블러업(blur-up) 효과나 단색 플레이스홀더에 사용합니다:

**블러업 효과:**

```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"
>
```

**대표 색상 플레이스홀더:**

```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"
>
```

**결합 방식 (색상 → 블러 → 원본 이미지 순서):**

```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>
```

LQIP가 비활성화 상태면 `lqip`와 `dominant_color`는 빈 문자열을 반환하므로 템플릿을 고치지 않아도 됩니다.

## 라이브 데모

### 리사이즈 데모

이 문서 사이트는 `widths = [128, 256, 512]`와 LQIP를 켠 상태로 이미지 처리를 사용합니다. 아래 이미지들은 `static/hwaro.png`에서 자동 생성된 리사이즈 변형입니다:

**원본** (`hwaro.png`):

<img src="/hwaro.png" alt="Hwaro 로고 - 원본" style="max-width:256px">

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

<img src="/hwaro_128w.png" alt="Hwaro 로고 - 가로 128px">

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

<img src="/hwaro_256w.png" alt="Hwaro 로고 - 가로 256px">

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

<img src="/hwaro_512w.png" alt="Hwaro 로고 - 가로 512px">

이 파일들은 빌드 시점에 생성되므로 런타임 리사이즈나 외부 서비스가 필요 없습니다. 템플릿에서는 `resize_image()`로 참조합니다:

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

### LQIP 데모

`resize_image()` 함수는 LQIP 데이터도 제공합니다. `hwaro.png`의 실제 출력은 다음과 같습니다:

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

## 성능

- **단일 디코드**: 원본 이미지를 한 번만 디코딩해 메모리에서 모든 대상 너비로 리사이즈
- **병렬 처리**: 워커 풀로 여러 이미지를 동시에 처리
- **업스케일 없음**: 대상 너비보다 작은 이미지는 그대로 복사
- **효율적인 LQIP**: LQIP 썸네일은 원본 해상도가 아니라 가장 작은 리사이즈 변형에서 생성하고, 대표 색상도 그 썸네일에서 계산

## 간단한 예시

사이트에 `static/hwaro.png`(Hwaro 로고)가 있고 이를 반응형 이미지로 표시하려는 경우입니다:

**config.toml:**

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

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

**템플릿:**

```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"
>
```

**빌드 출력:**

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

## 블로그 글 이미지

프론트 매터에 히어로 이미지를 지정한 블로그 글이라면:

```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 %}
```

## 함께 보기

- [콘텐츠 파일](/ko/features/content-files/) — content/의 마크다운 이외 파일 게시
- [자동 OG 이미지](/ko/features/og-images/) — 자동 생성되는 Open Graph 미리보기 이미지
- [함수](/ko/templates/functions/) — 템플릿 함수 레퍼런스

---

Title: 증분 빌드
URL: https://hwaro.hahwul.com/ko/features/incremental-build/
Source: content/features/incremental-build.ko.md
Language: ko

증분 빌드는 파일 체크섬과 의존성 변경을 추적해 변경되지 않은 페이지를 건너뜁니다. 페이지가 많은 사이트에서 재빌드 시간이 크게 줄어듭니다.

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

## 사용 시점

증분 빌드는 다음 상황에서 효과가 큽니다.

- 사이트에 페이지는 많지만 한 번에 몇 개만 수정하는 경우
- 수정-빌드-미리보기 사이클을 빠르게 돌리고 싶은 경우
- 템플릿이나 설정이 아니라 콘텐츠 위주로 작업하는 경우

## 사용 방법

### 캐시 활성화

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

첫 실행에서는 모든 페이지를 빌드하고 체크섬을 `.hwaro_cache.json`에 저장합니다. 이후 빌드부터는 변경된 파일만 다시 처리합니다.

### 전체 재빌드 강제

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

`--full` 플래그는 캐시를 비우고 모든 페이지를 처음부터 다시 빌드합니다. 빌드가 끝나면 새 캐시가 저장되므로, 다음에 `--full` 없이 빌드하면 다시 증분 빌드로 동작합니다.

## 동작 방식

### 변경 감지

캐시 항목마다 다음을 추적합니다.

- **파일 수정 시각(mtime)** — 빠른 1차 확인
- **콘텐츠 체크섬(MD5)** — mtime이 달라졌을 때 실제 변경 여부를 검증해, 파일을 touch만 한 경우 같은 오탐을 걸러냅니다

mtime이 그대로면 내용을 읽지 않고 변경 없음으로 판단합니다. mtime이 다르면 콘텐츠 해시를 계산해 비교하고, 실제로 변경됐는지 확인합니다.

### 의존성 무효화

파일별 체크섬 외에도, 각 페이지가 실제로 무엇에 의존하는지 추적합니다.

- **템플릿 클로저** — 페이지의 템플릿과 그 템플릿이 `extends`, `include`,
  `import`로 전이적으로 참조하는 모든 템플릿, 그리고 페이지 콘텐츠가 호출하는
  숏코드 템플릿까지 포함합니다. 각 페이지의 캐시 항목에 이 클로저의
  핑거프린트가 저장되므로, `partials/footer.html`을 수정하면 해당 파셜을
  렌더링하는 템플릿 체인을 가진 페이지만 재빌드됩니다.
- **캐스케이드 핑거프린트** — 페이지에 적용된 섹션 `[cascade]` 병합값.
  상위 `_index.md`의 캐스케이드를 수정하면 하위 페이지가 재빌드됩니다.
- **설정 체크섬** — 최종 병합된 설정의 해시. 설정이 바뀌면 **모든** 항목이
  무효화됩니다.
- **렌더 훅** — 설정된 모든 `templates/hooks/render-*` 템플릿의
  핑거프린트([렌더 훅](/ko/templates/render-hooks/) 참고)가 모든 페이지의
  템플릿 클로저에 포함됩니다. 훅은 페이지의 `{% include %}`/`{% extends %}`
  그래프로 도달하는 대상이 아니므로, 훅을 수정하면 좁혀진 집합이 아니라
  **모든** 페이지가 다시 렌더링됩니다.

템플릿 의존성 추적은 모든 템플릿 참조가 문자열 리터럴이어야 동작합니다.
동적 참조(`{% include some_var %}`)를 쓰는 템플릿이 하나라도 있으면
사이트 전체 무효화로 전환되어, 템플릿이 하나라도 바뀌면 모든 페이지를
재빌드합니다. 명시적으로 끌 수도 있습니다.

```toml
[build]
template_deps = false  # 템플릿이 바뀌면 모든 페이지를 재빌드
```

### 건너뛰는 작업

페이지와 그 의존성이 모두 변경되지 않았다면:

- 콘텐츠 파싱은 여전히 수행합니다(내비게이션, 택소노미 등을 구성하기 위해)
- **렌더링과 파일 쓰기는 건너뜁니다** — 기존 출력 파일을 재사용합니다
- SEO 파일(사이트맵, 피드 등)은 항상 다시 생성합니다

### serve 모드

개발 서버(`hwaro serve`)는 더 정밀한 증분 전략을 사용합니다.

| 변경 유형 | 전략 |
|-------------|----------|
| 콘텐츠 파일만 | 영향받는 페이지와 인접 페이지만 다시 파싱·렌더링 |
| 템플릿 파일만 | 수정된 템플릿이 템플릿 클로저에 포함된 페이지만 다시 렌더링 (추적이 꺼져 있거나, 그래프에 동적 참조가 있거나, 수정된 파일이 `templates/hooks/` 아래에 있으면 전체 페이지) |
| 설정 파일 | 전체 재빌드 |
| 정적 파일만 | 변경된 파일만 복사 |

### 삭제된 페이지

콜드 빌드는 빈 출력 디렉터리에서 시작하므로 삭제한 페이지는 다음 빌드에서
`public/`에서도 사라집니다. `--cache`는 디렉터리를 그대로 두기 때문에(그게
목적입니다) 삭제는 캐시로 처리합니다. 모든 항목은 해당 페이지가 쓴 파일을
기록해 두고, 매 빌드마다 살아 있는 페이지가 주장하지 않는 항목의 출력물을
삭제합니다.

삭제된 페이지, 이름이 바뀐 페이지, URL이 옮겨진 페이지(`slug`, `path`,
퍼머링크 규칙), 초안으로 바뀐 페이지, `expires` 날짜가 지난 페이지,
`render = false`가 된 페이지가 모두 여기에 해당합니다.

제거된 페이지가 함께 만들어 낸 파일도 같이 사라집니다. `aliases` 리다이렉트
스텁, AMP 미러, 자동 생성된 OG 이미지, 더 이상 아무도 쓰지 않는 텀의 택소노미
페이지(그 텀의 피드 포함), 섹션이 더 이상 채우지 않는 페이지네이션 페이지가
모두 해당합니다. 기능 자체를 끄는 경우(`[amp] enabled = false`)도 같은 이유로
다음 빌드에서 그동안 발행하던 파일이 정리됩니다.

따라서 `--cache` 빌드의 출력물은 깨끗한 빌드와 바이트 단위로 같고, 무언가를
정리하려고 `hwaro build --full`을 쓸 필요가 없습니다.

## 캐시 파일

캐시는 프로젝트 루트의 `.hwaro_cache.json`에 저장됩니다. 이 파일에는 다음이 들어 있습니다.

- **메타데이터** — 마지막 빌드의 템플릿·설정 체크섬
- **항목** — 파일별 레코드(경로, mtime, 콘텐츠 해시, 출력 경로). 출력 경로는 제거된 페이지의 오래된 파일을 찾는 데에도 쓰입니다

`.hwaro_cache.json`은 `.gitignore`에 추가합니다(`hwaro init`이 스캐폴드하는 `.gitignore`에는 이미 포함되어 있습니다).

```gitignore
.hwaro_cache.json
```

## 플래그 참조

| 플래그 | 설명 |
|------|-------------|
| `--cache` | 증분 빌드 캐시 활성화 |
| `--full` | 전체 재빌드 강제(캐시를 비우고 다시 채움) |

## 예시

```bash
# 첫 빌드 — 캐시 생성
hwaro build --cache

# 파일 몇 개 수정 후 재빌드 — 변경된 페이지만 다시 렌더링
hwaro build --cache

# 뭔가 이상할 때 — 깨끗하게 전체 재빌드
hwaro build --cache --full

# 다른 플래그와 조합
hwaro build --cache --minify
```

## 함께 보기

- [CLI](/ko/start/cli/) — 빌드 플래그 전체 목록
- [스트리밍 빌드](/ko/features/streaming-build/) — 대규모 사이트의 메모리 사용량 절감
- [빌드 훅](/ko/features/build-hooks/) — 빌드 전후 사용자 정의 명령 실행

---

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

Hwaro는 AI/LLM 크롤러에게 안내와 콘텐츠를 제공하는 `llms.txt`와 `llms-full.txt` 파일을 생성할 수 있습니다. 웹사이트를 대규모 언어 모델이 다루기 쉽게 만들기 위해 떠오르고 있는 [llms.txt 표준](https://llmstxt.org/)의 일부입니다.

## 설정

`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"
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | `llms.txt` 생성 여부 |
| filename | string | "llms.txt" | 출력 파일 이름 |
| instructions | string | "" | LLM 크롤러에게 전달할 안내 텍스트 |
| full_enabled | bool | false | 전체 콘텐츠 버전 생성 여부 |
| full_filename | string | "llms-full.txt" | 전체 버전의 파일 이름 |

## 생성 파일

### llms.txt

기본 `llms.txt` 파일에는 설정에 정의한 안내 텍스트만 들어갑니다. 사이트 정책을 AI 크롤러에게 알리는 가벼운 파일입니다.

**출력 예시 (`llms.txt`):**

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

### llms-full.txt

전체 버전에는 사이트의 렌더링된 콘텐츠가 모두 들어가므로 LLM이 사이트 전체를 파일 하나로 수집하기 쉽습니다. 각 페이지는 `---` 구분자로 나뉩니다.

**출력 예시 (`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...
```

## 전체 문서 구조

`llms-full.txt` 파일의 구조는 다음과 같습니다:

1. **사이트 헤더** — H1 헤딩으로 된 사이트 제목
2. **사이트 설명** — `config.toml`에서 가져옴
3. **Base URL** — 사이트의 base URL
4. **안내 텍스트** — 설정의 instructions 텍스트
5. **페이지 항목** — `---`로 구분된 각 페이지. 포함 내용:
   - `Title` — 페이지 제목
   - `URL` — 페이지의 절대 URL
   - `Source` — 프로젝트 루트 기준 소스 파일 경로
   - `Language` — 언어 코드 (다국어 사이트에만)
   - 페이지의 원본 콘텐츠

### 페이지 선별

다음 조건을 만족하는 페이지만 `llms-full.txt`에 포함됩니다:

- `render = true`인 페이지 (기본값)
- 원본 콘텐츠가 비어 있지 않은 페이지
- 일관된 출력을 위해 URL 순으로 정렬

초안 페이지는 프로덕션 빌드에서 제외됩니다 (`--drafts`를 쓰지 않는 한).

## 다국어 지원

다국어 사이트에서는 각 페이지 항목에 콘텐츠 언어를 나타내는 `Language` 필드가 들어갑니다:

```
---

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

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

## 활용 사례

### 문서 사이트

전체 문서를 LLM에 제공해 AI가 더 정확하게 답하도록 돕습니다:

```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
```

### 블로그 사이트

명확한 사용 지침과 함께 블로그 콘텐츠를 공유합니다:

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

### LLM 접근 제한

전체 콘텐츠를 제공하지 않으면서 `llms.txt`로 선호 사항만 전달할 수도 있습니다:

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

## robots.txt와 함께 사용

`llms.txt`는 `robots.txt`와 함께 동작합니다. `robots.txt`가 HTTP 수준에서 크롤러 접근을 제어한다면, `llms.txt`는 사람이 읽을 수 있는 안내와 맥락을 제공합니다:

```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
```

## 템플릿 연동

HTML 템플릿에서 `llms.txt` 파일로 링크할 수 있습니다:

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

## 함께 보기

- [SEO](/ko/features/seo/) — 사이트맵, RSS 피드, robots.txt, 소셜 태그
- [설정](/ko/start/config/) — 전체 설정 레퍼런스
- [검색](/ko/features/search/) — 검색 인덱스 생성

---

Title: 마크다운 확장
URL: https://hwaro.hahwul.com/ko/features/markdown-extensions/
Source: content/features/markdown-extensions.ko.md
Language: ko

Hwaro는 표준 CommonMark를 넘어서는 선택적 마크다운 확장을 지원합니다. 각 확장은 `config.toml`에서 켜고 끌 수 있습니다(기본값은 아래 표 참고).

## 설정

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| task_lists | bool | true | 체크박스 목록(`- [ ]` / `- [x]`) |
| definition_lists | bool | true | 정의 목록(`Term\n: Definition`) |
| footnotes | bool | true | 각주(`[^1]`) |
| math | bool | false | 수식(`$...$`, `$$...$$`) |
| math_engine | string | "katex" | 수식 렌더링 엔진(`"katex"` 또는 `"mathjax"`) |
| mermaid | bool | false | Mermaid 다이어그램 블록 |
| admonitions | bool | true | GitHub 스타일 `> [!NOTE]` 인용문을 admonition 블록으로 변환 |
| heading_ids | bool | true | 커스텀 헤딩 ID(`## Heading {#custom-id}`) |
| ins | bool | false | 삽입 텍스트(`++text++` → `<ins>text</ins>`) |
| mark | bool | false | 강조 표시 텍스트(`==text==` → `<mark>text</mark>`) |
| sub | bool | false | 아래 첨자(`~text~` → `<sub>text</sub>`) |
| sup | bool | false | 위 첨자(`^text^` → `<sup>text</sup>`) |
| attributes | bool | false | 헤딩과 인라인 이미지에 붙는 일반화된 `{#id .class key=val}` 블록 |
| safe | bool | false | 출력에서 원시 HTML 제거(주석으로 대체) |
| lazy_loading | bool | false | `<img>` 태그에 `loading="lazy"` 추가 |
| emoji | bool | false | 이모지 숏코드(예: `:smile:`)를 이모지 문자로 변환 |
| smart_punctuation | bool | false | 타이포그래피 따옴표/대시/줄임표 |
| containers | bool | false | `:::note Title` … `:::` 커스텀 컨테이너 |
| task_list_classes | bool | false | 작업 목록 마크업에 GFM 클래스 부여 |
| insert_anchor_links | string | "none" | 사이트 전역 헤딩 앵커 링크(`"none"`/`"left"`/`"right"`) |
| external_links_target_blank | bool | false | 절대 http(s) 링크에 `target="_blank" rel="noopener"` |
| external_links_no_follow | bool | false | 절대 http(s) 링크에 `rel="nofollow"` |
| external_links_no_referrer | bool | false | 절대 http(s) 링크에 `rel="noreferrer"` |

## 작업 목록

목록 안에 체크박스를 렌더링합니다.

### 문법

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

### 출력

```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>
```

## 정의 목록

`<dl>`, `<dt>`, `<dd>` 요소로 용어와 정의를 렌더링합니다.

### 문법

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

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

### 출력

```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>
```

## 각주

각주 참조와 정의를 추가합니다.

### 문법

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

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

### 출력

참조는 위 첨자 링크가 됩니다.

```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>
```

문서 끝에 각주 섹션이 덧붙습니다.

```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>
```

## 수식

수학 표현식을 렌더링합니다. 클라이언트 사이드 수식 라이브러리(KaTeX 또는 MathJax)가 필요합니다.

### 문법

인라인 수식은 `$` 하나로 감쌉니다.

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

디스플레이 수식은 `$$` 두 개로 감쌉니다.

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

### 출력

```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>
```

### 클라이언트 사이드 설정

#### 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 다이어그램

Mermaid 다이어그램 블록을 `<div class="mermaid">` 요소로 렌더링합니다.

이는 [렌더 훅](/ko/templates/render-hooks/)의 "항상 적용" 규칙에 대한 유일한 예외입니다. `mermaid = true`이면 `` ```mermaid `` 펜스는 `render-codeblock.html` 훅이 설정되어 있어도 항상 이 파이프라인을 거칩니다. 코드블록 훅이 다른 언어처럼 mermaid 펜스도 처리하게 하려면 `mermaid = false`로 설정합니다.

### 문법

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

### 출력

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

### 클라이언트 사이드 설정

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

## 인라인 마크업(ins, mark, sub, sup)

각각 별도 플래그 뒤에 있는 네 가지 옵트인 인라인 스타일입니다. 기본값이 모두 꺼짐이므로, 하나를 켜도 나머지에는 영향이 없습니다.

### 문법

```markdown
++Inserted text++ and ==highlighted text==.
Formula: x~2~ + y^2^ = z~n~
```

```toml
[markdown]
ins = true
mark = true
sub = true
sup = true
```

### 출력

```html
<p><ins>Inserted text</ins> and <mark>highlighted text</mark>.
Formula: x<sub>2</sub> + y<sup>2</sup> = z<sub>n</sub></p>
```

### 제한 사항

- **백슬래시 이스케이프가 없습니다.** 네 구분자 모두 CommonMark 스타일 `\` 이스케이프로 변환을 억제할 수 없고, 시도했을 때의 결과도 일관적이지 않습니다. 백슬래시가 리터럴 구분자나 스타일된 결과 대신 깨진 이스케이프 태그 출력을 남길 수 있습니다. 문법을 텍스트 그대로 보여야 할 때는 코드 스팬(`` `++literal++` ``)을 사용합니다.
- **구분자 관련 주의점:** `++`/`==`/`~`/`^`는 모두 내용 양쪽에 비공백 문자가 있어야 동작하므로, 산술식처럼 생긴 텍스트(`a ~ b`, `x ^ y`, 공백이 있는 `a == b`)는 건드리지 않습니다. 단일 `~`와 `^`는 취소선의 `~~`나 일반 `**`/`__` 강조와 의도적으로 분리되어 있어 같은 줄의 `~~del~~`과 `~sub~`가 모두 동작합니다. 다만 리터럴 `~`/`^`/`==`/`++`가 많은 페이지(셸 프롬프트, C/C++ 스니펫, XOR이 많은 코드)는 어차피 코드 스팬이나 펜스 코드 블록에 담아 두는 편이 좋습니다. sub/sup/ins/mark는 그 바깥에서만 적용되기 때문입니다.
- `footnotes`가 함께 켜져 있어도 `sup`이 각주 참조(`[^1]`)를 망가뜨리지 않습니다.

## 속성(`{#id .class key=val}`)

헤딩이나 인라인 이미지에 붙는 pandoc 스타일 속성 블록입니다. [커스텀 헤딩 ID](/ko/writing/pages/#커스텀-헤딩-id) 축약 문법을 일반화한 것으로, 클래스와 임의 속성까지 설정할 수 있고 이미지에도 적용됩니다.

### 문법

```markdown
## Section Title {#section-title .highlight data-index=3}

![A diagram](diagram.png){.responsive width=800}
```

```toml
[markdown]
attributes = true
```

### 출력

```html
<h2 id="section-title" class="highlight" data-index="3">Section Title</h2>

<img src="diagram.png" alt="A diagram" class="responsive" width="800" />
```

토큰은 공백으로 구분합니다(쉼표는 구분자가 아님). `#id`는 id를 설정하고, `.class`는 클래스를 추가하며(반복 가능), `key=value` / `key="quoted value"`는 그 밖의 속성을 설정합니다. `id=value`와 `class=value`는 `#value` / `.value`의 별칭으로 허용됩니다. id는 숫자로 시작해도 됩니다(`{#1-intro}`) — [커스텀 헤딩 ID](/ko/writing/pages/#커스텀-헤딩-id) 축약 문법과 같은 문자 집합입니다. 클래스 이름은 그렇지 않습니다. 유효하지 않은 토큰이 하나라도 있으면 블록 전체가 무효가 되어 원본 `{...}`이 그대로 남습니다.

### 제한 사항

- **v1 범위는 헤딩과 인라인 이미지뿐입니다** — 다른 요소(문단, 링크, 코드 스팬, 목록 항목) 뒤의 속성 블록은 지원되지 않고 리터럴 텍스트로 남습니다.
- 다른 토큰 없이 `## Heading {#id}`만 있는 경우는 `attributes`가 켜져 있어도 여전히 더 좁은 `heading_ids` 메커니즘이 처리합니다. 따라서 `attributes`를 켜도 기존 `{#id}` 전용 헤딩은 달라지지 않습니다.
- **safe 모드는 블록을 버립니다.** `markdown.safe = true`이면 `{...}` 속성 블록이 출력에서 제거되며(`heading_ids`와 동일), 어떤 속성도 적용되지 않습니다.

## 스마트 문장부호

`smart_punctuation = true`이면 곧은 따옴표, 이중/삼중 대시, 점 세 개가 타이포그래피 형태로 바뀝니다.

| 입력 | 출력 |
|-------|--------|
| `"quoted"` / `'quoted'` | “quoted” / ‘quoted’ |
| `--` | – (en dash) |
| `---` | — (em dash) |
| `...` | … (ellipsis) |

코드 스팬, 코드 블록, 원시 HTML, 수식 본문은 절대 다시 쓰지 않습니다. 표 셀, 정의 본문, 각주 본문은 미리 렌더링된 HTML이라 그 내부에는 스마트 문장부호가 적용되지 않습니다. `markdownify` 템플릿 필터는 사이트 설정을 따릅니다.

## 커스텀 컨테이너

`containers = true`이면 `:::` 펜스 블록이 admonition과 같은 마크업(과 CSS)으로 렌더링됩니다.

```markdown
:::note Optional Title
Any **markdown** body — code fences and task lists included.
:::
```

제목의 기본값은 타입을 대문자로 시작한 형태입니다. 더 긴 구분자는 중첩되고(`::::outer` … `:::inner` … `:::` … `::::`), 단독 `:::`는 가장 안쪽의 열린 컨테이너를 닫으며, 닫히지 않은 컨테이너는 페이지 끝에서 자동으로 닫힙니다. 코드 펜스 안의 `:::` 줄은 리터럴로 남습니다. `safe = true`와는 함께 쓸 수 없습니다(원시 래퍼가 제거되기 때문).

## 작업 목록 클래스

`task_list_classes = true`이면 작업 목록 마크업에 GFM의 클래스가 붙어 GitHub 대상 CSS가 그대로 적용됩니다. `<li class="task-list-item">`, 체크박스의 `class="task-list-item-checkbox"`, 작업 항목을 직접 포함하는 모든 목록의 `class="contains-task-list"`가 붙습니다. 기존 사이트의 출력을 바이트 단위로 동일하게 유지하기 위해 기본값은 꺼짐입니다.

## 헤딩 앵커 링크

`insert_anchor_links = "left"`(또는 `"right"`)는 사이트 전체의 모든 헤딩에 `🔗` 앵커 링크를 헤딩 텍스트 앞 또는 뒤에 추가합니다. 페이지 프론트 매터의 `insert_anchor_links = true/false`가 사이트 설정을 페이지 단위로 덮어씁니다. 마크업을 완전히 바꾸려면 [render-heading 훅](/ko/templates/render-hooks/)을 사용합니다.

## 외부 링크 정책

세 가지 플래그가 렌더링된 마크다운(표 셀과 각주 포함)의 절대 `http(s)://` 링크에 사이트 전역 정책을 적용합니다.

```toml
[markdown]
external_links_target_blank = true # target="_blank" + rel="noopener"
external_links_no_follow = true    # rel="nofollow"
external_links_no_referrer = true  # rel="noreferrer"
```

이미 `target=`을 가진 링크는 그대로 유지되고, `rel` 토큰은 기존 `rel` 속성에 중복 없이 병합됩니다. 즉 render-link 훅이 명시한 선택이 우선합니다. 이 정책은 자신의 도메인을 가리키는 링크를 포함해 모든 절대 http(s) 링크에 적용됩니다.

## 여러 줄 각주와 정의

각주 정의는 4칸 공백(또는 탭)으로 들여쓴 이어지는 줄을 수집하며, 빈 줄로 구분된 문단도 포함합니다.

```markdown
[^1]: First paragraph of the note,
    soft-wrapped onto a second line.

    Second paragraph of the same note.
```

정의 목록 본문도 같은 방식으로 이어집니다(들여쓴 줄이 같은 `<dd>`에 합쳐짐). 들여쓰지 않은(lazy) 이어쓰기, 각주 본문 안의 블록 요소, 여러 문단으로 된 `<dd>`는 지원되지 않습니다.

## 함께 보기

- [설정](/ko/start/config/) — 마크다운 설정 옵션
- [구문 강조](/ko/features/syntax-highlighting/) — 코드 블록 강조
- [렌더 훅](/ko/templates/render-hooks/) — 링크·이미지·헤딩·코드 블록 렌더링 방식 재정의

---

Title: 메뉴
URL: https://hwaro.hahwul.com/ko/features/menus/
Source: content/features/menus.ko.md
Language: ko

이름 있는 내비게이션 메뉴를 트리로 구성해 `site.menus` / `get_menu()`로 템플릿에 노출합니다. 메뉴는 `config.toml`에서 전부 정의할 수도, 페이지/섹션 프론트 매터로만 구성할 수도, 둘을 동시에 쓸 수도 있습니다. 두 소스의 엔트리는 같은 트리로 병합됩니다.

섹션에서 메뉴를 자동으로 만들어 주는 기능(Hugo의 `sectionPagesMenu`)은 없습니다. [후속 과제](#후속-과제)를 참고합니다.

## 메뉴 설정

```toml
[[menus.main]]
name = "Posts"
url = "/posts/"
weight = 1

[[menus.main]]
name = "About"
url = "/about/"
weight = 2
identifier = "about"
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| name | string | — | **필수.** 표시 라벨. `name`이 없는 엔트리는 경고와 함께 건너뜀 |
| url | string | "" | 루트 상대 경로(`/posts/`) 또는 절대 `http(s)://`/`//` URL |
| weight | int | 0 | 메뉴 내 정렬 순서(오름차순), 이후 `name`, `identifier` 순 |
| identifier | string | `name` | 다른 엔트리가 `parent`로 참조하는 고유 키 |
| parent | string | 없음 | 이 엔트리를 하위로 넣을 다른 엔트리의 `identifier` |

`[[menus.<name>]]` 블록 하나가 이름 있는 메뉴 하나입니다. 두 번째 메뉴가 필요하면 `[[menus.footer]]`를 추가하고 `get_menu(name="footer")`로 렌더링합니다.

## 프론트 매터로 페이지/섹션 등록

페이지나 섹션은 `config.toml`을 건드리지 않고도 메뉴에 합류할 수 있습니다.

```toml
+++
title = "My Post"
menus = ["main"]
+++
```

`menus`(또는 단수형 별칭 `menu`. 둘 다 있으면 `menus`가 우선)는 단일 문자열(`menus = "main"`)도 허용하고, 필드별 오버라이드를 위한 테이블 형태도 허용합니다.

```toml
+++
title = "My Post"

[menus.main]
name = "Featured Post"
weight = 1
parent = "posts"
+++
```

테이블 형태의 모든 필드는 선택 사항이며 페이지 자체 데이터로 대체됩니다. `name`은 `page.title`, `weight`는 `0`, `identifier`는 결정된 `name`, `parent`는 없음(루트 엔트리)이 기본값입니다.

페이지/섹션은 `config.toml`이 선언한 적 없는 이름을 포함해 **어떤** 메뉴 이름에도 등록할 수 있습니다. 프론트 매터로만 정의한 메뉴도 그 자체로 정상적인 지원 구성입니다(`hwaro doctor`는 설정이 다른 곳에 메뉴를 하나라도 선언한 경우에만 선언되지 않은 이름을 지적합니다. `[[menus.*]]` 블록이 하나도 없는 사이트는 의도적으로 프론트 매터에 전부 맡긴 것으로 보기 때문입니다).

## 계층 구조

`parent`가 있는 엔트리는 `identifier`가 일치하는 엔트리의 자식이 됩니다. 중첩 메뉴는 `item.children`을 순회해 렌더링합니다.

```jinja
<ul>
{% for item in get_menu(name="main") %}
  <li>
    <a href="{{ item.href }}">{{ item.name }}</a>
    {% if item.children %}
    <ul>
      {% for child in item.children %}
      <li><a href="{{ child.href }}">{{ child.name }}</a></li>
      {% endfor %}
    </ul>
    {% endif %}
  </li>
{% endfor %}
</ul>
```

같은 메뉴 안의 어떤 `identifier`와도 일치하지 않는 `parent`(오타나 낡은 참조)는 빌드를 실패시키지 않습니다. 대신 해당 엔트리가 루트 레벨로 승격되고 빌드 로그에 경고가 남습니다. `hwaro doctor`는 빌드 전에 `config.toml`에서 이를 미리 지적합니다([doctor](/ko/start/tools/doctor/) 참고). `identifier`가 중복되면 마지막에 선언된 엔트리가 남고 앞의 것은 버려집니다.

## 언어별 메뉴

menus 테이블이 없는 `[languages.<code>]` 블록은 전역 `[[menus.*]]` 집합을 통째로 상속합니다. `[[languages.<code>.menus.<name>]]`을 선언하면 그 언어에서 해당 메뉴가 통째로 **대체**되며, 전역 집합과 병합되지 않습니다.

```toml
[[menus.main]]
name = "Posts"
url = "/posts/"

[languages.ko]
language_name = "한국어"

[[languages.ko.menus.main]]
name = "글"
url = "/ko/posts/"
```

`get_menu()`는 **현재 페이지의** 언어를 기준으로 해석하며, 그 언어에 요청한 메뉴 이름의 엔트리가 없으면 기본 언어로 대체합니다. `site.menus`는 항상 기본 언어의 메뉴이므로, 기본 언어가 아닌 페이지에서 렌더링되는 템플릿에서는 `get_menu()`를 사용합니다.

프론트 매터 등록은 등록한 페이지/섹션 자신의 언어를 따릅니다. 언어별 설정 오버라이드와 무관하게, 자신이 속한 언어의 메뉴 집합에 합쳐집니다.

## 활성 상태 스타일링

`active_path` 필터는 메뉴 엔트리의 `url`을 현재 페이지와 비교합니다.

```jinja
{% for item in get_menu(name="main") %}
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
{% endfor %}
```

`ancestor=true`를 넘기면 하위 페이지도 일치합니다(섹션 안을 탐색하는 동안 상위 내비게이션 항목을 강조/펼친 상태로 유지할 때 유용).

```jinja
<a href="{{ item.href }}"{% if item.url | active_path(ancestor=true) %} class="open"{% endif %}>{{ item.name }}</a>
```

루트 경로(`/`)는 `ancestor=true`여도 항상 정확히 일치할 때만 매칭됩니다. 그렇지 않으면 홈 내비게이션 항목이 사이트의 모든 페이지에서 활성/펼침으로 보이게 됩니다. 외부 엔트리는 절대 매칭되지 않습니다(외부 URL에는 조상 관계를 따질 "현재 페이지"가 없음). [필터](/ko/templates/filters/#url-필터)의 URL 필터 절을 참고합니다.

## `href`와 `url`

모든 엔트리는 둘 다 노출합니다.

- **`url`** — 설정/등록된 그대로의 루트 상대 경로(외부 URL이면 손대지 않은 원본). `page.url`과 비교 가능한 값으로, `active_path`가 비교하는 대상입니다.
- **`href`** — 실제로 `<a href>`에 넣을 값. 내부 엔트리라면 `url` 앞에 사이트의 `base_path`(`base_url`의 경로 부분, 예: `https://user.github.io/repo/`에 배포된 프로젝트 사이트의 `/repo`)가 붙어, 서브패스 배포에서도 링크가 올바르게 해석됩니다. 외부 엔트리는 그대로이며 `href`와 `url`이 동일합니다.

항상 `item.href`를 렌더링하고, 비교에는 `item.url`을 사용합니다(`active_path`가 내부적으로 하는 방식). 둘을 섞어 쓰면 서브패스 배포가 깨지거나(`href` 자리에 `url` 사용) 현재 페이지와 절대 매칭되지 않습니다(`active_path`식 비교에 `href` 사용).

## 엔트리 레퍼런스

| 필드 | 타입 | 설명 |
|-------|------|--------------|
| name | String | 표시 라벨 |
| url | String | 순수 루트 상대 경로, 또는 손대지 않은 외부 URL |
| href | String | `base_path`가 적용된 `url`(내부) 또는 그대로(외부) — `<a href>`에는 이 값 사용 |
| identifier | String | 메뉴 내 고유 키 |
| weight | Int | 정렬 순서 |
| external | Bool | `http://`, `https://`, `//` URL이면 `true` |
| children | Array\<Entry\> | 중첩 엔트리([계층 구조](#계층-구조) 참고) |
| page | Page? | 엔트리가 프론트 매터에서 왔고 `Page`로 해석될 때 등록한 페이지/섹션의 데이터(설정 전용 엔트리와 `Section`의 `_index.md`에서 등록한 엔트리는 nil) |

## 후속 과제

- **`sectionPagesMenu` 스타일 자동 생성** — Hugo는 `[[menus.*]]`나 프론트 매터 등록 없이 모든 최상위 섹션에서 메뉴를 자동으로 채울 수 있습니다. Hwaro는 아직 이를 지원하지 않으며, 모든 엔트리를 명시적으로(설정 또는 프론트 매터) 등록해야 합니다.

## 함께 보기

- [함수](/ko/templates/functions/#get-menu) — `get_menu()` 레퍼런스
- [필터](/ko/templates/filters/#url-필터) — `active_path` 레퍼런스
- [데이터 모델](/ko/templates/data-model/#메뉴) — `site.menus`와 Entry 구조
- [설정](/ko/start/config/#메뉴) — `[[menus.*]]` 설정 레퍼런스
- [doctor](/ko/start/tools/doctor/) — `menu-parent-undefined` / `menu-undeclared` 검사기

---

Title: 다국어
URL: https://hwaro.hahwul.com/ko/features/multilingual/
Source: content/features/multilingual.ko.md
Language: ko

Hwaro는 자동 번역 연결, 언어별 URL, SEO용 hreflang 태그를 갖춘 다국어 사이트 구축을 지원합니다.

## 설정

`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
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| default_language | string | "en" | 기본 언어 코드 |
| language_name | string | — | 사람이 읽는 언어 이름 |
| weight | int | 0 | 정렬 순서(낮을수록 앞) |
| generate_feed | bool | true | 해당 언어의 RSS/Atom 피드 생성 여부 |
| build_search_index | bool | true | 검색 인덱스 포함 여부 |
| taxonomies | array | [] | 해당 언어의 택소노미 |

## 콘텐츠 구조

파일 이름에 언어 접미사를 붙여 번역을 만듭니다:

```
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 매핑

| 파일 | 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/ |

기본 언어 페이지는 루트 경로로 서비스되고, 비기본 언어 페이지에는 언어 코드 접두사가 붙습니다.

### 섹션 번역

섹션 인덱스 파일에도 언어 접미사를 쓸 수 있습니다:

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

## 번역 연결

Hwaro는 파일 이름을 기준으로 번역된 페이지를 자동으로 연결합니다. 언어 접미사를 뺀 기본 이름이 같은 페이지들은 서로의 번역으로 간주됩니다.

예를 들어 `hello.md`, `hello.ko.md`, `hello.ja.md`는 모두 번역 관계로 연결됩니다.

### 템플릿 변수

템플릿에서 번역 데이터에 접근합니다:

```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 %}
```

### 번역 속성

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| code | String | 언어 코드 (예: "en", "ko") |
| url | String | 번역된 페이지의 URL |
| title | String | 번역된 페이지의 제목 |
| is_current | Bool | 현재 페이지의 언어인지 여부 |
| is_default | Bool | 기본 언어인지 여부 |

## SEO 태그

### 캐노니컬 URL

Hwaro는 다국어 페이지의 캐노니컬 링크 태그를 생성합니다:

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

출력:

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

### hreflang 태그

번역이 있는 페이지에는 대체 언어 링크 태그가 자동으로 생성됩니다:

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

출력:

```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/">
```

### SEO 태그 결합

캐노니컬 태그와 hreflang 태그를 함께 넣습니다:

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

## 페이지 언어

템플릿에서 현재 페이지의 언어에 접근합니다:

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

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

## 다국어 스캐폴드

다국어를 지원하는 새 사이트를 만듭니다:

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

지정한 언어별로 설정과 샘플 콘텐츠 파일이 생성됩니다.

## 템플릿 예시

### 언어 전환 (드롭다운)

```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 %}
```

### 언어별 내비게이션

```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>
```

### 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 번역 파일

내비게이션 레이블, 버튼 텍스트 같은 UI 문자열은 `i18n/` 디렉터리에 언어별 TOML 파일을 두어 번역할 수 있습니다.

### 파일 구조

언어마다 TOML 파일을 하나씩 만듭니다:

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

### 번역 파일 형식

```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 = "뒤로"
```

중첩된 TOML 섹션은 점으로 구분한 키로 평탄화됩니다 (예: `nav.home`, `common.read_more`).

### 템플릿 사용

`t` 필터로 키를 번역합니다:

```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>
```

### 폴백 동작

1. 현재 페이지 언어에서 키를 찾습니다
2. 없으면 기본 언어(`default_language`)로 폴백합니다
3. 그래도 없으면 키 자체를 반환합니다 (예: `"nav.home"`)

### 복수형 처리

개수에 따라 달라지는 문자열에는 `pluralize` 필터를 사용합니다:

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

## 언어별 피드

다국어 사이트에서는 Hwaro가 언어별로 별도의 RSS/Atom 피드를 자동 생성합니다:

| 언어 | 피드 경로 | 내용 |
|----------|-----------|----------|
| 기본 언어 (예: `en`) | `/rss.xml` | 기본 언어 페이지만 (설정으로 변경 가능) |
| 비기본 언어 (예: `ko`) | `/ko/rss.xml` | 한국어 페이지만 |
| 비기본 언어 (예: `ja`) | `/ja/rss.xml` | 일본어 페이지만 |

기본적으로 메인 사이트 피드(`/rss.xml` 또는 `/atom.xml`)에는 **기본 언어 페이지만** 포함됩니다. 이 동작은 `default_language_only` 옵션으로 바꿀 수 있습니다. `generate_feed = true`인 비기본 언어는 이 설정과 무관하게 각자의 언어 접두사 아래에 자체 피드를 갖습니다.

### 설정

#### 메인 피드 언어 제어

```toml
[feeds]
enabled = true
default_language_only = true   # true(기본값): 메인 피드에 기본 언어만 포함
                               # false: 메인 피드에 모든 언어 포함
```

#### 언어별 피드 제어

```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
```

언어 피드는 전역 `[feeds]` 설정의 `sections`, `limit`, `truncate`, `full_content` 값을 그대로 사용합니다:

```toml
[feeds]
enabled = true
type = "rss"           # 또는 "atom"
limit = 20
truncate = 0
full_content = true    # false = 설명/요약만 포함
sections = []          # 비워 두면 모든 섹션
default_language_only = true
```

### 피드 세부 사항

- **RSS 피드**에는 `<language>` 태그가 포함됩니다 (예: `<language>ko</language>`)
- **Atom 피드**에는 `xml:lang` 속성이 포함됩니다 (예: `<feed xmlns="..." xml:lang="ko">`)
- 피드 제목에 언어 이름이 붙습니다: `"My Site (한국어)"`
- 자기 참조 링크는 해당 언어 경로를 가리킵니다 (예: `https://example.com/ko/rss.xml`)
- 초안 페이지와 섹션 인덱스 페이지는 제외됩니다
- 언어 피드는 메인 피드의 `enabled` 설정과 무관하게 생성됩니다

### 템플릿 링크

템플릿에 언어별 피드 링크를 추가합니다:

```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 %}
```

## 함께 보기

- [설정](/ko/start/config/) — 전체 설정 레퍼런스
- [SEO](/ko/features/seo/) — 피드, 캐노니컬, hreflang 등 SEO 기능
- [데이터 모델](/ko/templates/data-model/) — 번역 링크 속성

---

Title: 자동 OG 이미지
URL: https://hwaro.hahwul.com/ko/features/og-images/
Source: content/features/og-images.ko.md
Language: ko

Hwaro는 프론트 매터에 커스텀 `image`가 없는 모든 페이지에 1200x630 Open Graph 미리보기 이미지를 자동 생성합니다. 생성된 경로가 `page.image`로 설정되므로 `og:image` 메타 태그가 자동으로 이를 사용하므로 템플릿을 고칠 필요가 없습니다.

![자동 OG 이미지 페이지의 자동 생성 OG 이미지](/og-images/features-og-images.png)
*이 페이지의 자동 생성 OG 이미지 (`style = "terminal"`).*

## 빠른 시작

```toml
[og.auto_image]
enabled = true
style = "terminal"
accent_color = "#2ee66b"
logo = "static/logo.png"
```

## 설정

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | `false` | 자동 OG 이미지 생성 여부 |
| style | string | `"default"` | 구성 프리셋 — [스타일 프리셋](#스타일-프리셋) 참고 |
| background | string | `"#171310"` | 배경색(hex) |
| text_color | string | `"#f4ede4"` | 제목과 설명의 텍스트 색 |
| accent_color | string | `"#ec7a66"` | 룰, 브랜드 마크, 색 블록에 쓰는 액센트 색 |
| secondary_color | string | — | 투톤 스타일(`split`, `brutalist`, `bauhaus`, …)의 두 번째 색. 생략하면 `accent_color`에서 자동 파생 |
| font_size | int | `48` | 제목 폰트 크기(px). 더 큰 값을 지정하지 않으면 각 스타일이 자체 스케일로 자동 확대 |
| logo | string | — | 이미지에 삽입할 로고 파일 경로 (예: `static/logo.png`) |
| logo_position | string | `"bottom-left"` | `bottom-left`, `bottom-right`, `top-left`, `top-right` |
| show_title | bool | `true` | 사이트 이름 표시 (하단 브랜드 행, 또는 스타일별 자리 — 아이브로, 키커, 창 제목 표시줄) |
| output_dir | string | `"og-images"` | 생성 이미지를 담을 디렉터리 |
| format | string | `"png"` | `"png"` 또는 `"svg"`. 소셜 플랫폼은 SVG `og:image`를 렌더링하지 않으므로 PNG가 기본값 |
| font_path | string | — | PNG 출력용 커스텀 `.ttf`/`.otf`. 폰트 체인의 맨 앞에 오고, 없는 글리프는 번들 폰트로 대체 |
| background_image | string | — | 텍스트 뒤에 합성할 배경 사진 |
| overlay_opacity | float | `0.45` | `background` 색이 사진을 덮는 정도 (0.0 = 사진 그대로, 1.0 = 사진 가림) |
| text_panel | float | `0.0` | 0.0–0.6. 복잡한 배경에서 가독성을 높이는 텍스트 뒤 소프트 패널 |
| pattern_opacity | float | `0.35` | 패턴 스타일(`dots`, `grid`, …)의 최대 알파. 각 패턴은 이 값을 정점으로 내부에서 점차 옅어짐 |
| pattern_scale | float | `1.0` | 패턴 스타일의 배율 (최소 0.1) |
| accent_bars | bool | `false` | 패턴 스타일에 클래식한 얇은 상/하단 액센트 바 추가 |
| lazy_generate | bool | `false` | `hwaro serve`에서 일괄 생성을 건너뛰고 첫 요청 때 렌더링. 대규모 사이트에 권장. `hwaro build`에는 영향 없음 |

제목은 Space Grotesk, 설명은 Space Grotesk Medium, `terminal` 스타일은 JetBrains Mono로 렌더링됩니다. 모두 바이너리에 번들되어 있어 PNG 출력이 어떤 머신에서든 동일합니다. 제목에 필요하면 CJK를 지원하는 시스템 폰트가 체인에 자동으로 추가되고, 그 밖의 모든 경우는 DejaVu Sans Bold가 받쳐 줍니다.

## 스타일 프리셋

`style` 옵션이 구성 전체를 결정합니다. 아래 미리보기를 클릭하면 확대됩니다.

**Signature** — 그 자체로 완결된 구성:

| 스타일 | 설명 |
|-------|-------------|
| `terminal` | 신호등 버튼, `$` 프롬프트, 블록 커서가 있는 코드 에디터 창. 개발 블로그와 문서용 |
| `bauhaus` | 액센트/보조/파생 색으로 구성한 평면 기하학 아트 포스터 도형 |
| `halftone` | 오른쪽 가장자리에서 번져 들어오는 인쇄풍 하프톤 도트 필드 |

**Modern** — 생성된 배경 위의 타이포그래피 중심 구성:

| 스타일 | 설명 |
|-------|-------------|
| `editorial` | 잡지 표지풍: 헤어라인 룰, 대문자 사이트명 키커, 세로 액센트 룰. 무난하고 조화로운 기본 선택지 |
| `artistic` | 필름 그레인을 더한 메시 그라디언트 색 필드. 완성도 높은 풍부한 느낌 |
| `hero` | 스포트라이트 글로우, 제목 첫 단어의 거대한 고스트 에코, 포스터 타이포그래피 |
| `surreal` | 오로라 구체와 흐르는 리본 밴드에 그레인을 더한 구성 |
| `monument` | 극단적 미니멀리즘 — 거대한 타이포, 넓은 여백, 제목 위 액센트 룰, 오른쪽 아래 브랜드 행 |
| `framed` | 초대장 카드: 중립 색 헤어라인 프레임에 액센트 코너 브래킷과 가운데 정렬 타이포 |

**Geometric** — 대담한 평면 색 블로킹:

| 스타일 | 설명 |
|-------|-------------|
| `split` | 왼쪽 대각선 투톤 색 블록, 오른쪽 제목 |
| `band` | 제목을 뚫어낸 전체 폭 색 밴드와 그 위를 받치는 얇은 룰 — 잡지 표지 스타일 |
| `brutalist` | 강한 오프셋 그림자와 거대한 타이포가 있는 두꺼운 프레임 패널 |

**Patterns** — 초점이 있는 구성 (각 패턴은 `pattern_opacity`를 정점으로 내부에서 점차 옅어짐):

| 스타일 | 설명 |
|-------|-------------|
| `default` | 머스트헤드: 상단의 대문자 사이트명 아이브로, 낮은 코너 글로우, 은은한 비네트 |
| `minimal` | 타이포만 — 제목 뒤의 액센트 마침표가 전부 |
| `dots` | 오른쪽 위 모서리에서 번져 들어오는 엇갈린 하프톤 도트 |
| `grid` | 초점 크로스헤어와 레지스트레이션 마크가 있는 가는 청사진 그리드 |
| `diagonal` | 오른쪽 아래 모서리의 45° 스트라이프 쐐기와 빗변의 액센트 룰 |
| `gradient` | 코너 글로우, 비네트, 그레인이 있는 액센트 톤 듀오톤 워시 |
| `waves` | 아래 가장자리에 겹겹이 쌓인 물결 밴드 |

### 미리보기

<div class="og-style-grid">
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-terminal.png" alt="terminal 스타일" loading="lazy" />
    <span class="og-style-label"><code>terminal</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-terminal.png" alt="terminal 스타일" />
        <p><code>terminal</code> — 프롬프트와 커서가 있는 코드 에디터 창</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-bauhaus.png" alt="bauhaus 스타일" loading="lazy" />
    <span class="og-style-label"><code>bauhaus</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-bauhaus.png" alt="bauhaus 스타일" />
        <p><code>bauhaus</code> — 평면 기하학 아트 포스터 도형</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-halftone.png" alt="halftone 스타일" loading="lazy" />
    <span class="og-style-label"><code>halftone</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-halftone.png" alt="halftone 스타일" />
        <p><code>halftone</code> — 인쇄풍 하프톤 도트 페이드</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-editorial.png" alt="editorial 스타일" loading="lazy" />
    <span class="og-style-label"><code>editorial</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-editorial.png" alt="editorial 스타일" />
        <p><code>editorial</code> — 잡지 표지풍: 룰, 키커, 세로 액센트 룰</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-artistic.png" alt="artistic 스타일" loading="lazy" />
    <span class="og-style-label"><code>artistic</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-artistic.png" alt="artistic 스타일" />
        <p><code>artistic</code> — 필름 그레인을 더한 메시 그라디언트 색 필드</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-hero.png" alt="hero 스타일" loading="lazy" />
    <span class="og-style-label"><code>hero</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-hero.png" alt="hero 스타일" />
        <p><code>hero</code> — 고스트 타이포 에코가 있는 스포트라이트 글로우</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-surreal.png" alt="surreal 스타일" loading="lazy" />
    <span class="og-style-label"><code>surreal</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-surreal.png" alt="surreal 스타일" />
        <p><code>surreal</code> — 오로라 구체와 흐르는 리본</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-monument.png" alt="monument 스타일" loading="lazy" />
    <span class="og-style-label"><code>monument</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-monument.png" alt="monument 스타일" />
        <p><code>monument</code> — 제목 위 액센트 룰과 거대한 타이포</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-framed.png" alt="framed 스타일" loading="lazy" />
    <span class="og-style-label"><code>framed</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-framed.png" alt="framed 스타일" />
        <p><code>framed</code> — 액센트 코너 브래킷이 있는 헤어라인 프레임</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-split.png" alt="split 스타일" loading="lazy" />
    <span class="og-style-label"><code>split</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-split.png" alt="split 스타일" />
        <p><code>split</code> — 대각선 투톤 색 블록</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-band.png" alt="band 스타일" loading="lazy" />
    <span class="og-style-label"><code>band</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-band.png" alt="band 스타일" />
        <p><code>band</code> — 뚫어낸 제목 뒤의 잡지풍 색 밴드</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-brutalist.png" alt="brutalist 스타일" loading="lazy" />
    <span class="og-style-label"><code>brutalist</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-brutalist.png" alt="brutalist 스타일" />
        <p><code>brutalist</code> — 강한 오프셋 그림자가 있는 두꺼운 프레임 패널</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-default.png" alt="default 스타일" 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.png" alt="default 스타일" />
        <p><code>default</code> — 머스트헤드: 아이브로, 코너 글로우, 비네트</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-minimal.png" alt="minimal 스타일" 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.png" alt="minimal 스타일" />
        <p><code>minimal</code> — 타이포와 액센트 마침표만</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-dots.png" alt="dots 스타일" 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.png" alt="dots 스타일" />
        <p><code>dots</code> — 오른쪽 위에서 번져 들어오는 하프톤 도트</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-grid.png" alt="grid 스타일" 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.png" alt="grid 스타일" />
        <p><code>grid</code> — 초점 크로스헤어가 있는 청사진 그리드</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-diagonal.png" alt="diagonal 스타일" 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.png" alt="diagonal 스타일" />
        <p><code>diagonal</code> — 액센트 빗변 룰이 있는 스트라이프 쐐기</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-gradient.png" alt="gradient 스타일" 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.png" alt="gradient 스타일" />
        <p><code>gradient</code> — 글로우, 비네트, 그레인이 있는 듀오톤 워시</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/style-waves.png" alt="waves 스타일" 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.png" alt="waves 스타일" />
        <p><code>waves</code> — 아래 가장자리에 겹겹이 쌓인 물결 밴드</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>

## 배경 이미지

사진을 텍스트 뒤에 합성합니다:

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

렌더링 순서는 배경색 → 사진 → 색 오버레이 → 스타일 구성 → 텍스트/로고입니다. `overlay_opacity`는 배경색이 사진을 얼마나 덮을지 결정합니다. 자체 배경을 생성하는 스타일(`artistic`, `hero`, `surreal`)은 사진이 설정되면 배경 생성을 건너뛰어 사진이 그대로 드러납니다.

### 미리보기

아래 예시는 `overlay_opacity`만 다릅니다 (같은 사진, `style = "editorial"`, 검정에 가까운 `background`). 클릭하면 확대됩니다.

<div class="og-style-grid">
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/bg-image-low.png" alt="오버레이가 낮은 배경 이미지" loading="lazy" />
    <span class="og-style-label"><code>overlay_opacity = 0.3</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/bg-image-low.png" alt="오버레이가 낮은 배경 이미지" />
        <p><code>overlay_opacity = 0.3</code> — 사진이 선명하게 유지됨</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/bg-image-mid.png" alt="오버레이가 중간인 배경 이미지" loading="lazy" />
    <span class="og-style-label"><code>overlay_opacity = 0.55</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/bg-image-mid.png" alt="오버레이가 중간인 배경 이미지" />
        <p><code>overlay_opacity = 0.55</code> — 사진과 텍스트의 균형</p>
      </div>
    </dialog>
  </div>
  <div class="og-style-card" onclick="this.querySelector('dialog').showModal()">
    <img src="/images/og-style-examples/bg-image-high.png" alt="오버레이가 높은 배경 이미지" loading="lazy" />
    <span class="og-style-label"><code>overlay_opacity = 0.8</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/bg-image-high.png" alt="오버레이가 높은 배경 이미지" />
        <p><code>overlay_opacity = 0.8</code> — 사진은 어둡게, 텍스트가 도드라짐</p>
      </div>
    </dialog>
  </div>
</div>

## 출력 포맷

PNG가 기본값입니다. stb_truetype과 stb_image_write로 자체 렌더링하므로 외부 도구가 필요 없습니다. 시스템 폰트는 자동 감지되며(macOS는 Helvetica/Arial, Linux는 DejaVu/Liberation/Noto), 최후 수단으로 번들된 DejaVu Sans Bold를 사용합니다.

CJK 문자가 들어간 제목에는 CJK를 지원하는 `font_path`(예: Noto Sans CJK)가 필요합니다. 번들 폰트는 라틴 문자만 지원합니다.

의존성 없는 SVG 출력이 필요하면 `format = "svg"`로 설정합니다. 다만 소셜 플랫폼은 일반적으로 SVG `og:image`를 렌더링하지 않습니다.

## 증분 생성

Hwaro는 생성 이미지 옆에 `.og_manifest.json`을 저장하고 입력이 바뀌지 않은 페이지를 건너뜁니다. 빌드 간에 출력 디렉터리를 유지하면(예: `--cache` 모드) 증분 생성이 자동으로 동작합니다. `hahwul/hwaro` GitHub Action은 이를 알아서 처리합니다.

| 변경 | 재생성 대상 |
|--------|-------------|
| 페이지 제목, 설명, URL | 해당 페이지만 |
| OG 설정, 또는 로고/배경 이미지의 **파일 내용** | 전체 페이지 |
| 디스크에 이미지 파일이 없음 | 해당 페이지만 |

## 개발 서버 속도 개선

OG 생성은 대규모 사이트에서 가장 비용이 큰 빌드 단계 중 하나입니다. 두 가지 방법이 있습니다:

- `lazy_generate = true` — `hwaro serve`가 일괄 생성을 건너뛰고, 각 이미지는 해당 페이지의 첫 요청 때 렌더링된 뒤 캐시됩니다. `hwaro build`에는 영향이 없습니다. `hwaro serve --fast-start`와 잘 어울립니다.
- `hwaro build --skip-og-image` — OG 이미지를 아예 건너뜁니다.

## 동작

- 프론트 매터에 커스텀 `image`가 있는 페이지는 그대로 유지하고, 초안은 건너뜁니다
- 긴 제목은 자동으로 줄바꿈됩니다 (CJK 인식)
- 로고와 배경 이미지는 한 번만 로드해 전체 페이지에서 재사용합니다

## 출력

`/posts/hello-world/` 페이지는 `public/og-images/posts-hello-world.png`와 다음 태그를 만듭니다:

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

특정 페이지에 커스텀 이미지를 쓰려면 프론트 매터에 `image`를 설정합니다:

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

## 함께 보기

- [SEO](/ko/features/seo/) — OpenGraph, Twitter 카드, 메타 태그
- [이미지 처리](/ko/features/image-processing/) — 반응형 이미지 리사이징
- [설정](/ko/start/config/) — 전체 설정 레퍼런스

---

Title: 출력 포맷
URL: https://hwaro.hahwul.com/ko/features/output-formats/
Source: content/features/output-formats.ko.md
Language: ko

모든 페이지와 섹션이 항상 렌더링하는 HTML 페이지 외에, Hwaro는 나란히 놓이는 비HTML 파일도 추가로 렌더링할 수 있습니다. 글의 JSON 표현, 섹션의 피드 형태 XML 목록, 일반 텍스트 내보내기 같은 것들입니다. HTML 렌더링에는 영향이 없으며, 추가 포맷은 어디까지나 덧붙는 것입니다.

사이트의 RSS/Atom 피드 마크업을 커스터마이즈하려는 거라면, 그건 출력 포맷이 아니라 [커스텀 피드 템플릿](/ko/features/seo/#커스텀-피드-템플릿)(`templates/rss.xml.jinja`)입니다.

## 설정

```toml
[outputs]
page = []                 # 예: ["json"] — 모든 일반 페이지가 내보내는 포맷
section = ["json"]        # 모든 섹션 인덱스가 내보내는 포맷
sections = []              # 선택적 섹션 이름 허용 목록. 비어 있으면 전체
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| page | array | [] | 모든 일반 페이지가 내보내는 포맷 |
| section | array | [] | 모든 섹션 인덱스가 내보내는 포맷 |
| sections | array | [] | `section` 출력을 제한할 섹션 이름(과 그 하위). 비어 있으면 모든 섹션 |

지원되는 포맷은 네 가지뿐이며, 포맷 이름이 곧 파일 확장자입니다.

```
json  txt  xml  csv
```

`[outputs]`에 알 수 없는 포맷 이름이 있으면 조용히 아무것도 출력하지 않는 대신, 분류된 설정 오류와 함께 빌드가 즉시 실패합니다.

`sections`는 섹션 이름 자체 또는 그 하위 어느 것과도 매칭됩니다(`"posts"` 값은 `"posts/reviews"`에도 매칭). `[feeds].sections`와 같은 규칙입니다.

## 프론트 매터 오버라이드

페이지(또는 섹션)는 프론트 매터의 최상위 `outputs` 키로 설정 기본값을 덮어쓸 수 있습니다.

```toml
+++
title = "My Post"
outputs = ["json"]
+++
```

`outputs`는 일급 프론트 매터 필드가 아닙니다. 다른 알 수 없는 최상위 키처럼 `page.extra["outputs"]`에 담기고 템플릿에는 `page.extra.outputs`로 노출됩니다. 프론트 매터에 이 키가 *존재*하기만 하면 명시적인 빈 목록을 포함해 항상 설정 기본값을 이깁니다.

```toml
+++
title = "Opt this page out"
outputs = []
+++
```

이렇게 하면 `config.toml`의 `[outputs].page`가 비어 있지 않더라도 그 한 페이지의 모든 포맷이 억제됩니다. 키가 아예 없으면 설정 기본값(섹션의 경우 `sections` 허용 목록 포함)이 적용됩니다.

일반적인 `extra` 값이므로 다른 extra 필드처럼 섹션의 `[cascade.extra]` 테이블을 통해 캐스케이드되기도 합니다.

```toml
+++
title = "Blog"

[cascade.extra]
outputs = ["json"]
+++
```

이렇게 하면 페이지가 직접 설정하지 않는 한 모든 하위 페이지가 `outputs = ["json"]`을 갖습니다. 형식이 잘못된 오버라이드(배열이 아니거나 `json`/`txt`/`xml`/`csv` 밖의 이름을 포함)는 1회성 빌드 경고와 함께 무시됩니다. 빌드를 실패시키는 대신 해당 페이지는 추가 포맷 없음으로 처리됩니다.

## 템플릿

활성화된 각 포맷은 전용 Crinja 템플릿에서 렌더링됩니다. 템플릿 이름은 `page.html`/`section.html`과 같은 관례로 확장자를 따릅니다.

```
templates/page.json.jinja
templates/section.json.jinja
templates/page.xml.jinja
```

Hwaro가 템플릿을 로드할 때는 마지막의 인식되는 템플릿 확장자(`.html`, `.j2`, `.jinja2`, `.jinja`, `.ecr`)만 제거하고, `.json`/`.xml` 부분은 템플릿 이름의 일부로 남습니다. 예를 들어 `templates/page.json.jinja`는 `page.json`으로 로드됩니다.

페이지 자신의 본문 마크다운/콘텐츠, `toc`, 그리고 `page.html`/`section.html`에서 평소 쓸 수 있는 다른 모든 값(`page`, `section`, `site`, `config`, …)을 포맷 템플릿에서도 쓸 수 있습니다. 포맷에 필요한 것을 자유롭게 작성하면 됩니다. 예:

```jinja
{# templates/page.json.jinja #}
{
  "title": {{ page.title | tojson }},
  "url": "{{ page.url }}",
  "date": "{{ page.date }}"
}
```

```jinja
{# templates/section.json.jinja #}
{
  "title": {{ section.title | tojson }},
  "pages": [
    {% for p in section.pages %}
    "{{ p.url }}"{% if not loop.last %},{% endif %}
    {% endfor %}
  ]
}
```

### 템플릿 선택 체인

주어진 페이지/섹션과 활성화된 포맷 `<fmt>`에 대해 Hwaro는 다음 순서로 시도합니다.

1. `<entry-template>.<fmt>` — 페이지가 실제로 해석되는 템플릿의 포맷별 형제(프론트 매터가 `template = "post"`라면 `post.json`을 먼저 찾음)
2. `section.<fmt>` — 섹션만
3. `page.<fmt>` — 최종 폴백

**활성화된 포맷의 템플릿이 없으면 하드 빌드 오류입니다.** 후보가 하나도 없으면 빌드가 즉시 실패하고 시도한 템플릿 이름을 모두 나열합니다. 예:

```
Error [HWARO_E_TEMPLATE]: No template found for output format 'txt' on about.md. Tried: page.txt.
Create one of: templates/page.txt.jinja.
```

이는 의도된 동작입니다. 설정이나 프론트 매터에서 켠 포맷이 조용히 아무것도 만들지 않는 것이, 시끄럽게 실패하는 것보다 더 나쁜 실패 방식이기 때문입니다.

## 출력 위치

포맷은 페이지의 `index.html` 옆에 나란히 `index.<fmt>`로 렌더링됩니다.

```
public/
  posts/hello/index.html
  posts/hello/index.json   <- [outputs].page = ["json"]
```

## 페이지네이션

포맷은 페이지/섹션당 한 번만, 즉 **1페이지에만** 적용됩니다. 페이지네이션된 섹션의 `/page/2/`, `/page/3/`, …는 평소처럼 HTML을 출력하지만 자체 `index.<fmt>`는 절대 생기지 않습니다. 섹션 자신의 URL에만 생성됩니다.

## `alternate_output_tags`

활성화된 모든 포맷은 `<link rel="alternate" type="…">` 태그를 얻으며, `page.html`/`section.html`에서 `{{ alternate_output_tags }}`로 쓸 수 있습니다(포맷이 없는 페이지에서는 빈 문자열).

```jinja
<head>
  {{ alternate_output_tags }}
</head>
```

`outputs = ["json"]`인 페이지에서는 다음과 같이 렌더링됩니다.

```html
<link rel="alternate" type="application/json" href="https://example.com/posts/hello/index.json">
```

href는 `canonical`/`hreflang` 링크와 같은 방식으로 `base_url`을 거쳐 해석되므로, 서브패스 배포(`base_url = "https://user.github.io/repo"`)에서도 올바릅니다.

## 결정성

포맷 템플릿은 `page.html`과 같은 렌더링 파이프라인을 거칩니다. 빌드 간에 바이트 단위로 동일한 출력을 원한다면 포맷 템플릿에서 `now()` 같은 비결정적 값을 피합니다([증분 빌드](/ko/features/incremental-build/) 참고).

## 알려진 제한: `--cache`에서 포맷 비활성화

`[outputs]`(또는 페이지 프론트 매터)에서 포맷을 제거해도 *이전* 빌드가 `--cache`로 이미 써 둔 파일이 소급해서 삭제되지는 않습니다. 증분 빌드는 변경으로 감지된 페이지만 다시 렌더링하는데, "설정에서 포맷이 제거됨"은 파일별 변경으로 추적되지 않기 때문입니다. 포맷을 끈 뒤에는 전체(비증분) 빌드를 실행해 남아 있는 `index.<fmt>` 파일을 정리합니다.

## 함께 보기

- [설정](/ko/start/config/) — 전체 설정 레퍼런스
- [섹션](/ko/writing/sections/#캐스케이드) — `[cascade.extra]`와 캐스케이드 가능한 키
- [데이터 모델](/ko/templates/data-model/) — `page.extra`
- [증분 빌드](/ko/features/incremental-build/) — `--cache` 의미론

---

Title: 페이지네이션
URL: https://hwaro.hahwul.com/ko/features/pagination/
Source: content/features/pagination.ko.md
Language: ko

긴 콘텐츠 목록을 여러 페이지로 나눕니다.

## 설정

### 사이트 전역 기본값

`config.toml`에서 기본 페이지네이션 동작을 설정합니다.

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | 페이지네이션 전역 활성화 |
| per_page | int | 10 | 페이지당 기본 항목 수 |

### 섹션 페이지네이션

섹션 프론트 매터에서 활성화합니다.

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

| 필드 | 타입 | 기본값 | 설명 |
|-------|------|---------|-------------|
| paginate | int | — | 페이지당 항목 수 |
| paginate_path | string | "page" | 페이지 URL 패턴 |

### 생성되는 URL

`/blog/` 섹션 기준:

| 페이지 | URL |
|------|-----|
| 1 | /blog/ |
| 2 | /blog/page/2/ |
| 3 | /blog/page/3/ |

`paginate_path = "p"`인 경우:

| 페이지 | URL |
|------|-----|
| 1 | /blog/ |
| 2 | /blog/p/2/ |
| 3 | /blog/p/3/ |

## 템플릿 변수

### pagination

미리 렌더링된 페이지네이션 HTML:

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

### paginator

커스텀 렌더링을 위한 페이지네이션 객체:

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| paginator.paginate_by | Int | 페이지당 항목 수 |
| paginator.base_url | String | 페이지네이션 기준 URL |
| paginator.number_pagers | Int | 전체 페이저(페이지) 수 |
| paginator.first | String | 첫 페이저 URL |
| paginator.last | String | 마지막 페이저 URL |
| paginator.previous | String? | 이전 페이저 URL |
| paginator.next | String? | 다음 페이저 URL |
| paginator.pages | Array | 현재 페이저에 담긴 페이지 배열 |
| paginator.current_index | Int | 현재 페이저 인덱스(1부터 시작) |
| paginator.total_pages | Int | 전체 페이지 수 |

### pagination_obj

페이지네이션 마크업을 처음부터 직접 만들 수 있도록 개별 필드를 담은 구조화된 페이지네이션 객체:

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| pagination_obj.html | String | 미리 렌더링된 페이지네이션 HTML(`pagination`과 동일) |
| pagination_obj.current_page | Int | 현재 페이지 번호(1부터 시작) |
| pagination_obj.total_pages | Int | 전체 페이지 수 |
| pagination_obj.per_page | Int | 페이지당 항목 수 |
| pagination_obj.total_items | Int | 전체 페이지를 합친 항목 수 |
| pagination_obj.has_previous | Bool | 이전 페이지 존재 여부 |
| pagination_obj.has_next | Bool | 다음 페이지 존재 여부 |
| pagination_obj.previous_url | String | 이전 페이지 URL(없으면 빈 문자열) |
| pagination_obj.next_url | String | 다음 페이지 URL(없으면 빈 문자열) |
| pagination_obj.first_url | String | 첫 페이지 URL |
| pagination_obj.last_url | String | 마지막 페이지 URL |

```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 %}
```

## 템플릿 예시

### 간단한 내비게이션

미리 렌더링된 `pagination` 변수를 사용합니다.

```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 %}
```

### 커스텀 페이지네이션

`paginator` 객체로 페이지네이션 UI를 직접 만듭니다.

```jinja
{% if paginator.number_pagers > 1 %}
<nav class="pagination">
  {% if paginator.current_index > 1 %}
  <a href="{{ paginator.first }}">« First</a>
  {% endif %}

  {% if paginator.previous %}
  <a href="{{ paginator.previous }}" class="prev">‹ Prev</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 %}

  {% if paginator.current_index < paginator.number_pagers %}
  <a href="{{ paginator.last }}">Last »</a>
  {% endif %}
</nav>
{% endif %}
```

## 페이지가 많을 때의 줄임표

페이지가 7개를 넘으면 내장 페이지네이션 내비게이션이 UI를 간결하게 유지하기 위해 줄임표(`...`)를 자동으로 넣습니다. 현재 페이지를 중심으로 페이지 번호 5개의 슬라이딩 윈도가 표시되고, 첫 페이지와 마지막 페이지는 항상 보입니다.

예를 들어 20페이지 중 5페이지에서는:

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

## SEO 링크

Hwaro는 페이지네이션된 페이지에 `<link rel="prev">`와 `<link rel="next">` 태그를 생성합니다. `<head>`에 포함하면 됩니다.

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

출력:

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

## 택소노미 페이지네이션

택소노미 항목 페이지는 `config.toml`의 `paginate_by`로 페이지네이션을 지원합니다.

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

각 항목 목록(예: `/tags/crystal/`)이 20개씩 페이지로 나뉘고, 이후 페이지는 `/tags/crystal/page/2/`에 생성됩니다. 택소노미 템플릿에서도 동일한 `pagination`, `paginator` 템플릿 변수를 사용할 수 있습니다.

## CSS 예시

```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;
}
```

## 함께 보기

- [섹션](/ko/writing/sections/) — 섹션 설정
- [택소노미](/ko/writing/taxonomies/) — 택소노미 페이지네이션
- [데이터 모델](/ko/templates/data-model/) — 섹션 변수

---

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

Hwaro는 프로그레시브 웹 앱(PWA) 파일을 생성해 사이트의 오프라인 접근과 앱 설치를 지원합니다.

## 생성되는 파일

`[pwa]`를 활성화하면 빌드 출력에 두 파일이 추가됩니다:

- **`manifest.json`** — 앱 이름, 아이콘, 테마, 표시 모드를 기술하는 웹 앱 매니페스트
- **`sw.js`** — 캐시 우선 전략으로 오프라인 캐싱을 처리하는 서비스 워커

## 설정

```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"]
cache_strategy = "cache-first"
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | PWA 파일 생성 활성화 |
| name | string | 사이트 제목 | 전체 애플리케이션 이름 |
| short_name | string | name | 홈 화면용 짧은 이름 |
| theme_color | string | "#ffffff" | 브라우저 툴바/상태 표시줄 색상 |
| background_color | string | "#ffffff" | 스플래시 화면 배경색 |
| display | string | "standalone" | 표시 모드: `fullscreen`, `standalone`, `minimal-ui`, `browser` 중 하나 (알 수 없는 값은 `standalone`으로 대체) |
| start_url | string | "/" | 앱 실행 시 열리는 URL |
| icons | array | [] | 아이콘 파일 경로 |
| offline_page | string | — | 오프라인일 때 보여줄 폴백 페이지 |
| precache_urls | array | [] | 서비스 워커 설치 시 미리 캐시할 URL |
| cache_strategy | string | `"cache-first"` | 에셋 요청 전략: `cache-first`, `network-first`, `stale-while-revalidate` |

> `start_url`, `icons`, `offline_page`, `precache_urls`는 `base_url` 접두사 **없이** 루트 기준 경로로 적습니다 (예: `"/repo/"`가 아니라 `start_url = "/"`). `base_url`에 서브패스가 포함된 경우(GitHub Pages 프로젝트 사이트)에는 생성되는 `manifest.json`과 `sw.js`에 Hwaro가 자동으로 접두사를 붙입니다.

## 아이콘 크기

각 아이콘의 `sizes` 값은 파일 자체에서 측정합니다. PNG, JPEG, BMP 헤더에서
읽은 실제 픽셀 크기입니다. 브라우저는 이 값을 보고 설치 아이콘을 고르므로,
추측한 값보다 측정한 값을 항상 우선합니다.

| 아이콘 | 선언되는 `sizes` |
|--------|------------------|
| `logo.png` (디스크상 200x60) | 200x60 |
| `icon-2024.jpg` (디스크상 192x192) | 192x192 |
| `favicon.svg` | `any` (벡터 — 픽셀 크기 없음) |
| `icon-192.png` (읽을 수 없음 / 없음) | 192x192 (파일 이름에서) |
| `icon-512x512.png` (읽을 수 없음 / 없음) | 512x512 (파일 이름에서) |
| `logo.webp`, `https://cdn.example/icon.png` | 파일 이름에서, 없으면 512x512 |

파일 이름 기반 추정은 대비책일 뿐입니다. Hwaro가 헤더를 읽을 수 없는 형식
(WebP, ICO), 원격 `http(s)://` 아이콘, 그리고 바이트를 읽지 못한 파일에만
적용되며, 그 경우 빌드 경고가 해당 아이콘을 알려줍니다.

아이콘 파일은 빌드 출력으로 복사되도록 `static/` 디렉터리에 둡니다.

## 템플릿 연동

가장 간단한 방법은 `{{ pwa_tags }}` 템플릿 변수입니다. 매니페스트 링크, theme-color 메타, 서비스 워커 등록 스크립트로 전개되며(베이스 경로 접두사 포함), `[pwa]`가 비활성일 때는 빈 문자열로 렌더링됩니다. 스캐폴드 헤더 템플릿에는 기본으로 포함돼 있습니다:

```jinja
<head>
  {{ pwa_tags }}
</head>
```

직접 연동하려면 베이스 템플릿에 매니페스트 링크와 서비스 워커 등록 코드를 추가합니다:

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

> 서브패스 배포(예: `https://user.github.io/repo/`로 서비스되는 GitHub Pages
> 프로젝트 사이트)에서 매니페스트와 서비스 워커가 올바르게 로드되려면
> `{{ base_url }}` 접두사가 필요합니다. 생성된 `manifest.json`/`sw.js` 내부에는
> 이미 서브패스가 반영되어 있지만, `<link>`/`register()`의 URL에는 여기서 직접
> 붙여야 합니다.

## 캐싱 전략

생성되는 서비스 워커는 다음과 같이 동작합니다:

- **설치 시 프리캐시** — `precache_urls`에 나열한 URL과 `start_url`을 즉시 캐시합니다
- **에셋 요청** — `cache_strategy`로 제어합니다 (아래 참고)
- **내비게이션은 네트워크 우선** — 페이지 이동은 항상 네트워크를 먼저 시도하고, 실패하면 오프라인 페이지로 폴백합니다
- **자동 캐시 버전 관리** — 서비스 워커 활성화 시 오래된 캐시를 정리합니다

에셋(내비게이션 이외 요청)을 어떻게 제공할지는 `cache_strategy`로 선택합니다:

| 값 | 동작 |
|-------|----------|
| `cache-first` (기본값) | 캐시에 있으면 캐시에서 제공하고, 없으면 네트워크에서 가져와 캐시. 정적 사이트에서 가장 빠름 |
| `network-first` | 네트워크를 먼저 시도하고 실패하면 캐시로 폴백. 최신 콘텐츠와 오프라인 대응이 모두 필요할 때 사용 |
| `stale-while-revalidate` | 캐시된 사본을 즉시 제공하고 백그라운드에서 캐시를 갱신. 속도와 최신성의 균형 |

알 수 없는 값은 경고를 남기고 `cache-first`로 폴백합니다.

## 오프라인 페이지

`offline_page`를 설정했다면 해당 경로에 정적 HTML 페이지(예: `content/offline.md` 또는 `static/offline.html`)를 만들어 둡니다. 사용자가 오프라인 상태에서 페이지를 이동하면 이 페이지가 표시됩니다.

## 함께 보기

- [설정](/ko/start/config/) — 전체 설정 레퍼런스
- [SEO](/ko/features/seo/) — 사이트맵, 피드, OpenGraph

---

Title: 관련 글
URL: https://hwaro.hahwul.com/ko/features/related-posts/
Source: content/features/related-posts.ko.md
Language: ko

공유하는 택소노미 항목(태그, 카테고리 등)을 기반으로 관련 콘텐츠를 자동 추천합니다.

## 설정

`config.toml`에서 활성화합니다.

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | 관련 글 계산 활성화 |
| limit | int | 5 | 페이지당 관련 글 최대 개수 |
| taxonomies | array | ["tags"] | 유사도 계산에 쓰는 택소노미 이름 |

## 동작 방식

1. Hwaro가 택소노미 항목 → 페이지의 역색인을 만듭니다
2. 각 페이지마다 다른 페이지와 공유하는 택소노미 항목 수를 셉니다
3. 공유 항목이 많은 페이지가 더 높은 순위를 받습니다
4. 결과는 언어별로 필터링됩니다(다국어 사이트는 같은 언어의 글만 보여줌)
5. 상위 N개(`limit`까지)가 관련 글로 지정됩니다

초안 페이지, 인덱스 페이지, 생성된 페이지는 관련 글 계산에서 제외됩니다.

## 템플릿 변수

각 페이지는 관련 페이지를 관련도 순으로 담은 `related_posts` 배열을 갖습니다.

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| related_posts | array | 현재 페이지와 관련된 페이지들, 공유 항목 수 순 정렬 |

`related_posts`의 각 항목은 완전한 페이지 객체이므로 모든 페이지 변수(`title`, `url`, `description`, `date`, `tags` 등)에 접근할 수 있습니다.

## 템플릿에서 사용

### 기본 관련 글

```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 %}
```

### 태그와 함께 표시

```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 %}
```

## 여러 택소노미 사용

관련도를 높이기 위해 여러 택소노미를 기준으로 삼을 수 있습니다.

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

여러 택소노미에서 항목을 공유하는 글이 더 높은 순위를 받습니다. 예를 들어 어떤 글과 태그 2개, 카테고리 1개를 공유하는 글은 3점, 태그 1개만 공유하는 글은 1점입니다.

## 함께 보기

- [택소노미](/ko/writing/taxonomies/) — 점수 계산에 쓰이는 태그와 카테고리
- [시리즈](/ko/features/series/) — 순서 있는 콘텐츠 묶기
- [설정](/ko/start/config/) — 관련 글 설정 레퍼런스

---

Title: 원격 데이터 소스
URL: https://hwaro.hahwul.com/ko/features/remote-data/
Source: content/features/remote-data.ko.md
Language: ko

`[[data.remote]]`는 템플릿을 렌더링하기 전에 HTTP(S) 페이로드를
`site.data`로 가져옵니다. JSON API, 간단한 헤드리스 CMS 엔드포인트처럼 요청
하나로 끝나는 데이터 소스에 알맞습니다. 템플릿은 네트워크에 접근하지 않고,
모든 외부 의존성은 `config.toml` 한곳에 선언됩니다.

사이트와 함께 커밋하는 데이터는 `data/` 파일을 사용하세요. 원격 데이터와
로컬 데이터는 템플릿에서 같은 방식으로 접근하므로, 둘 사이에서 키를 옮겨도
템플릿을 바꿀 필요가 없습니다.

## 빠른 시작

```toml
[[data.remote]]
key = "team"                # site.data.team으로 노출
url = "https://api.example.com/team"
format = "json"             # 응답이 포맷을 알려 주면 생략 가능
headers = { Authorization = "Bearer ${API_TOKEN}" }
cache = "1h"                # 신선한 캐시 페이로드 재사용
on_error = "fail"           # fail | warn-and-use-cache | warn-and-skip
```

```jinja
{% for person in site.data.team %}
  <h2>{{ person.name }}</h2>
  <p>{{ person.role }}</p>
{% endfor %}
```

## 설정 레퍼런스

| 필드 | 필수 | 의미 |
|-------|----------|---------|
| `key` | 예 | `site.data` 아래 이름. 영문자, 숫자, `_`, `-`를 쓸 수 있고 대소문자를 구분하지 않고 고유해야 합니다. |
| `url` | 예 | 절대 `http://` 또는 `https://` URL. 다른 스킴은 설정 로딩 시 거부됩니다. |
| `format` | 아니오 | `json`, `toml`, `yaml`, `csv`. 생략하면 응답의 `Content-Type`, 그다음 리다이렉트 뒤 최종 URL 확장자로 판단합니다. 둘 다 알 수 없으면 명시하세요. |
| `headers` | 아니오 | 추가 요청 헤더. 자격 증명으로 취급하여 로그에 남기지 않으며, 리다이렉트가 원래 origin을 벗어나면 제거합니다. |
| `cache` | 아니오 | `"90s"`, `"30m"`, `"1h"`, `"7d"`, `"1h30m"` 같은 디스크 캐시 TTL. 캐시가 신선하면 요청하지 않습니다. |
| `on_error` | 아니오 | 가져오기/파싱 실패 정책: `fail`(기본값), `warn-and-use-cache`, `warn-and-skip`. |

CSV 데이터는 행 배열이 되며, 각 행은 공백을 제거한 문자열 배열입니다. 로컬
CSV에서 `load_data()`가 만드는 모양과 같습니다.

## 환경 변수

`url`, `headers`의 `${VAR}` 플레이스홀더는 환경 변수로 치환됩니다. 일반 설정
치환과 달리 여기서 없는 변수는 빌드를 실패시키고 변수 이름을 알려 줍니다. 빈
토큰으로 요청하는 실수를 막기 위해서입니다. 안전한 기본값이 있으면
`${VAR:-default}`를 사용하세요. 치환은 빌드가 소스를 가져올 때만 일어나므로
`hwaro deploy`, `hwaro new`, `hwaro tool ...`에는 변수가 필요하지 않습니다.

## 캐시, 오프라인 빌드, Serve

페이로드는 `hwaro serve`가 감시하지 않는 `.hwaro/remote_data/`에 저장됩니다.
캐시는 `hwaro build --full` 후에도 남고 Git에서 무시됩니다.

- `cache`를 설정하면 TTL이 남아 있는 동안 캐시를 재사용합니다. 설정하지 않은
  경우 새 `hwaro build`마다 다시 가져오지만, `warn-and-use-cache`용 마지막
  성공 페이로드는 보관합니다.
- `warn-and-use-cache`는 가져오기나 파싱이 실패하면 경고 후 저장된 페이로드를
  사용합니다. `warn-and-skip`은 경고 후 `site.data.<key>`를 이번 빌드에서
  비웁니다. 이 키는 템플릿에서 조건으로 감싸세요. `fail`은 빌드를 멈춥니다.
- 한 번의 `hwaro serve` 세션에서는 변하지 않은 소스를 메모리에 유지합니다.
  TTL이 있는 소스는 만료 뒤 첫 전체 리빌드에서 다시 시도합니다. 갱신이
  실패하면 편집을 오프라인에서도 계속할 수 있게 이전 페이로드를 유지합니다.
- 페이로드가 바뀌면 로컬 `data/` 파일을 고친 것처럼 캐시된 페이지를 무효화합니다.

각 소스는 연결에 10초, 읽기마다 30초, 리다이렉트와 응답 본문 전체에는 총
120초가 주어집니다. 타임아웃도 선택한 `on_error` 정책을 따릅니다.

## 범위와 충돌

원격 소스는 의도적으로 설정에서만 선언합니다. `load_data()`와 숏코드는 URL을
가져올 수 없습니다. 페이지네이션, POST 요청, 인증 흐름, 여러 응답의 변형이
필요하면 [빌드 전 훅](/ko/features/build-hooks/#api에서-데이터-가져오기)으로
`data/` 아래에 로컬 파일을 쓰세요.

원격 키는 로컬 데이터 파일과 이름을 공유할 수 없습니다. 예를 들어
`data/team.json`과 `key = "team"`은 설정 오류이며, Hwaro는 조용히 하나를 고르는
대신 두 소스를 모두 알려 줍니다.

원격 배열을 페이지로 만들려면 [콘텐츠 생성](/ko/features/content-generation/)과
함께 사용하세요. 생성된 페이지는 작성한 콘텐츠와 똑같이 목록, 택소노미, 피드,
검색, 사이트맵, 출력 포맷에 포함됩니다.

## 함께 보기

- [데이터 모델](/ko/templates/data-model/#데이터-파일) — 로컬 `data/` 파일과 템플릿 접근
- [콘텐츠 생성](/ko/features/content-generation/) — 데이터 레코드를 페이지로 만들기
- [빌드 훅](/ko/features/build-hooks/) — 여러 단계 또는 GET 이외의 연동

---

Title: Sass/SCSS
URL: https://hwaro.hahwul.com/ko/features/sass/
Source: content/features/sass.ko.md
Language: ko

Hwaro는 빌드 시점에 순수 Crystal로 구현된 내장 컴파일러로 SCSS를 컴파일합니다. dart-sass 바이너리 설치도, npm 툴체인도, C 라이브러리도 필요 없습니다. 외부 의존성 없음이라는 Hwaro의 철학 그대로입니다.

## 빠른 시작

```toml
[sass]
enabled = true
```

SCSS 파일을 `static/` 아래에 둡니다.

```
static/
├── css/
│   ├── _variables.scss   # partial — never published
│   ├── _mixins.scss      # partial — never published
│   └── style.scss        # entry — compiles to /css/style.css
```

```scss
// static/css/style.scss
@use "variables";
@use "mixins";

.card {
  color: variables.$primary;
  &:hover { color: variables.$accent; }

  @include mixins.respond(768px) {
    padding: 2rem;
  }
}
```

파셜이 아닌 모든 `*.scss`는 출력에서 같은 경로의 `.css`로 컴파일되므로(`static/css/style.scss` → `/css/style.css`), 스타일시트 URL이 안정적으로 유지됩니다.

```html
<link rel="stylesheet" href="{{ url_for(path="/css/style.css") }}">
```

## 규칙

- **엔트리** — 이름이 `_`로 시작하지 않는 `*.scss` 파일은 출력의 같은 상대 경로에 `.css`로 컴파일됩니다.
- **파셜** — `_*.scss` 파일은 단독으로 컴파일되지 않고 게시되지도 않습니다. `@use`/`@import`로만 접근할 수 있습니다.
- **원본 소스는 게시되지 않음** — `[sass]`가 활성화된 동안 `.scss` 파일은 정적 파일 그대로 복사되는 대상에서 제외됩니다.
- **번들** — `[[assets.bundles]]`의 `files` 항목에 `.scss` 파일을 지정할 수 있습니다. `[sass]`가 활성화된 동안에는 이어 붙이기 전에 컴파일된 뒤 일반적인 압축(minify) → 핑거프린트 파이프라인을 거칩니다. `[sass]`가 비활성화되면 번들 항목은 그대로 이어 붙입니다(미리 컴파일했거나 지원 범위를 벗어난 소스를 위한 탈출구).
- **감시** — `hwaro serve`는 `.scss` 변경 시 다시 컴파일합니다. 파셜을 수정하면 모든 엔트리를 다시 컴파일합니다(의존성 그래프가 없습니다. 정적 사이트 규모에서는 전체 재컴파일도 충분히 빠릅니다). 컴파일 오류는 브라우저 오류 오버레이에 표시됩니다.

## 설정

| 옵션 | 타입 | 기본값 | 설명 |
|--------|------|---------|-------------|
| `enabled` | bool | `false` | SCSS 컴파일 활성화 |
| `minify` | bool | `true` | 컴파일된 CSS 압축(에셋 파이프라인과 같은 압축기 사용) |

## 지원 범위

Hwaro는 실용적인 SCSS 부분집합을 구현합니다. 직접 작성하는 사이트 스타일시트에서 실제로 쓰이는 기능들입니다.

| 기능 | 지원 |
|---------|---------|
| `$variables` | ✅ `!default` / `!global`, 렉시컬 스코프와 섀도잉 지원 |
| 중첩 규칙 | ✅ 셀렉터 목록 포함(카테시안 조합) |
| `&` 부모 셀렉터 | ✅ `&:hover`, `&.mod`, BEM `&__elem` / `&--mod` |
| `#{...}` 보간 | ✅ 셀렉터, 속성 이름, 값, at-규칙 서두, 문자열, `url()`. 내부에서 전체 표현식 평가. 문자열은 리스트 안까지 모든 중첩 수준에서 따옴표를 벗겨 출력합니다(`#{("a", "b")}` → `a, b`) |
| 파셜 + `@use` | ✅ 네임스페이스(`colors.$primary`), `as x`, `as *`, 1회 로드, `with (...)` 설정 |
| `@forward` | ✅ `show` / `hide` 필터, `as prefix-*` |
| `@import`(Sass 파일) | ✅ 클래식 전역 병합 시맨틱. `@forward`만 하는 파셜(`@import "components"` → `components/_index.scss`)도 포함하며, 순수 CSS 형태는 그대로 통과 |
| `@mixin` / `@include` | ✅ 기본값, 키워드 인자, 가변 인자 `$args...`(남는 키워드는 `meta.keywords()`로 전달), 스프레드(키워드는 `$args...`를 통해 그대로 전달), 인자를 받는 `@content` 블록(`@content(1px)` / `@include m using ($a)`) |
| `@function` / `@return` | ✅ 값 안에서 호출 가능한 사용자 함수, 기본값/키워드/가변 인자, 재귀 |
| `@extend` + `%placeholders` | ✅ 단순 셀렉터 타깃, 컴파운드 통합, `!optional`. 확장되지 않은 플레이스홀더는 출력되지 않음(차이점 참고) |
| SassScript의 `&` | ✅ `if(&, "&", "")` 패턴. 부모 셀렉터를 값으로, 루트에서는 `null` |
| 제어 흐름 | ✅ `@if` / `@else if` / `@else`, `@each`(구조 분해 포함), `@for`(`through`/`to`, 내림차순), `@while` |
| SassScript 표현식 | ✅ 산술(`+ - * / %`, 클래식 슬래시 나눗셈 규칙), 비교, `and`/`or`/`not`, 문자열, 리스트, 맵(`/`는 차이점 참고) |
| 단위 변환 | ✅ `px`/`cm`/`mm`/`q`/`in`/`pt`/`pc`, `deg`/`grad`/`rad`/`turn`, `s`/`ms`, `Hz`/`kHz`, `dpi`/`dpcm`/`dppx`가 산술·비교·`==`·`math.*`에서 변환됨 |
| 중첩 속성 | ✅ `font: 12px serif { family: sans; }` → `font`, `font-family` (재귀 적용) |
| 내장 함수 | ✅ `sass:math`(`log` / `hypot` / 삼각함수 포함), `sass:string`(`insert` / `split` 포함), `sass:list`(`zip` / `set-nth` / `slash` / `is-bracketed` 포함), `sass:map`(`set` / `deep-merge` / `deep-remove` 포함), `sass:meta`(`keywords` / `variable-exists` / `function-exists` / `mixin-exists` / `content-exists` / `get-function` / `call` 포함), `sass:selector`(문자열 수준의 `parse` / `nest` / `append` / `unify` / `replace` / `is-superselector` / `simple-selectors` — `replace`는 `@extend` 부분집합과 같은 제약을 공유합니다: `$original`은 컴파운드만, 의사 클래스 재귀 없음, 첫 번째 접두 순서만), `sass:color` 부분집합(`channel` / `hwb` / `ie-hex-str` 포함) + 레거시 전역 이름(`map-get`, `nth`, `darken`, `if()` 등) |
| 모듈 상수 | ✅ `math.$pi`, `math.$e`, `math.$epsilon`, `math.$max-safe-integer`, `math.$min-safe-integer`, `math.$max-number`, `math.$min-number` |
| `@debug` / `@warn` / `@error` | ✅ `@error`는 위치 정보가 담긴 메시지로 빌드를 실패시킴 |
| `@at-root` | ✅ 셀렉터 형태와 블록 형태, `#{&}` 접미, `(with: ...)` / `(without: ...)` 쿼리 |
| 규칙 안의 `@media` / `@supports` | ✅ 중첩 밖으로 자동 버블링, 중첩된 `@media`는 `and`로 병합(쉼표 목록은 교차 조합), 피처 값에서 표현식 평가 |
| `@keyframes`, `@font-face`, 커스텀 속성 | ✅ 올바르게 통과 |
| 순수 CSS | ✅ 유효한 `.css`는 그대로 컴파일(공백 정규화) |

알 수 없는 함수(`var()`, `clamp()`, `color-mix()` 등)는 손대지 않고 그대로 통과합니다. 인자는 평가되고(`translate($x * 2, -50%)` 동작), 정적인 `calc()`는 하나의 숫자로 접히며(차이점 참고), 토큰 전체를 이루는 `url($v)` / `url(ns.$img)`는 변수가 치환됩니다(`$`는 원시 URL에 쓸 수 없는 문자입니다). 더 큰 url 토큰 안에 `$`가 박혀 있는 형태(`url(plain$x.png)`)는 유효한 순수 CSS이므로 바이트 단위로 그대로 통과합니다. dart-sass는 여기서 오류를 내고, 반대로 `url($a + $b)`처럼 표현식이 들어간 내용은 dart-sass가 평가하지만 Hwaro는 원문 그대로 둡니다.

```scss
@use "sass:math";
$breakpoints: (sm: 640px, md: 768px, lg: 1024px);

@function rem($px, $base: 16px) { @return math.div($px, $base) * 1rem; }

@mixin respond($name) {
  @if not map-has-key($breakpoints, $name) { @error "unknown breakpoint #{$name}"; }
  @media (min-width: map-get($breakpoints, $name)) { @content; }
}

@each $name, $bp in $breakpoints {
  .container-#{$name} { max-width: $bp - 24px; }
}
@for $i from 1 through 12 {
  .col-#{$i} { width: math.percentage(math.div($i, 12)); }
}
.hero {
  font-size: rem(28px);
  @include respond(md) { font-size: rem(40px); }
}
```

### 색상

색상 함수는 hex 리터럴(`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`), CSS 색상 키워드(`red`, `rebeccapurple`, `transparent`), 그리고 레거시 콤마 철자 `rgb(…)` / `rgba(…)` / `hsl(…)` / `hsla(…)`에 동작합니다. `hsl()`로 만든 색상은 선언된 색조/채도를 기억하므로 `hue(hsl(221, 14%, 100%))`는 `221deg`를 답합니다.

```scss
$brand: #336699;

.button {
  background: $brand;
  border-color: darken($brand, 10%);      // #264d73
  color: scale-color($brand, $lightness: 60%);
  box-shadow: 0 1px 2px rgba($brand, 0.4); // rgba(51, 102, 153, 0.4)
}
```

| 분류 | 함수 |
|------|------|
| 명도 | `darken`, `lighten` |
| 채도 | `saturate`, `desaturate`, `grayscale` |
| 색상(Hue) | `adjust-hue`, `complement` |
| 혼합 | `mix`, `invert` |
| 알파 | `rgba($color, $alpha)`, `opacify` / `fade-in`, `transparentize` / `fade-out` |
| 복합 | `adjust-color`, `scale-color`, `change-color` |
| 성분 조회 | `red`, `green`, `blue`, `hue`, `saturation`, `lightness`, `alpha` / `opacity`, `color.channel` |
| 기타 | `ie-hex-str`, `color.hwb`(`color.hwb($h $w $b)`와 `color.hwb($h, $w, $b)` 모두) |

같은 함수들을 `sass:color` 모듈의 최신 이름으로도 쓸 수 있습니다. `color.adjust`, `color.scale`, `color.change`, `color.mix`, `color.complement`, `color.grayscale`, `color.invert`, 그리고 성분 조회 함수들입니다.

```scss
@use "sass:color";
.a { border-color: color.scale(#336699, $lightness: -20%); }
```

계산된 색상은 불투명하면 `#rrggbb`로, 그렇지 않으면 `rgba(r, g, b, a)`로 직렬화됩니다. *수정하지 않은* 색상은 작성한 철자를 그대로 유지하므로 `#FFF`는 `#FFF`로 남습니다.

색상은 표기가 달라도 채널 값으로 비교됩니다. `#ffffff == #FFF`, `red == #f00`, `rgb(255, 0, 0) == #ff0000`은 모두 true입니다(dart-sass 시맨틱).

### @extend

`@extend`는 단순 셀렉터 타깃(클래스, `%placeholder`, id, 요소, 의사 클래스)에 동작합니다. Bootstrap을 포함한 실제 스타일시트의 사용 방식을 전부 커버합니다. 타깃이 속한 컴파운드는 확장자의 마지막 컴파운드와 통합되고, 조상 컴파운드는 앞에 붙으며, 확장되지 않은 `%placeholder` 규칙은 출력에 등장하지 않습니다.

```scss
%visually-hidden { position: absolute; clip: rect(0 0 0 0); }
.sr-only { @extend %visually-hidden; }
// → .sr-only { position: absolute; clip: rect(0 0 0 0); }
```

타깃을 찾지 못하면 위치 정보가 담긴 오류로 빌드가 실패합니다. `!optional`을 붙이면 허용됩니다. dart-sass의 전체 extend 알고리즘과의 차이는 아래 차이점 목록을 참고하세요.

### 미지원 (아직)

복합 단위(`px*em`, `px/s`처럼 분자·분모 단위 목록이 필요한 곱셈·나눗셈), `@forward ... with (...)`, `math.random` / `unique-id()`(빌드는 결정적이어야 합니다), 들여쓰기 방식의 `.sass` 문법, 소스맵은 지원하지 않습니다.

**미지원 지시문은 위치 정보가 담긴 오류와 함께 빌드를 실패시킵니다** — Hwaro는 조용히 깨진 CSS를 내보내지 않습니다.

```
Error [HWARO_E_CONTENT]: Sass: static/css/style.scss:14:3: @forward ... with (...) is not supported
```

### 표현식 시맨틱

이 컴파일러의 첫 번째 의무는 순수 CSS 보장이므로, 표현식은 두 단계 정책을 따릅니다.

- **값 컨텍스트는 관대(lenient)합니다.** 선언이나 변수 값은 눈에 보이게 무언가를 계산할 때(숫자 사이의 연산자, 알려진 함수 호출)만 평가됩니다. 그 외의 값, 그리고 평가에 *실패*하는 값(단위가 안 맞는 `$a + 2em`, `min(100% - 10px, 20rem)`)은 이전과 똑같이 원문 텍스트를 유지합니다. 기존 스타일시트는 바이트 단위로 동일하게 컴파일됩니다.
- **새 구문은 엄격(strict)합니다.** `@if`/`@while` 조건, `@each`/`@for` 헤더, `@return`, `@use ... with`는 모든 실패를 위치 정보가 담긴 빌드 오류로 보고합니다.

### dart-sass와의 차이

- `/`는 클래식 Sass 나눗셈 규칙(dart-sass 1.x)을 따릅니다. 피연산자가 변수이거나 알려진 함수 호출이거나 괄호로 감싸여 있을 때, 또는 슬래시가 계산 문맥(인접한 산술, Sass 함수 인자, 변수 선언, 보간, 제어 흐름)에 놓일 때 나눗셈이 됩니다. 리터럴끼리의 슬래시(`font: 12px/1.5`, `grid-area: 1 / 2`)는 **작성자가 쓴 공백 그대로** 유지됩니다. dart-sass는 이를 붙여서(`1/2`) 다시 출력합니다.
- 값은 평가 사이에 CSS 텍스트로 저장되고 사용 시점에 타입이 다시 유도됩니다. 리스트처럼 *보이는* 따옴표 없는 문자열(`"a, b"`를 unquote한 값)은 리스트로 취급됩니다.
- 단위 산술은 표준 그룹(길이, 각도, 시간, 주파수, 해상도) 안에서 변환되며, 왼쪽 피연산자의 단위가 결과 단위가 됩니다. 복합 단위(`1px * 1em`, `math.div(1px, 1s)`)는 모델링하지 않고 원문 텍스트로 남습니다.
- *값* 위치의 `and`/`or`는 실제 불리언에만 동작하므로 `font-family: Franklin and Marshall`은 텍스트로 남습니다. 조건식에서는 Sass의 완전한 truthiness를 따릅니다.
- 전역 `min()`/`max()`/`round()`/`abs()`는 모든 인자가 정적으로 비교 가능한 숫자일 때만 평가됩니다. CSS 형태(`min(5vw, 100px)`, `round(up, 101px, 10px)`)는 그대로 통과합니다.
- `rgb()`/`rgba()`/`hsl()`/`hsla()`는 CSS 형태 그대로 두고 접지 **않습니다**. dart-sass는 `rgb(0, 0, 0)`을 `black`으로 내보내지만 여기서는 원문이 유지됩니다(색상 *함수*가 그런 리터럴을 받으면 색상으로 읽기는 합니다). 유효한 CSS가 아닌 Sass 전용 `rgba($color, $alpha)` 철자만 평가됩니다. 마찬가지로 `grayscale()`, `invert()`, `saturate()`, `opacity()`는 색상을 받으면 색상 함수, 숫자를 받으면 순수 CSS 필터로 취급됩니다(`filter: grayscale(50%)`는 그대로 통과).
- 계산된 색상은 정수 채널로 직렬화됩니다. 반올림한 채널이 CSS 키워드와 정확히 일치하면 키워드로(`mix(red, blue)` → `purple`, 별칭은 dart의 표기를 따라 `aqua`, `gray`, `fuchsia`), 그렇지 않으면 hex/`rgba()`로 출력합니다. dart-sass 1.79+는 대신 소수 채널을 유지하므로(거기서 `mix(red, blue)`는 `rgb(50%, 0%, 50%)`) 키워드 형태는 계산 결과가 정확한 정수로 떨어질 때만 dart와 일치하며, 어느 쪽이든 채널당 최대 1 차이입니다.
- 내장 함수는 문서화된 키워드 이름을 받습니다(`list.append($l, x, $separator: comma)`, `string.slice($string: …, $start-at: 2)`, `darken($c, $amount: 10%)`, `map.get($map: …, $key: …)`). 가변 인자 내장 함수(`math.min`, `list.zip`, `map.set`, `selector.nest`)는 위치 인자만 받습니다. 사용자 정의 `@mixin`/`@function`의 키워드 인자는 정상 동작합니다.
- `@extend`는 dart-sass 알고리즘의 실용적 부분집합입니다: 타깃은 단순 셀렉터여야 하고, 확장은 문서 전역에 적용되며(dart-sass는 모듈 단위로 스코프를 나누고 `@media` 경계를 넘는 확장을 금지), 확장 대상과 확장자 양쪽에 조상 컴파운드가 있으면 첫 번째 접두 순서만 출력합니다(dart-sass는 두 순서를 모두 "위빙"). 공유하는 선행 접두는 병합됩니다(`.nav %p`를 `.nav > .c`로 확장 → `.nav > .c`).
- 내용 전체가 하나의 정적 숫자로 접히는 `calc()`는 dart-sass와 같은 방식으로 단순화됩니다. `calc(10px + 5px * 2)` → `20px`, `calc(9 / 21 * 100%)` → `42.8571428571%`이며 중첩된 `calc`/`min`/`max`/`clamp`도 포함합니다(`clamp`는 경계값에서 경계가 이기고, 단위 표기도 유지됩니다). 완전히 접히지 않는 것은 원문 텍스트를 유지합니다: `calc(100% - 20px)`, `var()`, 보간이 들어간 `calc(#{…})`, 단위 없는 값과 단위 있는 값의 덧셈이나 clamp, 앞뒤 공백이 없는 `+`/`-`(dart-sass가 오류를 내는 잘못된 CSS), NaN이 나오는 나눗셈이 그렇습니다. `@supports (width: calc(…))`는 절대 접지 않습니다. 이 쿼리는 calc 지원 여부 자체를 검사하기 때문입니다. 리터럴 `calc()` 뒤의 슬래시(`font: calc(16px)/1.5`)는 다른 리터럴 슬래시와 마찬가지로 그대로 유지됩니다.
- at-규칙 서두와 값 안의 변수는 직접 치환됩니다(`@media (min-width: $bp)` 동작). 셀렉터와 속성 이름에는 `#{...}` 보간이 필요합니다(dart-sass와 동일).
- at-규칙 서두에서는 `(feature: value)` 구간 안에서만 표현식이 평가됩니다. 쿼리 구조 자체는 원문 그대로 유지됩니다.
- `@media` 안에 중첩된 `@media`는 조건이 `and`로 병합됩니다(쉼표 목록은 바깥쪽을 우선으로 교차 조합하고, 타입이 충돌하는 쌍은 버립니다). 병합으로 표현할 수 없는 쿼리(`not …`)나 중간에 다른 at-규칙(`@supports`)이 끼어든 중첩은 문자 그대로 중첩된 형태를 유지합니다. 유효한 최신 CSS이며, dart-sass는 이런 경우를 버리거나 다시 씁니다.
- `&` 치환은 텍스트 기반이라 `&__elem`은 결합 셀렉터를 검증하지 않고 이어 붙입니다.
- 커스텀 속성 값은 그대로 유지됩니다: `$var`는 리터럴로 남고 `#{...}`만 보간됩니다(dart-sass 시맨틱). 다만 앞뒤 공백은 잘라냅니다.
- 같은 파일을 여러 번 `@import`하면 그때마다 CSS를 다시 내보냅니다(클래식 Sass 동작). `@use`는 한 번만 로드합니다.
- 자체적으로 `@forward`를 사용하는 모듈을 설정(`@use "lib" with (...)`)하는 것은 조용히 무시되는 대신 오류입니다.
- 출력에 비ASCII 내용이 있으면 맨 앞에 `@charset "UTF-8";`가 한 번 붙습니다. 소스에 쓴 `@charset` 선언은 제거됩니다(dart-sass 동작).
- 값은 텍스트로 치환됩니다: 짝이 맞지 않는 따옴표 문자가 들어 있는 변수를 보간하면 이후의 공백/따옴표 처리가 꼬일 수 있습니다. 따옴표 문자는 따옴표로 감싼 문자열 안에만 둡니다.
- 소문자 `.scss` 확장자만 Sass 소스로 취급합니다. 다른 대소문자 조합은 일반 정적 파일처럼 그대로 게시됩니다.

## 오류

컴파일 실패는 콘텐츠 오류로 분류되며(종료 코드 5), `path:line:column` 위치 정보가 함께 표시됩니다.

```
Error [HWARO_E_CONTENT]: Sass: static/css/_mixins.scss:7:12: undefined variable: "$primry"
```

`hwaro serve` 중에는 오류가 브라우저 오버레이에 표시되고, 이전 출력은 디스크에 그대로 남습니다.

## 다른 기능과의 상호작용

- **에셋 파이프라인** — 단독으로 컴파일된 엔트리는 안정적인(핑거프린트 없는) URL을 유지하고 `asset()`의 패스스루로 해석됩니다. 핑거프린트가 필요하면 번들에서 `.scss` 파일을 참조합니다.
- **빌드 훅** — Tailwind/PostCSS나 완전한 dart-sass 프로젝트는 여전히 `[build] hooks.pre`로 실행하고, 컴파일된 출력을 Hwaro가 사용하게 하면 됩니다.
- **캐시** — Sass는 전체 빌드마다 다시 컴파일됩니다(증분 페이지 캐시에 참여하지 않습니다). 엔트리 `.scss`를 삭제하면 이전에 컴파일된 `.css`가 오래된 출력 디렉터리에 남습니다. 클린 빌드는 이를 제거합니다.

---

Title: 검색
URL: https://hwaro.hahwul.com/ko/features/search/
Source: content/features/search.ko.md
Language: ko

Hwaro는 Fuse.js와 함께 사용할 수 있는 클라이언트 사이드 검색 인덱스를 생성합니다.

## 설정

`config.toml`에서 활성화합니다.

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | 검색 인덱스 생성 여부 |
| format | string | "fuse_json" | 검색 인덱스 포맷 |
| fields | array | ["title", "content"] | 인덱스에 포함할 필드 — 기본값은 `title`과 `content`뿐 (`url`은 항상 추가) |
| filename | string | "search.json" | 출력 파일 이름 |
| exclude | array | [] | 검색 인덱스에서 제외할 경로(접두사) |
| tokenize_cjk | bool | false | CJK 바이그램 토큰화 활성화 |
| shards | string | "none" | 인덱스를 지연 로드 가능한 샤드로 분할: `"section"`, `"language"`, `"section-language"` — [샤드 인덱스](#샤드-인덱스) 참고 |
| single_file | bool | true | `shards` 사용 시 기존 `search.json`도 함께 생성; `false`면 샤드만 생성 |
| content_max_length | int | 0 | 0보다 크면 각 항목의 `content`를 단어 경계에서 해당 글자 수로 자름; `0`이면 전체 본문 유지 |

## 생성 파일

활성화하면 Hwaro가 `/search.json`을 생성합니다(`filename`으로 변경 가능).

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

## 인덱싱되는 필드

`fields`에 나열한 필드만 출력됩니다(`url`은 항상 포함).

| 필드 | 설명 |
|-------|-------------|
| title | 페이지 제목 |
| url | 페이지 URL |
| content | 페이지 본문(`fields`에 `"content"`가 있을 때) |
| description | 페이지 설명 |
| section | 섹션 이름 |
| tags | 페이지 태그 |

## 클라이언트 사이드 구현

### Fuse.js 사용

템플릿에 추가합니다.

```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>
```

### 검색 폼

```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 검색 지원

중국어·일본어·한국어 콘텐츠가 있는 사이트라면 CJK 토큰화를 켜서 검색 정확도를 높일 수 있습니다. CJK 언어는 단어 사이에 공백이 없는 경우가 많아 검색 라이브러리가 텍스트를 제대로 토큰화하기 어렵습니다.

이 옵션을 켜면 연속된 CJK 문자를 겹치는 바이그램(2글자 쌍)으로 분할하므로, 긴 텍스트 안에서도 검색어가 매칭됩니다.

**예:** `"검색엔진"` → `"검색 색엔 엔진"` (이제 검색어 `"검색"`이 매칭됨)

### 설정

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| tokenize_cjk | bool | false | 검색 인덱스에 CJK 바이그램 토큰화 적용 |

### 동작 방식

- `title`, `content`, `description` 필드만 토큰화됩니다
- `url`, `tags`, `section` 필드는 구조용 필드이므로 그대로 둡니다
- CJK가 아닌 텍스트는 변경 없이 통과합니다
- Fuse.js와 ElasticLunr 포맷 모두에서 동작합니다

### 참고

- 이 옵션을 켜면 검색 인덱스 크기가 약간 커집니다
- 바이그램 방식은 대부분의 CJK 검색 시나리오에서 잘 동작합니다
- 자연스러운 공백이 있는 한국어 텍스트(예: `"검색 엔진"`)도 올바르게 처리됩니다

## 페이지 제외

### 프론트 매터

프론트 매터로 개별 페이지를 검색에서 제외합니다.

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

### 설정

`config.toml`로 섹션이나 경로 전체를 제외합니다.

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

### 필드 선택

`fields`를 지정해 검색 인덱스에 들어갈 필드를 제어합니다.

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

사용 가능한 필드: `title`, `content`, `description`, `tags`, `url`, `section`.

`fields`에서 `content`를 빼면 대규모 사이트에서 인덱스 파일 크기가 크게 줄어듭니다.

## 성능 팁

### 대규모 사이트

페이지가 많은 사이트라면:

1. `fields`에서 `"content"`를 제거해 인덱스 크기를 줄입니다
2. Fuse.js의 `ignoreLocation` 옵션을 사용합니다
3. 디바운스 검색을 구현합니다

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

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

### 지연 로딩

검색창에 포커스가 왔을 때만 인덱스를 불러옵니다.

```javascript
let indexLoaded = false;

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

## 샤드 인덱스

`search.json` 하나는 사이트가 커질수록 함께 커지고, 방문자는 첫 검색 전에 파일 전체를 내려받아야 합니다. 샤딩은 인덱스를 여러 JSON 파일과 매니페스트로 나누어, 클라이언트가 필요한 것만(현재 섹션 먼저, 또는 언어별로) 불러올 수 있게 합니다.

```toml
[search]
enabled = true
shards = "section"          # "section" | "language" | "section-language"
single_file = false         # 샤드만 생성 (기본값 true는 search.json도 유지)
content_max_length = 500    # 선택: 각 항목의 content 길이 제한
```

| 모드 | 샤드 | id 예시 |
|------|------|---------|
| `"section"` | 최상위 콘텐츠 섹션마다 하나; 섹션 밖의 페이지는 `_root` | `blog`, `docs`, `_root` |
| `"language"` | 언어마다 하나(다국어 사이트); 기본 언어는 자신의 코드 사용 | `en`, `ko` |
| `"section-language"` | 언어, 그다음 섹션 | `en/blog`, `ko/blog`, `ko/_root` |

중첩 섹션은 최상위 섹션으로 합쳐집니다. `blog/news/post.md`는 `blog` 샤드에 들어갑니다. 기존 인덱스의 포함 규칙(`fields`, `exclude`, `in_search_index = false`, 초안, `render = false`, 언어별 `build_search_index`, `tokenize_cjk`)은 그대로 적용됩니다.

### 생성 파일

```
public/
├── search.json          # single_file = false가 아니면 생성
└── search/
    ├── index.json       # 매니페스트
    ├── _root.json
    ├── blog.json
    └── docs.json        # 중첩 id는 디렉터리 사용: search/ko/blog.json
```

각 샤드는 `search.json`과 완전히 동일한 항목 스키마를 가진 JSON 배열입니다(`format` 설정과 무관하게 샤드는 항상 JSON입니다. `*_javascript` 래퍼는 `<script src>` 로딩 전용입니다). `search/index.json`은 전체 구조를 설명합니다.

```json
{
  "version": 1,
  "fields": ["title", "content", "url", "lang"],
  "shards": [
    {"id": "_root", "url": "/search/_root.json", "language": null, "section": "", "count": 2, "bytes": 200},
    {"id": "blog",  "url": "/search/blog.json",  "language": null, "section": "blog", "count": 42, "bytes": 12345}
  ]
}
```

- `url`은 `base_url`의 하위 경로를 반영하고(`https://example.com/docs` 배포라면 `/docs/search/blog.json`), 섹션 이름은 퍼센트 인코딩됩니다.
- `language`는 `language`·`section-language` 모드에서, `section`은 `section`·`section-language` 모드에서 채워지고 나머지는 `null`입니다.
- 샤드는 id 순으로 나열되며 타임스탬프가 없어 출력이 결정적이고 diff하기 좋습니다. 마지막 페이지가 사라진 샤드는 다음 빌드에서 삭제됩니다.
- `--cache` 빌드와 `hwaro serve`도 `search.json`과 같은 페이지 집합에서 샤드를 다시 생성합니다.

### Fuse.js로 샤드 지연 로드

매니페스트를 한 번 받은 뒤 필요할 때 샤드를 불러옵니다. 전역 검색창은 모든 샤드를, 섹션 인식 검색창은 현재 섹션 샤드를 먼저 받고 나머지는 백그라운드에서 받습니다.

```html
<script src="https://cdn.jsdelivr.net/npm/fuse.js@7.0.0"></script>
<script>
const loaded = new Map();       // 샤드 id → 항목 배열
let manifest = null;
let fuse = null;

async function loadManifest() {
  if (manifest) return manifest;
  manifest = await (await fetch('/search/index.json')).json();
  return manifest;
}

async function loadShard(shard) {
  if (loaded.has(shard.id)) return;
  loaded.set(shard.id, await (await fetch(shard.url)).json());
  fuse = new Fuse([...loaded.values()].flat(), {
    keys: ['title', 'content', 'description', 'tags'],
    threshold: 0.3,
    ignoreLocation: true
  });
}

// 이 페이지에 필요한 샤드는? 문서 언어와 URL 첫 세그먼트로
// 매니페스트를 거르고, 해당 없으면 전체를 불러옵니다.
async function loadRelevantShards() {
  const { shards } = await loadManifest();
  const lang = (document.documentElement.lang || '').split('-')[0];
  const section = location.pathname.split('/').filter(Boolean)[0] || '';
  const local = shards.filter(s =>
    (s.language === null || s.language === lang) &&
    (s.section === null || s.section === section));
  await Promise.all((local.length ? local : shards).map(loadShard));
  // 첫 결과를 막지 않고 나머지 샤드를 미리 받아 둡니다.
  shards.filter(s => !loaded.has(s.id)).forEach(s => loadShard(s));
}

function search(query) {
  return fuse ? fuse.search(query) : [];
}

document.getElementById('search-input').addEventListener('focus', loadRelevantShards, { once: true });
</script>
```

전역 검색만 필요하면 `loadRelevantShards` 대신 `shards.map(loadShard)`를 사용하세요. 로드 이후는 위의 단일 파일 예제와 같은 Fuse.js 코드입니다.

## 대안: Pagefind

더 큰 사이트라면 [Pagefind](https://pagefind.app/)를 고려해 볼 만합니다.

```bash
# 빌드 후 실행
npx pagefind --site public
```

빌드 후 훅으로 설정에 추가합니다.

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

## 함께 보기

- [설정](/ko/start/config/) — 검색 설정 레퍼런스
- [다국어](/ko/features/multilingual/) — CJK 토큰화와 i18n 검색

---

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

Hwaro는 사이트맵, RSS 피드, robots.txt, 소셜 공유 메타 태그 같은 SEO 기능을 기본으로 제공합니다.

## 사이트맵

검색 엔진용 `sitemap.xml`을 자동 생성합니다.

### 설정

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | `sitemap.xml` 생성 여부 |
| filename | string | "sitemap.xml" | 출력 파일 이름 |
| changefreq | string | "weekly" | 전체 페이지의 기본 변경 주기 |
| priority | float | 0.5 | 전체 페이지의 기본 우선순위(0.0–1.0) |
| exclude | array | [] | 제외할 경로 접두사 (예: `["/private"]`는 `/private`, `/private/page.html`을 제외) |

### 출력

```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>
```

### 페이지 제외

프론트 매터에 `in_sitemap = false`를 설정합니다:

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

---

## RSS 피드

사이트와 섹션의 RSS 피드를 생성합니다.

### 설정

```toml
[feeds]
enabled = true
type = "rss"              # "rss" 또는 "atom"
limit = 20                # 최대 항목 수
truncate = 0              # N자로 자르기 (0 = 자르지 않음)
full_content = true       # true = 전체 HTML 본문, false = description/요약만
filename = ""             # 비워 두면 기본값 (rss.xml 또는 atom.xml)
sections = []             # 특정 섹션으로 제한, 예: ["posts"]
```

| 옵션 | 기본값 | 설명 |
|--------|---------|-------------|
| `enabled` | `false` | 피드 생성 여부 |
| `type` | `"rss"` | 피드 형식: `"rss"` 또는 `"atom"` |
| `limit` | `10` | 피드의 최대 항목 수 |
| `truncate` | `0` | 콘텐츠를 N자로 자르기 (0 = 전체 콘텐츠) |
| `full_content` | `true` | `true` = 피드에 전체 HTML 포함, `false` = 프론트 매터 `description` 또는 자동 생성 요약 사용 |
| `filename` | `""` | 커스텀 파일 이름 (비어 있으면 `rss.xml` 또는 `atom.xml`) |
| `sections` | `[]` | 피드를 특정 섹션으로 제한 |
| `default_language_only` | `true` | 다국어: 메인 피드에 기본 언어만 포함 |

### 섹션 피드

섹션별 피드를 활성화합니다:

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

이렇게 하면 `/blog/rss.xml`이 생성됩니다.

### 출력

- `/rss.xml` — 사이트 전체 피드
- `/blog/rss.xml` — 섹션 피드 (활성화한 경우)

### 다국어 피드

사이트가 다국어이면 피드는 언어별로 자동 생성됩니다:

| 언어 | 피드 경로 | 내용 |
|----------|-----------|----------|
| 기본 언어 (예: `en`) | `/rss.xml` | 기본 언어 페이지만 (설정 가능) |
| 기본 외 언어 (예: `ko`) | `/ko/rss.xml` | 한국어 페이지만 |
| 기본 외 언어 (예: `ja`) | `/ja/rss.xml` | 일본어 페이지만 |

기본적으로 메인 사이트 피드에는 **기본 언어 페이지만** 포함됩니다(`default_language_only = true`). 메인 피드에 모든 언어를 포함하려면 `default_language_only = false`로 설정합니다. `generate_feed = true`인 기본 외 언어는 이 설정과 무관하게 각자 별도 피드를 갖습니다.

```toml
[feeds]
enabled = true
default_language_only = true   # true (기본값): 메인 피드 = 기본 언어만
                               # false: 메인 피드에 모든 언어 포함
```

언어별 피드 제어:

```toml
[languages.ko]
language_name = "한국어"
generate_feed = true    # /ko/rss.xml 생성 (기본값: true)

[languages.ja]
language_name = "日本語"
generate_feed = false   # /ja/rss.xml을 생성하지 않음
```

언어 피드는 `[feeds]` 설정의 `sections`, `limit`, `truncate`, `full_content` 값을 그대로 공유합니다. RSS 언어 피드에는 `<language>` 태그가, Atom 피드에는 `xml:lang` 속성이 들어갑니다. 피드 제목에는 언어 이름이 포함됩니다 (예: `"My Site (한국어)"`).

### 커스텀 피드 템플릿

피드 마크업을 직접 제어하려면 피드 출력 파일 이름을 딴 템플릿을 만듭니다:

| 피드 종류 | 템플릿 파일 | 로드 키 |
|-----------|---------------|---------------|
| RSS | `templates/rss.xml.jinja` | `rss.xml` |
| Atom | `templates/atom.xml.jinja` | `atom.xml` |

템플릿 확장자는 무엇이든 됩니다(`.jinja`, `.j2`, `.jinja2`, `.html`). 마지막 확장자만 제거되므로 `rss.xml.jinja`는 `rss.xml` 키로 로드됩니다. 확장자와 무관하게 파일은 항상 **Jinja**로 렌더링됩니다(`.ecr` 파일도 인식되지만 ECR `<%= %>` 태그는 문자 그대로 출력되므로 Jinja 문법을 써야 합니다). 템플릿 파일의 존재 자체가 옵트인입니다: 파일이 없으면 Hwaro는 기존과 똑같이 내장 피드를 내보내고, 템플릿을 삭제하면 내장 출력으로 되돌아갑니다. 오버라이드는 **네 가지 피드 전부**(메인 피드, 섹션별 피드, 언어별 피드, 택소노미 항목별 피드)에 적용되고, 커스텀 `[feeds] filename`은 여전히 출력 경로를 결정합니다.

피드 템플릿 안에서 `{% include %}`를 쓸 수 있고, 템플릿이 잘못되면 해당 파일 이름을 담은 템플릿 오류와 함께 빌드가 실패합니다.

#### 컨텍스트 변수

`feed` — 렌더링 중인 피드의 메타데이터:

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| `feed.type` | string | `"rss"` 또는 `"atom"` (`[feeds] type`을 따름) |
| `feed.kind` | string | `"main"`, `"section"`, `"language"`, `"taxonomy"` 중 하나 |
| `feed.title` | string | 피드 제목 (사이트 제목, `Site - Section`, `Site (한국어)` 등) |
| `feed.description` | string | 사이트 설명 |
| `feed.url` | string | 이 피드 파일의 절대 self URL (퍼센트 인코딩) |
| `feed.home_url` | string | 피드가 대표하는 표준 HTML URL (사이트 루트, 섹션 페이지, 언어 홈) |
| `feed.base_url` | string | 끝 슬래시를 뺀 `base_url` |
| `feed.language` | string? | 언어별 피드의 언어 코드, 그 외에는 없음 |
| `feed.updated` | time | 가장 최신 항목의 날짜 (결정적; 날짜 있는 항목이 없으면 epoch) |
| `feed.updated_rfc3339` | string | `feed.updated`의 RFC 3339 표현 (Atom `<updated>`) |
| `feed.updated_rfc822` | string | `feed.updated`의 RFC 822 표현 (RSS `<lastBuildDate>`/`<pubDate>` 형식) |
| `feed.author` | string | 사이트 제목 (없으면 피드 제목으로 대체) |
| `feed.section_url` | string? | 섹션 URL — 섹션 피드 전용 |
| `feed.taxonomy` / `feed.term` | string? | 택소노미 이름과 항목 — 택소노미 피드 전용 |

`pages` — 정렬과 `limit`이 적용된 항목 목록. 각 항목:

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| `title` | string | 페이지 제목 (비어 있으면 사이트 제목) |
| `url` | string | 절대 페이지 URL (퍼센트 인코딩) |
| `date` / `updated` | time? | 프론트 매터의 원본 날짜 (`date` 필터에 사용 가능) |
| `date_rfc822` | string? | 미리 형식화된 RFC 822 날짜; 날짜 없는 페이지는 없음 |
| `updated_rfc3339` | string | `updated`/`date` 기반 RFC 3339 타임스탬프 (없으면 epoch) |
| `description` | string? | 프론트 매터 description |
| `summary` | string | 일반 텍스트 요약 (description → `<!-- more -->` 요약 → 발췌 순) |
| `content` | string | `full_content`/`truncate`를 반영한 본문 (자를 때는 일반 텍스트) |
| `content_html` | string | 외부 리더를 위해 링크를 절대 URL로 바꾼 전체 HTML 본문 |
| `content_is_html` | bool | `content`가 HTML인지 여부 (`truncate`/`full_content = false`면 `false`) |
| `authors` | array | 프론트 매터 authors |
| `categories` | array | 택소노미 항목 — `tags`가 먼저, 그다음 다른 택소노미, 중복 제거 |
| `section` | string | 페이지 섹션 경로 |
| `language` | string? | 페이지 언어 코드 |

#### 예시

값은 **미리 이스케이프되지 않습니다.** `xml_escape`를 적용하거나 CDATA로 감싸는 일은 템플릿 작성자의 몫입니다:

```jinja
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>{{ feed.title | xml_escape }}</title>
    <link>{{ feed.home_url | xml_escape }}</link>
    <description>{{ feed.description | xml_escape }}</description>
    {% if feed.language %}<language>{{ feed.language | xml_escape }}</language>{% endif %}
    <atom:link href="{{ feed.url | xml_escape }}" rel="self" type="application/rss+xml" />
    {% for p in pages %}
    <item>
      <title>{{ p.title | xml_escape }}</title>
      <link>{{ p.url | xml_escape }}</link>
      <guid>{{ p.url | xml_escape }}</guid>
      <description>{{ p.summary | xml_escape }}</description>
      {% if p.date_rfc822 %}<pubDate>{{ p.date_rfc822 }}</pubDate>{% endif %}
      {% for term in p.categories %}<category>{{ term | xml_escape }}</category>{% endfor %}
    </item>
    {% endfor %}
  </channel>
</rss>
```

### 템플릿 링크

```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

검색 엔진 크롤링을 제어합니다.

### 설정

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

커스텀 규칙 사용:

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | true | `robots.txt` 생성 여부 |
| filename | string | "robots.txt" | 출력 파일 이름 |
| rules | array | [] | `allow`/`disallow` 경로를 담은 user-agent 규칙 목록 |

규칙을 설정하지 않으면 Hwaro는 기본 전체 허용 규칙을 생성합니다. 규칙의 `allow`와 `disallow`가 모두 비어 있으면 모호한 동작을 막기 위해 명시적인 `Allow: /`가 추가됩니다.

### 출력

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

---

## LLMs.txt

[llms.txt 표준](https://llmstxt.org/)을 따르는 AI/LLM 크롤러용 안내 파일을 생성합니다.

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

전체 설정과 출력 형식은 [LLMs.txt](/ko/features/llms-txt/)에서 다룹니다.

---

## OpenGraph 태그

Facebook, LinkedIn 등을 위한 소셜 공유 메타 태그입니다.

### 설정

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

| 키 | 설명 |
|-----|-------------|
| default_image | 페이지에 이미지가 없을 때 사용할 대체 이미지 |
| type | 콘텐츠 페이지의 OpenGraph 타입 (기본값: `"article"`; 목록 페이지는 항상 `"website"`) |
| fb_app_id | Facebook 앱 ID (선택) |

### 페이지 단위 오버라이드

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

### 템플릿에서 사용

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

### 출력

```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 카드

Twitter 전용 공유 태그입니다.

### 설정

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

| 키 | 설명 |
|-----|-------------|
| twitter_card | 카드 타입: summary, summary_large_image |
| twitter_site | 사이트의 Twitter 핸들 |
| twitter_creator | 작성자의 Twitter 핸들 |

### 템플릿에서 사용

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

또는 OG와 Twitter 태그를 함께 포함합니다:

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

### 출력

```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 구조화된 데이터

Hwaro는 모든 페이지에 Article과 BreadcrumbList JSON-LD를 자동 생성합니다.

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

FAQ, HowTo, WebSite, Organization 같은 추가 스키마 타입도 사용할 수 있습니다. 전체 타입, 설정, 출력 예시는 [구조화된 데이터](/ko/features/structured-data/)에서 다룹니다.

---

## 템플릿 변수

### 미리 렌더링된 HTML

다음 변수는 바로 쓸 수 있는 HTML 태그를 출력합니다:

| 변수 | 설명 |
|----------|-------------|
| og_tags | OpenGraph 메타 태그 |
| twitter_tags | Twitter 카드 메타 태그 |
| og_all_tags | OG와 Twitter 태그 전체 |
| canonical_tag | canonical 링크 태그 |
| hreflang_tags | hreflang 대체 링크 태그 |
| jsonld | Article + BreadcrumbList JSON-LD |
| jsonld_article | Article JSON-LD만 |
| jsonld_breadcrumb | BreadcrumbList JSON-LD만 |
| page_description | 페이지 설명 (없으면 사이트 설명) |
| page_image | 페이지 이미지 (없으면 og.default_image) |

### SEO 객체

`seo` 객체는 커스텀 메타 태그를 만들 수 있도록 필드 단위 접근을 제공합니다:

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| seo.canonical_url | String | 전체 canonical URL |
| seo.og_type | String | OpenGraph 타입 (기본값: "article") |
| seo.og_image | String | 해석된 절대 이미지 URL |
| seo.twitter_card | String | Twitter 카드 타입 |
| seo.twitter_site | String | Twitter 사이트 핸들 |
| seo.twitter_creator | String | Twitter 작성자 핸들 |
| seo.fb_app_id | String | Facebook 앱 ID |
| seo.hreflang | Array | 언어 번역 링크 |

```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>
```

---

## 전체 예시

### 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>
```

## 함께 보기

- [LLMs.txt](/ko/features/llms-txt/) — AI/LLM 크롤러 안내
- [다국어](/ko/features/multilingual/) — i18n을 위한 hreflang과 canonical 태그
- [설정](/ko/start/config/) — 전체 설정 레퍼런스

---

Title: 시리즈
URL: https://hwaro.hahwul.com/ko/features/series/
Source: content/features/series.ko.md
Language: ko

관련 글을 순서 있는 시리즈로 묶어 독자가 콘텐츠를 차례대로 따라갈 수 있게 합니다.

## 설정

`config.toml`에서 활성화합니다.

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | false | 시리즈 묶기 활성화 |

## 시리즈에 글 지정

프론트 매터로 글을 시리즈에 지정합니다.

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

| 필드 | 타입 | 기본값 | 설명 |
|-------|------|---------|-------------|
| series | string | — | 이 글이 속할 시리즈 이름 |
| series_weight | int | 0 | 시리즈 내 순서(낮을수록 앞) |

시리즈 안의 글은 `series_weight`, 날짜, 제목 순으로 정렬됩니다.

## 템플릿 변수

시리즈에 속한 각 페이지는 다음 변수를 갖습니다.

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| series | string | 시리즈 이름 |
| series_index | int | 시리즈 내 위치(1부터 시작) |
| series_pages | array | 같은 시리즈의 모든 페이지(정렬됨) |

## 템플릿에서 사용

### 시리즈 내비게이션

```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 %}
```

### 이전 / 다음 링크

```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 %}
```

## 예시

글이 세 개 있다고 하면:

```
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
```

각 글의 `series_pages`에는 세 글이 순서대로 모두 담기고, `series_index`는 각각 1, 2, 3이 됩니다.

## 함께 보기

- [페이지](/ko/writing/pages/) — 시리즈용 프론트 매터 필드
- [관련 글](/ko/features/related-posts/) — 콘텐츠 추천
- [데이터 모델](/ko/templates/data-model/) — 시리즈 템플릿 변수

---

Title: 스트리밍 빌드
URL: https://hwaro.hahwul.com/ko/features/streaming-build/
Source: content/features/streaming-build.ko.md
Language: ko

스트리밍 빌드는 Render 단계에서 페이지를 배치 단위로 처리해 대규모 사이트의 메모리 사용량을 줄입니다. 렌더링된 HTML 전체를 한 번에 메모리에 들고 있는 대신, 배치 하나를 렌더링해 디스크에 쓰고 해제한 뒤 다음 배치로 넘어갑니다.

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

## 사용 시점

대부분의 사이트는 기본 빌드 모드로 충분합니다. 스트리밍 빌드는 다음 상황에서 유용합니다.

- 페이지가 수천 개인 사이트
- 빌드 과정의 메모리 사용량이 너무 큰 경우
- 메모리가 제한된 환경(CI, 컨테이너, 작은 VM)에서 빌드하는 경우

## 사용 방법

### `--stream` 플래그

기본 배치 크기 500페이지로 스트리밍을 활성화합니다.

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

### `--memory-limit` 플래그

메모리 한도를 지정하면 Hwaro가 최적의 배치 크기를 자동으로 계산합니다.

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

`G`(기가바이트), `M`(메가바이트), `K`(킬로바이트) 접미사를 사용할 수 있습니다. 배치 크기는 페이지당 약 50KB로 잡는 휴리스틱으로 계산합니다.

### 환경 변수

CLI 플래그가 없을 때의 대체값으로 `HWARO_MEMORYLIMIT`을 설정할 수 있습니다.

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

CLI `--memory-limit` 플래그가 항상 환경 변수보다 우선합니다.

둘 중 하나라도 설정하면 `hwaro build`가 평소에 적용하는 GC 힙 사전 확보(`GC_INITIAL_HEAP_SIZE=256M`)도 함께 꺼집니다. 미리 확보한 힙은 그 하한 아래로 다시 줄어들지 않기 때문에, 지정한 메모리 한도와 반대로 작용하기 때문입니다.

### 플래그 조합

`--stream`과 `--memory-limit`은 함께 쓸 수 있습니다. `--memory-limit`이 지정되면 `--stream` 여부와 관계없이 배치 크기는 이 값으로 결정됩니다.

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

## 플래그 상호작용

| `--stream` | `--memory-limit` | `HWARO_MEMORYLIMIT` | 결과 |
|---|---|---|---|
| - | - | - | 일반 빌드 |
| 예 | - | - | 스트리밍, batch=500 |
| - | 2G | - | 스트리밍, batch≈20000 |
| - | - | 1G | 스트리밍, batch≈10000 |
| 예 | 512M | - | 스트리밍, batch≈5000 |
| - | 2G | 1G | CLI 우선(2G) |

## 동작 방식

1. Render 단계에서 페이지를 배치로 나눕니다
2. 각 배치는 일반 빌드와 동일한 병렬/순차 로직으로 렌더링됩니다
3. 배치를 디스크에 쓴 뒤 `page.content`를 비워 메모리를 해제합니다 — 단, 이후 단계에서 다시 읽지 않을 때만 그렇습니다(아래 참고)
4. 가비지 컬렉터를 호출해 해제된 메모리를 회수합니다
5. Generate 단계(피드, 사이트맵, 검색 인덱스)가 끝나면 `page.raw_content`도 비웁니다

### `page.content`를 유지하는 경우

검색 인덱스와 모든 피드는 Generate 단계에서 각 페이지의 렌더링된 본문을 다시
읽습니다. 이때 본문을 이미 해제했다면 생성기는 `raw_content`를 마크다운으로만
다시 렌더링한 결과를 쓰게 되고 — 숏코드 확장도, `@/` 링크 해석도, 앵커 링크도,
`base_path` 접두사도 없습니다 — `search.json`과 `rss.xml`에 날것의
`{% shortcode %}` 마크업과 깨진 링크가 실립니다.

그래서 다음 중 하나라도 켜져 있으면 3번 단계를 건너뜁니다.

- `[search] enabled`
- `[feeds] enabled`
- `feed = true`인 `[[taxonomies]]`
- `_index.md`에 `generate_feeds`를 설정한 섹션

모두 꺼져 있으면 기존처럼 배치마다 해제합니다. 어느 쪽이든 렌더링 자체는 여전히
배치 단위로 진행되므로 배치별 최대 사용량(워커 템플릿 출력, Crinja 값 캐시)은
계속 제한됩니다.

## 출력

빌드 출력은 스트리밍 사용 여부와 관계없이 **동일**합니다. 스트리밍은 빌드 중 메모리 사용량에만 영향을 줍니다.

> v0.20.1까지의 릴리스에서는 그렇지 않았습니다. 검색 인덱스나 피드를 쓰는
> 사이트에서 `--stream`은 확장되지 않은 숏코드와 해석되지 않은 `@/` 링크를
> `search.json`과 모든 피드에 실었습니다. 해당 사이트는 업그레이드 후 한 번 다시
> 빌드해 주세요.

`--verbose`를 붙이면 배치 진행 상황을 볼 수 있습니다.

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

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

## 함께 보기

- [CLI](/ko/start/cli/) — 빌드 플래그 전체 목록
- [빌드 훅](/ko/features/build-hooks/) — 빌드 전후 사용자 정의 명령 실행

---

Title: 구조화된 데이터
URL: https://hwaro.hahwul.com/ko/features/structured-data/
Source: content/features/structured-data.ko.md
Language: ko

Hwaro는 리치 검색 결과를 위한 JSON-LD 구조화된 데이터를 자동 생성합니다. 기본 제공되는 Article과 BreadcrumbList 외에 추가 Schema.org 타입도 활성화할 수 있습니다.

## 자동 생성 (항상)

다음은 모든 페이지에 생성됩니다:

- **Article** — headline, 날짜, 설명, 작성자, 이미지
- **BreadcrumbList** — 페이지 계층/상위 페이지에서 자동 생성

템플릿 변수로 제공됩니다: `{{ jsonld }}`, `{{ jsonld_article }}`, `{{ jsonld_breadcrumb }}`

## 사이트 전역 스키마

한 번만 생성되어 모든 페이지에서 사용할 수 있습니다:

### WebSite + SearchAction

Google의 사이트링크 검색창을 활성화합니다. `[search]`가 켜져 있으면 `SearchAction`이 자동으로 포함됩니다.

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

### Organization

사이트 설정에서 가져온 기본 조직 정보입니다. `og.default_image`가 설정되어 있으면 로고로 사용합니다.

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

## 페이지별 스키마

프론트 매터에 `schema_type`을 설정하면 추가 타입을 자동 감지해 포함합니다:

### 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."]
+++
```

또는 쌍(pair) 배열 형식을 사용합니다:
```toml
faq = ["Question 1", "Answer 1", "Question 2", "Answer 2"]
```

`schema_type = "FAQ"`이면 FAQ 스키마가 `{{ jsonld }}`에 자동 포함됩니다. `{{ jsonld_faq }}`를 직접 써도 됩니다.

### 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."]
+++
```

또는 쌍 배열 형식을 사용합니다:
```toml
howto_steps = ["Step Name", "Step Description", "Step 2 Name", "Step 2 Description"]
```

`schema_type = "HowTo"`이면 `{{ jsonld }}`에 자동 포함됩니다. `{{ jsonld_howto }}`로도 쓸 수 있습니다.

### Person

작성자 페이지 템플릿에서 사용합니다:

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

또는 템플릿 함수로 직접 구성해도 됩니다 (작성자별 페이지용).

## 템플릿 변수

| 변수 | 범위 | 설명 |
|----------|-------|-------------|
| `jsonld` | 페이지별 | 적용 가능한 JSON-LD 전체 결합 (Article + Breadcrumb + 확장 타입) |
| `jsonld_article` | 페이지별 | Article 스키마만 |
| `jsonld_breadcrumb` | 페이지별 | BreadcrumbList 스키마만 |
| `jsonld_faq` | 페이지별 | FAQPage 스키마 (FAQ가 아니면 비어 있음) |
| `jsonld_howto` | 페이지별 | HowTo 스키마 (HowTo가 아니면 비어 있음) |
| `jsonld_website` | 전역 | WebSite + SearchAction 스키마 |
| `jsonld_organization` | 전역 | Organization 스키마 |

## 템플릿에서 사용

베이스 템플릿의 `<head>`에 넣는 일반적인 배치:

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

## 함께 보기

- [SEO](/ko/features/seo/) — 사이트맵, 피드, OpenGraph, canonical 태그
- [설정](/ko/start/config/) — 전체 설정 레퍼런스

---

Title: 구문 강조
URL: https://hwaro.hahwul.com/ko/features/syntax-highlighting/
Source: content/features/syntax-highlighting.ko.md
Language: ko

마크다운의 코드 블록은 자동으로 구문 강조됩니다.

## 사용법

언어 식별자를 붙인 펜스 코드 블록을 사용합니다.

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

## 지원 언어

자주 쓰는 언어:

| 언어 | 식별자 |
|----------|-------------|
| 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 |

## 설정

`config.toml`에서 설정합니다.

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

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| enabled | bool | true | 구문 강조 활성화 |
| theme | string | "github" | Highlight.js 테마 이름 |
| use_cdn | bool | true | 에셋을 CDN에서 로드(false = 로컬 파일) |
| mode | string | "server" | `"server"`는 빌드 시점에 강조, `"client"`는 브라우저에서 Highlight.js로 강조 |
| line_numbers | bool | false | 모든 펜스 코드 블록에 기본으로 줄 번호 추가(아래 참고) |
| copy | bool | false | 펜스 코드 블록에 클립보드 복사 버튼 추가(아래 참고) |

## 서버 사이드 강조(기본값)

`mode = "server"`(기본값)에서는 빌드 중에 코드 블록이 강조됩니다. 브라우저로 JavaScript가 전송되지 않고, JavaScript를 꺼 놓아도 코드에 색이 입혀집니다.

빌드 시점 하이라이터는 Highlight.js 호환 CSS 클래스를 출력하므로, 아래의 모든 테마가 그대로 동작합니다. `{{ highlight_css }}`는 여전히 테마 스타일시트를 주입하고, `{{ highlight_js }}`는 빈 값이 됩니다.

250개가 넘는 언어를 지원합니다(Pygments/Chroma에서 포팅된 [Tartrazine](https://github.com/ralsina/tartrazine) 렉서 사용). 렉서가 없는 언어의 코드 블록은 강조 없는 일반 출력으로 대체됩니다.

## 클라이언트 사이드 강조

`mode = "client"`로 설정하면 대신 브라우저에서 Highlight.js로 강조합니다.

```toml
[highlight]
mode = "client"
theme = "github-dark"
```

클라이언트 모드에서는 `{{ highlight_js }}`가 Highlight.js 스크립트를 주입하고(CDN 또는 로컬 에셋에서. 아래 참고), 코드 블록은 브라우저가 색을 입힐 수 있도록 일반 `<pre><code class="language-...">` 마크업으로 출력됩니다.

## 줄 번호와 줄 강조

펜스 코드 블록의 언어 뒤에 옵션 블록 `{...}`을 붙여 줄 번호를 넣거나 특정 줄을 강조할 수 있습니다.

````markdown
```python {linenos=true, hl_lines="2-4 7", linenostart=5}
def main():
    setup()
    run()
    teardown()
    return 0
```
````

| 옵션 | 값 | 설명 |
|--------|-------|--------------|
| `linenos` | `true` / `false` | 줄 번호 거터 표시. 이 블록에 한해 `[highlight] line_numbers` 기본값을 덮어씀 |
| `hl_lines` | 예: `"2-4 7"` | 지정한 줄을 강조. 공백/쉼표로 구분한 줄 번호나 범위. 항상 블록 자체의 **물리적** 1-기반 줄 번호이며 `linenostart`의 영향을 받지 않음 |
| `linenostart` | 예: `5` | 표시되는 첫 줄 번호(기본 `1`). 화면에 보이는 번호만 바꿀 뿐, `hl_lines`가 강조하는 물리적 줄은 바뀌지 않음 |
| `hide_lines` | 예: `"1 9-12"` | 지정한 줄을 렌더링 출력에서 제외(서버 모드 전용, 아래 참고). 문법과 물리적 줄 의미는 `hl_lines`와 동일 |
| `copy` | `true` / `false` | 이 블록에 복사 버튼 표시. `[highlight] copy` 기본값을 덮어씀. `mermaid` 펜스에서는 무시됨 |
| `name` | 예: `"main.cr"` | 블록 위에 렌더링되는 파일명/제목 라벨(`title=`도 별칭으로 허용). `mermaid` 펜스에서는 무시됨 |

이름이 붙은 블록은 스타일링을 위해 래핑됩니다(내부의 `<pre>`는 그대로).

```html
<div class="code-block"><div class="code-filename">main.cr</div>
<pre><code class="language-crystal hljs">…</code></pre>
</div>
```

스캐폴드로 만든 사이트에는 이에 맞는 `.code-block` / `.code-filename` 스타일이 포함되어 있습니다. 그 외에는 직접 CSS를 준비해야 합니다.

옵션 블록은 몇 가지 동등한 형태를 허용합니다. `python {linenos=true}`, `python{linenos=true}`(공백 없음), 언어 없이 `{linenos=true}`만 쓰는 형태 모두 가능합니다. 형식이 잘못됐거나 인식할 수 없는 옵션 블록(예: `{oops}`)은 펜스 옵션이 없는 것처럼 언어 토큰의 리터럴 텍스트로 남습니다.

`[highlight] line_numbers = true`를 설정하면 언어가 지정된 *모든* 펜스 코드 블록에 줄 번호가 켜집니다. 블록별 `{linenos=false}`로 다시 끌 수 있습니다.

숨긴 줄도 물리적 줄 번호는 그대로 차지하므로, `linenos=true`일 때 거터에는 줄이 생략된 자리에 **번호 공백**이 생깁니다. 남은 줄의 번호를 다시 매기는 Zola와는 다른 동작입니다. 덕분에 `hl_lines`와 `linenostart`가 숨김 여부와 무관하게 항상 블록의 물리적 줄을 가리킨다는 문서화된 불변 조건이 유지됩니다(숨긴 줄을 강조하는 것은 그저 아무 효과가 없을 뿐입니다).

숨긴 줄을 HTML에서 실제로 제거하는 것은 `mode = "server"`뿐입니다. 클라이언트 모드의 `hide_lines`는 표시용 메타데이터(비활성 `data-hide-lines` 속성)일 뿐이며, 해당 줄은 페이지 소스에 그대로 남습니다. 클라이언트 모드에서 비밀 값을 가리는 용도로 `hide_lines`를 사용하면 **안 됩니다**.

**서버 모드와 클라이언트 모드:**

- `mode = "server"`(기본값)는 빌드 시점에 결과를 완전히 렌더링합니다. 각 줄이 자체 요소로 래핑되므로 줄 번호와 줄 강조가 JavaScript 없이 표시됩니다.
- `mode = "client"`는 본문을 다시 렌더링하지 않습니다. 대신 `<pre>` 태그에 `data-linenos="true"`, `data-linenostart="N"`(1보다 클 때), `data-hl-lines="2-4 7"`, `data-hide-lines="1 9-12"` 속성이 붙어서 클라이언트 스크립트나 커스텀 CSS가 이를 활용할 수 있습니다. Hwaro는 클라이언트 모드용 스크립트를 제공하지 않습니다. 완전한 렌더링(과 실제 줄 숨김)에는 `mode = "server"`가 필요합니다.

스캐폴드 사이트는 서버 모드 마크업 스타일을 기본으로 제공합니다. 스캐폴드가 아닌 사이트나 커스텀 테마에서는 다음을 추가합니다.

```css
pre code .line.hl { display: inline-block; width: 100%; background: color-mix(in srgb, var(--code-keyword) 12%, transparent); }
pre code .ln { user-select: none; -webkit-user-select: none; opacity: .45; }
```

(Hwaro Ember 토큰 시스템을 쓰지 않는다면 `var(--code-keyword)`를 테마에 맞는 아무 색으로 바꾸면 됩니다.)

## 복사 버튼

`[highlight] copy = true`는 모든 펜스 코드 블록에 클립보드 복사 버튼을 추가합니다. 펜스별 `{copy=false}`(또는 전역 기본값이 꺼진 상태의 `{copy=true}`)가 이를 덮어씁니다.

```toml
[highlight]
copy = true
```

마크업 계약은 이렇습니다. 옵트인한 각 블록의 `<pre>`에 `data-copy="true"` 속성이 붙고, `{{ highlight_js }}`가 의존성 없는 작은 인라인 런타임을 주입합니다(서버·클라이언트 모드 모두 동작). `copy = true`이면 런타임이 사이트 전체에 포함되고, 전역 기본값이 꺼져 있으면 옵트인 블록이 본문에 있는 페이지에만 해당 페이지의 `{{ highlight_js }}`에 덧붙습니다. 없는 페이지는 JavaScript가 없는 상태를 유지합니다. 런타임은 각 `pre[data-copy]`를 `<div class="code-wrapper">`로 감싸고(이름 붙은 펜스처럼 기존 `.code-block` 래퍼가 있으면 그것을 앵커로 재사용), `<button class="code-copy-btn">`을 덧붙인 뒤, 클릭 시 코드 텍스트를 복사합니다(서버 모드의 `.ln` 줄 번호 거터는 복사되는 텍스트에서 제거됩니다). 인라인 스타일은 테마 중립적(currentColor, 호버 시 표시)이며, 스캐폴드 사이트는 토큰 기반 스타일로 이를 덮어씁니다.

`mermaid` 펜스에는 이 속성이 절대 붙지 않습니다. 그 `<pre>` 구조는 Mermaid 파이프라인이 소유합니다.

새로 스캐폴드한 사이트는 `copy = true`가 기본으로 켜져 있습니다.

## 테마

Hwaro는 [Highlight.js](https://highlightjs.org/) 테마를 사용합니다. 유효한 Highlight.js 테마 이름이면 무엇이든 동작합니다. 많이 쓰는 테마:

- `github` — 밝은 GitHub 스타일(기본값)
- `github-dark` — 어두운 GitHub 스타일
- `github-dark-dimmed` — 톤을 낮춘 어두운 GitHub 스타일
- `monokai` — 클래식 다크 테마
- `dracula` — 어두운 보라색 테마
- `solarized-dark` — Solarized 다크
- `solarized-light` — Solarized 라이트
- `nord` — 북극 색 팔레트
- `tokyo-night-dark` — Tokyo Night 다크

전체 테마 목록은 [highlightjs.org/demo](https://highlightjs.org/demo)에서 볼 수 있습니다.

## CDN과 로컬

`use_cdn = true`(기본값)이면 에셋을 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>
```

`use_cdn = false`이면 로컬 경로에서 로드합니다.

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

`use_cdn = false`를 쓸 때는 로컬 파일을 직접 준비해야 합니다. 기본값인 서버 모드에서는 테마 스타일시트만 참조됩니다. 위의 `<script>` 태그는 `mode = "client"`일 때만 나타납니다.

## 템플릿 연동

템플릿에 강조 에셋을 포함합니다.

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

또는 한 번에:

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

## 빌드 옵션

빌드 속도를 높이려면 강조를 비활성화합니다.

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

## 일반 텍스트 블록

강조하지 않으려면 언어를 생략하거나 `text`를 사용합니다.

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

## 인라인 코드

인라인 코드는 백틱을 사용하며 강조되지 않습니다.

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

## 함께 보기

- [마크다운 확장](/ko/features/markdown-extensions/) — 코드 블록과 언어 지원
- [설정](/ko/start/config/) — 강조 설정 레퍼런스

---

Title: 버전별 문서
URL: https://hwaro.hahwul.com/ko/features/versioned-docs/
Source: content/features/versioned-docs.ko.md
Language: ko

Hwaro는 하나의 사이트에서 같은 문서의 여러 버전(v1, v2, …)을 게시할 수 있습니다. 버전 전환기, 버전별 내비게이션, 그리고 검색 엔진을 최신 릴리스로 안내하는 SEO를 제공합니다. 버전 관리는 **디렉터리 기반**이며 [다국어](/ko/features/multilingual/) 지원을 본떠 설계되었습니다. 페이지는 자신을 담고 있는 콘텐츠 디렉터리의 버전에 속합니다.

## 설정

```toml
[versions]
latest_at_root = true     # 최신 버전은 섹션의 원래 URL에 렌더링
noindex_old = true        # 이전 버전: <meta name="robots" content="noindex"> + 최신 대응 페이지로 canonical
search = "latest"         # "latest" | "all" — search.json과 sitemap.xml에 들어갈 버전
feeds = "latest"          # "latest" | "all" — RSS/Atom에 들어갈 버전
taxonomies = "latest"     # "latest" | "all" — 택소노미 용어 페이지가 수집할 버전

[[versions.list]]
name = "v2"               # URL 세그먼트, URL-safe 문자만 허용 (영문자, 숫자, - _ . ~)
label = "2.x (latest)"    # 전환기 라벨 (기본값: name)
path = "docs/v2"          # content/ 기준 콘텐츠 디렉터리 (기본값: name)
latest = true

[[versions.list]]
name = "v1"
label = "1.x"
path = "docs/v1"
```

TOML에서는 하나의 키가 테이블과 테이블 배열을 동시에 가질 수 없으므로, 스위치는 `[versions]`에, 항목은 `[[versions.list]]`에 둡니다. 기본값만 필요하다면 배열만 써도 됩니다:

```toml
[[versions]]
name = "v2"
path = "docs/v2"
latest = true

[[versions]]
name = "v1"
path = "docs/v1"
```

검증 규칙 (모두 `HWARO_E_CONFIG`로 빌드가 실패합니다):

- `name`은 필수이며 URL-safe하고 고유해야 합니다.
- `path`는 `content/` 기준 디렉터리여야 하며, 두 버전이 같은 경로를 쓰거나 서로 중첩될 수 없습니다.
- `latest = true`는 정확히 하나여야 합니다. 표시된 항목이 없으면 **첫 번째** 항목이 최신이 되고, 둘 이상이면 오류입니다.
- `search`, `feeds`, `taxonomies`는 `"latest"` 또는 `"all"`만 허용합니다.

`hwaro doctor`는 존재하지 않는 콘텐츠 디렉터리를 가리키는 버전이 있으면 `version-path-missing` 경고를 냅니다.

## 콘텐츠 구조

각 버전은 자기 디렉터리 아래의 일반 콘텐츠 트리입니다. 버전 루트 기준 상대 경로가 같은 파일은 다른 버전의 같은 페이지로 취급되며, 전환기는 이 규칙으로 대응 페이지를 찾습니다.

```
content/
└── docs/
    ├── v2/
    │   ├── _index.md
    │   ├── install.md
    │   └── plugins.md      # v2에만 존재
    └── v1/
        ├── _index.md
        ├── install.md
        └── legacy.md       # v1에만 존재
```

### URL 매핑

버전 디렉터리는 그 버전이 *게시되는* 디렉터리로 치환됩니다. `latest_at_root = true`(기본값)이면 최신 버전이 상위 디렉터리의 원래 URL을 차지하고, 이전 버전은 `/<name>/` 세그먼트를 갖습니다:

| 소스 | URL |
|------|-----|
| `content/docs/v2/_index.md` | `/docs/` |
| `content/docs/v2/install.md` | `/docs/install/` |
| `content/docs/v1/_index.md` | `/docs/v1/` |
| `content/docs/v1/install.md` | `/docs/v1/install/` |

`latest_at_root = false`이면 모든 버전이 세그먼트를 유지하고(`/docs/v2/install/`, `/docs/v1/install/`), `/docs/`는 최신 버전 루트로 향하는 리디렉션 스텁이 됩니다. 직접 `content/docs/_index.md`를 작성했다면 그 페이지가 URL을 유지합니다.

URL 세그먼트는 디렉터리 이름이 아니라 버전 **name**입니다. `name = "2.x"`, `path = "docs/v2"`라면 루트가 아닐 때 `/docs/2.x/…`에 게시됩니다. 버전 디렉터리는 최상위(`content/v2/…`)에 둘 수도 있으며, 이 경우 최신 버전이 사이트 루트가 됩니다.

참고:

- `latest_at_root = true`일 때는 `content/docs/_index.md`를 함께 두지 마세요. 최신 버전 루트와 같은 `/docs/` URL을 차지하므로 빌드가 출력 경로 중복을 보고합니다(작성한 파일이 우선하고 버전 루트는 기록되지 않습니다).
- `[permalinks]` 규칙과 `slug`는 소스 경로가 아니라 게시 경로(`docs/install.md`)에 적용됩니다.
- 프론트 매터의 명시적 `path = "…"`는 언어와 마찬가지로 항상 우선합니다. 커스텀 경로에는 접두어가 붙지 않으므로 버전 간에 서로 다르게 유지해야 합니다.
- 버전 디렉터리 아래의 모든 것이 버전에 속합니다: 페이지 번들, 에셋, `_index.md` 캐스케이드, 대상 경로가 그 안에 있는 `[[content.generate]]` 결과물까지.

### 다국어

언어와 버전은 함께 사용할 수 있습니다. 언어 접두어가 먼저, 버전이 그 뒤에 옵니다. `content/docs/v1/install.ko.md`는 `/ko/docs/v1/install/`에 렌더링되며, 버전 디렉터리 안의 `foo.ko.md` 파일은 다른 곳과 똑같이 동작합니다(번역 연결, hreflang, 언어별 메뉴).

## 템플릿 변수

### page.version

버전이 없는 페이지에서는 `nil`이므로(`{% if page.version %}`이 가드), 그 외에는:

| 속성 | 타입 | 설명 |
|------|------|------|
| `.name` | String | 버전 이름 (`"v2"`) |
| `.label` | String | 표시 라벨 (`"2.x (latest)"`) |
| `.latest` | Bool | 최신 버전인지 |
| `.url` | String | 페이지 언어 기준 버전 루트 URL (`/docs/`, `/ko/docs/v1/`) |

### page.version_links

설정된 버전마다 하나씩, 설정 순서대로 나열되며, 전환기의 각 행이 됩니다. 버전이 없는 페이지에서는 비어 있습니다.

| 속성 | 타입 | 설명 |
|------|------|------|
| `.name` | String | 버전 이름 |
| `.label` | String | 표시 라벨 |
| `.latest` | Bool | 최신 버전인지 |
| `.url` | String | 그 버전에 **같은 페이지**가 있으면 그 URL, 없으면 그 버전의 루트 |
| `.exists` | Bool | 대응 페이지 존재 여부 (`false`면 `url`은 버전 루트) |
| `.current` | Bool | 이 행이 현재 페이지의 버전인지 |

대응 페이지는 같은 언어에서 버전 루트 기준 상대 경로로 매칭됩니다: `docs/v1/install.md` ↔ `docs/v2/install.md`, `docs/v1/install.ko.md` ↔ `docs/v2/install.ko.md`. `render = false`인 대응 페이지는 존재하지 않는 것으로 취급합니다.

### versions (전역)

버전 사이트의 모든 페이지에서 사용할 수 있습니다. `{name, label, latest, url}` 항목의 리스트(`{% for v in versions %}`)이며 `url`은 현재 페이지 언어 기준 각 버전의 루트입니다. 추가로:

| 속성 | 설명 |
|------|------|
| `versions.latest` | 최신 버전 항목 |
| `versions.all` | 같은 리스트를 일반 배열로 |
| `versions.size` | 버전 개수 |

`page.url`처럼 위의 모든 URL은 사이트 상대 경로입니다. [서브패스 배포](/ko/start/config/#base-url)가 동작하도록 링크에는 `{{ base_url }}`(또는 `{{ base_path }}`)을 앞에 붙이세요.

## 버전 전환기 예시

```jinja
{% if page.version %}
<details class="version-switch">
  <summary aria-label="문서 버전 전환">
    {{ page.version.label }}
    {% if not page.version.latest %}<span class="badge">old</span>{% endif %}
  </summary>
  <ul>
    {% for v in page.version_links %}
    <li>
      <a href="{{ base_url }}{{ v.url }}"
         {% if v.current %}class="current" aria-current="page"{% endif %}
         {% if not v.exists %}title="이 페이지는 {{ v.label }}에 없습니다 — {{ v.label }} 시작 페이지로 이동"{% endif %}>
        {{ v.label }}{% if v.latest %} (latest){% endif %}
      </a>
    </li>
    {% endfor %}
  </ul>
</details>

{% if not page.version.latest %}
<div class="version-banner">
  {{ page.version.label }} 문서를 보고 있습니다.
  {% for v in page.version_links %}{% if v.latest %}
  <a href="{{ base_url }}{{ v.url }}">{% if v.exists %}{{ v.label }}에서 이 페이지 보기{% else %}{{ v.label }} 문서로 이동{% endif %}</a>
  {% endif %}{% endfor %}
</div>
{% endif %}
{% endif %}
```

현재 페이지에 의존하지 않는 사이트 전역 진입점:

```jinja
<a href="{{ base_url }}{{ versions.latest.url }}">Docs ({{ versions.latest.label }})</a>
<select onchange="location.href=this.value">
  {% for v in versions %}
  <option value="{{ base_url }}{{ v.url }}">{{ v.label }}</option>
  {% endfor %}
</select>
```

## 범위 규칙

각 버전은 독립된 트리이며, 경계를 넘어 새는 것은 없습니다:

| 대상 | 동작 |
|------|------|
| `page.lower` / `page.higher` | 읽기 순서는 `{언어, 버전}`별로 만들어집니다. 마지막 v1 페이지에는 "다음"이 없고 v2로 넘어가지 않습니다. |
| `page.ancestors` (브레드크럼) | 버전 루트에서 멈춥니다. 버전 없는 `docs/_index.md`는 `docs/v1/…`의 조상이 아닙니다. |
| `get_section()`, `section.pages`, `section.subsections` | 버전 루트는 버전 없는 상위 섹션의 하위 섹션이나 페이지가 아니며, 버전 안의 목록은 그 버전만 봅니다. |
| 메뉴 (`get_menu`) | 설정의 `[[menus.*]]` 항목은 어디에나 나타납니다. 버전 페이지의 프론트 매터 `menus = […]` 등록은 그 버전의 메뉴에만 나타나고, 버전 없는 페이지는 **최신** 버전의 등록을 추가로 봅니다. |
| 관련 글 | 버전 경계를 넘지 않습니다. |
| 택소노미 | 용어 페이지는 버전 없는 콘텐츠와 최신 버전에서 수집합니다(`taxonomies = "latest"`, 기본값). 모든 버전을 나열하려면 `taxonomies = "all"`. |

시리즈는 버전을 인식하지 않습니다. v1 페이지와 v2 페이지가 같은 `series`를 쓰면 함께 묶입니다.

## SEO와 탐색 표면

### Canonical과 noindex

이전 버전의 페이지는 **최신 대응 페이지**가 있으면 그쪽으로 canonical 링크를 내고(없으면 자기 자신), `noindex_old = true`(기본값)이면 바로 뒤에 `<meta name="robots" content="noindex">`를 붙입니다. 둘 다 `{{ canonical_tag }}`에서 나오므로 이미 이 변수를 출력하는 템플릿은 수정이 필요 없습니다. `seo.canonical_url`도 같은 규칙을 따르고 `seo.noindex`가 플래그를 노출합니다.

```html
<link rel="canonical" href="https://example.com/docs/install/">
<meta name="robots" content="noindex">
```

최신 버전 페이지는 평소처럼 자기 자신을 canonical로 가리킵니다. 페이지네이션된 목록은 계속 자기 자신을 가리킵니다(이전 섹션의 `page/2/`는 새 섹션의 `page/2/`가 아닙니다). `hreflang_tags`는 영향을 받지 않으며 같은 버전의 번역본을 연결합니다.

### 탐색 표면

| 표면 | 스위치 | 기본값 |
|------|--------|--------|
| `search.json` | `[versions] search` | 최신만 |
| `sitemap.xml` | `[versions] search` (같은 스위치) | 최신만 |
| RSS / Atom (메인, 섹션, 언어별) | `[versions] feeds` | 최신만 |
| 택소노미 용어 페이지 | `[versions] taxonomies` | 최신만 |
| `llms.txt` / `llms-full.txt` | — | 항상 최신만 |

버전 없는 페이지는 항상 포함됩니다. `search = "all"`이면 `search.json`의 모든 레코드에 `version` 필드(버전 이름)가 들어가므로 클라이언트에서 읽고 있는 버전으로 결과를 필터링할 수 있습니다:

```js
const current = document.documentElement.dataset.version; // 예: data-version="{{ page.version.name }}"
const hits = results.filter((r) => !r.version || r.version === current);
```

## 빌드 캐시, serve, doctor

- `[versions]`는 설정 해시에, 버전 소속은 페이지 집합 지문에 포함됩니다. 따라서 파일을 버전 디렉터리 간에 옮기거나, 대응 페이지를 추가하거나(다른 버전의 `version_links`에서 `exists`가 바뀜), 스위치를 바꾸면 `hwaro build --cache`가 바뀐 것을 다시 빌드합니다.
- `hwaro serve`는 버전 사이트도 다른 사이트처럼 빌드하며, 버전 디렉터리 안의 편집은 증분으로 반영됩니다.
- `hwaro doctor`는 디렉터리가 없는 `[[versions.list]]` 항목에 `version-path-missing`을 보고합니다.

## 포함되지 않은 것

- 최신 버전에만 존재하는 URL에 대한 리디렉션 규칙(이전 버전의 404는 그냥 404입니다).
- 버전을 인식하는 시리즈.
- `docs` 스캐폴드는 바뀌지 않았습니다. 생성된 사이트에는 위 스니펫으로 `[versions]`를 직접 추가하세요.

## 참고

- [다국어](/ko/features/multilingual/) — 버전과 결합되는 언어 계층
- [데이터 모델](/ko/templates/data-model/) — 모든 `page.*`와 전역 변수
- [SEO](/ko/features/seo/) — canonical, robots, 사이트맵 세부 사항
- [설정](/ko/start/config/) — 전체 `config.toml` 레퍼런스

---

Title: 연동
URL: https://hwaro.hahwul.com/ko/integrations/
Source: content/integrations/_index.ko.md
Language: ko

Hwaro는 기존 툴체인, 특히 AI 코딩 에이전트와 잘 맞물리도록 설계했습니다. 분류된 오류 코드, `--json` 출력, `AGENTS.md` 생성 기능은 모두 에이전트가 Hwaro를 안정적으로 다룰 수 있게 하기 위한 것입니다.

이 섹션에는 바로 사용할 수 있는 연동을 모았습니다.

## 이 섹션의 문서

- **[에이전트 스킬](/ko/integrations/skills/)** — Claude Code, Cursor, OpenCode, Codex 등 스킬을 지원하는 에이전트에게 Hwaro CLI 사용법과 좋은 Hwaro 사이트 설계법을 가르치는 설치형 `SKILL.md` 파일.

---

Title: 에이전트 스킬
URL: https://hwaro.hahwul.com/ko/integrations/skills/
Source: content/integrations/skills.ko.md
Language: ko

Hwaro는 두 개의 [에이전트 스킬](https://github.com/hahwul/hwaro/tree/main/skills)을 제공합니다. 스킬을 지원하는 AI 에이전트에게 Hwaro 사용법을 가르치는 독립적인 `SKILL.md` 파일로, 설치해 두면 에이전트가 Hwaro 작업을 감지했을 때 해당 스킬을 자동으로 불러옵니다.

| 스킬 | 가르치는 내용 |
|-------|-----------------|
| **`hwaro`** | CLI 운용. 스캐폴드(`init`), 콘텐츠 작성(`new`), 미리 보기(`serve`), 프로덕션 빌드(`build`), 그리고 `doctor`/`tool`/`deploy` 하위 명령. 에이전트에 안전한 출력 계약(`--json`, `--quiet`, `NO_COLOR`, 분류된 `HWARO_E_*` 오류/종료 코드)과 안전한 `config.toml`·Crinja 템플릿 수정을 강조합니다. |
| **`hwaro-design`** | 사이트 디자인과 리스타일링. **요구 사항을 읽고 한 줄짜리 Design Read를 선언한 뒤 세 가지 디자인 다이얼을 설정**하고(의도가 정말 모호할 때만 질문), Hwaro의 Crinja 템플릿과 CSS 변수 토큰 시스템 안에서 개성 있는 프로덕션 수준의 디자인을 만들어 냅니다. 뻔한 AI 미감을 걸러내는 엄격한 anti-slop 원칙과 기계적인 사전 점검을 따릅니다. |

## `npx skills`로 설치

[`skills` CLI](https://www.npmjs.com/package/skills)를 사용하면 스킬 설치와 업데이트가 가장 간편합니다. 저장소를 추가하면 두 Hwaro 스킬(`hwaro`, `hwaro-design`)이 **모두** 설치됩니다.

```bash
# 현재 프로젝트에 추가 — 에이전트를 고르라는 프롬프트 표시 (.claude/skills, .cursor/, …)
npx skills add hahwul/hwaro

# 모든 프로젝트에서 쓰도록 전역 설치
npx skills add hahwul/hwaro -g

# 특정 에이전트 지정 (예: Claude Code)
npx skills add hahwul/hwaro -a claude-code

# 비대화형 — CI에 적합
npx skills add hahwul/hwaro -g -a claude-code -y
```

나중에 스킬 이름으로 업데이트하거나 제거합니다:

```bash
npx skills update hwaro hwaro-design
npx skills remove hwaro hwaro-design
```

## 수동 설치

`npx`를 쓰고 싶지 않다면 저장소에서 파일을 직접 복사합니다. **Claude Code**의 설치 경로는 `~/.claude/skills/<name>/SKILL.md`입니다:

```bash
# hwaro — CLI 스킬
mkdir -p ~/.claude/skills/hwaro
curl -o ~/.claude/skills/hwaro/SKILL.md \
  https://raw.githubusercontent.com/hahwul/hwaro/main/skills/hwaro/SKILL.md

# hwaro-design — 디자인 스킬
mkdir -p ~/.claude/skills/hwaro-design
curl -o ~/.claude/skills/hwaro-design/SKILL.md \
  https://raw.githubusercontent.com/hahwul/hwaro/main/skills/hwaro-design/SKILL.md
```

다른 에이전트는 다른 스킬 디렉터리를 사용합니다(예: `.cursor/`, 프로젝트 로컬 `skills/` 폴더). 정확한 위치는 사용하는 에이전트의 문서를 확인합니다.

## 스킬이 다루는 내용

### `hwaro` — CLI 다루기

- **트리거 시점:** Hwaro 관련 작업이거나, `config.toml`과 함께 `content/`·`templates/`가 있는 디렉터리를 만났을 때.
- **출력 계약:** 사람이 읽는 텍스트를 긁어내는 대신 `--json`을 우선 사용하고, 분류된 종료 코드(`HWARO_E_USAGE`, `HWARO_E_CONFIG`, `HWARO_E_TEMPLATE`, `HWARO_E_CONTENT`, …)로 분기합니다.
- **워크플로:** `init` 스캐폴드, `new`와 아키타입, `serve` 라이브 리로드 개발 루프, 프로덕션 `build`(`--minify`, `--cache`, `--base-url`, 환경 변수 재정의), `doctor` / `tool validate` / `tool check-links`, 콘텐츠 도구, `tool platform`, `deploy`.
- **안전한 수정:** TOML 설정 규칙과 Crinja 템플릿 주의점(`| safe`, nil 가드, URL에는 `url_for`/`asset`), 그리고 종료 코드로 검증하는 루프.

### `hwaro-design` — 사이트 디자인

- **Design Read 우선:** CSS를 한 줄이라도 쓰기 전에 요구 사항을 읽고 한 줄짜리 디자인 방향과 세 가지 다이얼(`DESIGN_VARIANCE` / `MOTION_INTENSITY` / `VISUAL_DENSITY`)을 선언합니다. 의도가 정말 모호할 때만 짧고 집중된 질문을 하고, 전체 취향 인터뷰는 요청할 때만 진행하므로, 결과물은 기본값이 아니라 **사용자의** 취향을 반영합니다.
- **Anti-slop 원칙:** AI가 만든 디자인의 전형적 신호를 강하게 금지하는 방대한 목록(본문 카피의 em-dash, eyebrow 라벨 남용, 반복되는 섹션 레이아웃, hero 오버플로, `<div>`로 만든 가짜 스크린샷, AI 특유의 보라색 그라디언트, 장식용 점과 로케일 스트립, "Jane Doe" 데모 콘텐츠)에 레이아웃·카피 밀도·이미지 규칙을 더해, 완료를 선언하기 전에 기계적인 사전 점검 체크리스트로 전부 강제합니다.
- **Hwaro 메커니즘:** Crinja 템플릿 구조, 세 가지 CSS 전달 방식(인라인, `[auto_includes]`, `[assets]` 파이프라인), 모든 내장 스캐폴드가 테마의 기반으로 공유하는 `light-dark()` 디자인 토큰 어휘(라이트/다크는 자동 지원, 토큰 쌍만 재정의하면 리테마), `resize_image`를 이용한 반응형 이미지, CSS 스크롤 기반 애니메이션과 `IntersectionObserver`를 이용한 정적 사이트 모션을 다룹니다. 프레임워크가 필요 없습니다.

## 사전 요구 사항

에이전트가 실제로 빌드와 미리 보기를 실행할 수 있도록 Hwaro CLI를 설치합니다. [설치](/ko/start/installation/)를 참고합니다. 스킬은 그것이 다루는 바이너리가 있어야 비로소 쓸모가 있습니다.

`hwaro` 스킬은 프로젝트의 `AGENTS.md`를 보완합니다. 스킬이 어느 Hwaro 프로젝트에서든 에이전트를 따라다니는 이동 가능한 지침이라면, [`hwaro tool agents-md`](/ko/start/tools/agents-md/)로 생성하는 `AGENTS.md`는 프로젝트별 규칙을 담습니다. 에이전트는 `AGENTS.md`를 먼저 읽어야 하며, 이 파일이 스킬의 기본값을 재정의할 수 있습니다.

## 작성 팁

두 스킬 모두 Hwaro 저장소의 [`skills/`](https://github.com/hahwul/hwaro/tree/main/skills) 아래에 있습니다. 기여할 때는 다음을 지킵니다:

- CLI/템플릿 레퍼런스 전체를 복제하는 대신(그 내용은 이 문서로 링크), **에이전트의 상호작용 패턴**(무엇을 언제 실행하고 어떻게 복구하는지)을 중심으로 작성합니다.
- 프론트 매터의 `description`을 정확하게 유지합니다. 에이전트는 이 값을 읽고 스킬을 *언제* 불러올지 결정합니다.
- [GitHub](https://github.com/hahwul/hwaro)에 풀 리퀘스트를 엽니다.

## 함께 보기

- [CLI](/ko/start/cli/) — `hwaro` 스킬이 다루는 모든 명령과 플래그.
- [agents-md](/ko/start/tools/agents-md/) — AI 에이전트를 위한 프로젝트별 지침.
- [템플릿](/ko/templates/) — 디자인 스킬이 기반으로 삼는 데이터 모델, 함수, 필터.

---

Title: 시작하기
URL: https://hwaro.hahwul.com/ko/start/
Source: content/start/_index.ko.md
Language: ko

## Hwaro란?

Hwaro는 [Crystal](https://crystal-lang.org)로 작성한 가볍고 빠른 정적 사이트 생성기(SSG)입니다. TOML·YAML·JSON 프론트 매터가 붙은 마크다운 콘텐츠와 Jinja2 호환 템플릿(Crinja)을 처리해 고성능 정적 사이트를 만듭니다.

Hwaro는 **기성 테마에 기대지 않고 자기만의 웹사이트를 만들도록** 설계했습니다. 테마를 골라 손보는 대신 템플릿과 스타일을 처음부터 직접 만들기 때문에 사이트의 모든 부분을 원하는 대로 다룰 수 있습니다. 병렬 빌드, 증분 캐시, 라이브 리로드가 있는 개발 서버 덕분에 개발 경험도 빠르고 매끄럽습니다.

## 빠른 시작

```bash
# 설치 (전체 방법은 설치 문서 참고)
brew tap hahwul/hwaro && brew install hwaro

# 새 사이트 생성
hwaro init my-site --scaffold blog
cd my-site

# 라이브 리로드가 켜진 개발 서버 시작
hwaro serve
```

`http://localhost:3000`을 열어 사이트를 확인합니다.

## 왜 "Hwaro"인가?

Hwaro(화로)는 **Furnace**를 뜻하는 우리말로, 마인크래프트 한국어판에서도 같은 이름을 씁니다. 게임 속 화로는 원재료를 유용한 아이템으로 바꿔 주는 필수 도구입니다. Hwaro도 정적 사이트에서 같은 역할을 합니다. 콘텐츠를 넣으면 완성된 웹사이트가 나옵니다.

![마인크래프트의 화로](/images/hwaro-minecraft.webp)

---

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

Hwaro는 사이트를 만들고, 빌드하고, 서빙하는 명령을 제공합니다.

## 전역 플래그

이 플래그들은 모든 최상위 명령에서 동작하며 CLI가 터미널에 출력하는
방식을 제어합니다. 스크립트, CI 로그, 깔끔한 출력이 필요한 AI 에이전트에
특히 유용합니다.

| 플래그 / 환경 변수 | 설명 |
|----------------|-------------|
| `-q`, `--quiet` | 정보성 출력과 시작 배너를 숨김. 경고와 오류는 stderr에 계속 표시 |
| `NO_COLOR` (env) | 비어 있지 않은 값이면 모든 명령 출력에서 ANSI 색상 코드를 제거. [no-color.org](https://no-color.org)의 도구 공통 규약을 따름 |
| `GC_MARKERS` (env) | GC 마커 스레드 수. `hwaro build`에 한해 Hwaro가 `1`을 기본값으로 지정합니다(할당이 많은 사이트에서 3~5배 빠르게 측정됨). 직접 export 하면 덮어쓸 수 있습니다. 다른 명령은 가비지 컬렉터의 기본 동작을 그대로 씁니다 |
| `GC_INITIAL_HEAP_SIZE` (env) | GC 초기 힙 크기. `hwaro build`에 한해 Hwaro가 `256M`을 기본값으로 지정해 힙 확장-수집 사이클 반복을 피합니다. 직접 export 하면 덮어쓸 수 있습니다. `--memory-limit` / `HWARO_MEMORYLIMIT`가 설정되어 있으면 자동으로 건너뜁니다 |

stdout이 TTY가 아니면(예: `cat`으로 파이프, 파일로 리디렉션, 대부분의
CI 환경) 색상은 자동으로 꺼집니다. 어디서든 색상을 강제로 끄려면
`NO_COLOR=1`만 설정하면 됩니다. 별도 플래그는 필요 없습니다.

```bash
# 스크립트·CI용 무음 빌드 — 경고와 오류만 표시됨
hwaro build --quiet

# stdout이 TTY여도 ANSI 이스케이프 없는 일반 텍스트 출력
NO_COLOR=1 hwaro doctor
```

### 오류 분류

분류된 실패 경로는 안정적인 오류 코드와 그에 대응하는 프로세스 종료
코드를 함께 내보냅니다. 스크립트, CI, 에이전트가 사람 대상 메시지를
파싱하지 않고도 안정적으로 분기할 수 있습니다.

텍스트 모드에서는 오류 줄 앞에 코드가 붙습니다:

```
Error [HWARO_E_USAGE]: missing <path> argument
```

`--json`에서는 분류된 오류가 대신 stdout에 구조화된 페이로드로
출력됩니다. (`--quiet`는 정보성 출력만 숨깁니다. 오류는 그대로
stderr에 사람이 읽는 `Error [CODE]: …` 형태로 남으므로, 기계가 읽을
수 있는 실패 출력이 필요하면 `--json`과 함께 사용합니다.)

```json
{
  "status": "error",
  "error": {
    "code": "HWARO_E_USAGE",
    "category": "usage",
    "message": "missing <path> argument",
    "hint": "Usage: hwaro new <path> [options] — run 'hwaro new --help' for details."
  }
}
```

분류되지 않은 실패는 기존 `Error: <message>` 형식과 종료 코드 `1`을
그대로 유지하므로, 이 규약은 기존 동작에 순수하게 추가만 됩니다.

| 코드 | 분류 | 종료 코드 | 설명 |
|------|----------|------|-------------|
| `HWARO_E_USAGE` | usage | 2 | 잘못되거나 누락된 플래그, 필수 인자 누락, 알 수 없는 명령 |
| `HWARO_E_CONFIG` | config | 3 | `config.toml` 누락, 파싱 불가 또는 유효하지 않음 |
| `HWARO_E_TEMPLATE` | template | 4 | Crinja 템플릿 렌더링 오류 |
| `HWARO_E_CONTENT` | content | 5 | 콘텐츠 파일 파싱 오류, 유효하지 않은 프론트 매터 |
| `HWARO_E_IO` | io | 6 | 파일시스템 접근 오류 (디렉터리 없음, 권한 거부) |
| `HWARO_E_NETWORK` | network | 7 | 배포 업로드, 원격 스캐폴드 가져오기 실패 |
| `HWARO_E_INTERNAL` | internal | 70 | 복구 불가능한 버그 또는 예기치 않은 상태 |
| *(미분류)* | — | 1 | 기존/일반 실패 경로 |
| *(성공)* | — | 0 | 명령 정상 완료 |

## 명령

### init

새 사이트를 만듭니다:

```bash
hwaro init                    # 기본값으로 즉시 초기화
hwaro init my-site            # my-site/에 초기화
hwaro init --wizard           # 대화형 위저드(TTY): 스캐폴드, 제목
hwaro init my-site --wizard   # 위저드; 디렉터리 프롬프트 생략 (경로는 인자 사용)
hwaro init my-site --scaffold blog
hwaro init my-site --scaffold docs
hwaro init my-site --scaffold book
```

**대화형 모드:**

대화형 터미널에서 `--wizard`를 주면 안내 흐름이 열립니다. 디렉터리,
스캐폴드, 사이트 제목을 차례로 묻고, 요약을 보여 준 뒤 확인을 받고
나서야 파일을 씁니다. 경로 인자를 함께 주면(`hwaro init my-site --wizard`)
위저드는 디렉터리 프롬프트를 건너뛰고 그 경로를 그대로 사용합니다.

`--wizard` 없이 실행하면 `hwaro init`은 기본값으로 즉시 초기화합니다.
스크립트와 CI가 기존에 의존하던 동작 그대로입니다.

모든 스캐폴드는 읽는 사람의 OS 색상 모드를 자동으로 따릅니다(공유 토큰
시스템이 CSS `light-dark()` 쌍을 사용). 스타일이 있는 스캐폴드에는
auto → light → dark로 순환하며 선택을 `localStorage`에 기억하는 헤더
테마 전환 버튼이 들어 있습니다. 한 가지 모드로 고정하려면
`css/style.css` 끝에 `:root { color-scheme: dark; }`(또는 `light`)를
추가합니다.

GitHub 저장소의 원격 스캐폴드도 사용할 수 있습니다:

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

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

원격 스캐폴드는 저장소에서 `config.toml`, `templates/`, `static/`,
콘텐츠 구조를 가져옵니다. 콘텐츠 파일은 프론트 매터(메타데이터)만
유지하므로 원본 본문 없이도 기대되는 페이지 구조를 확인할 수 있습니다.
API 요청 제한을 피하려면 `GITHUB_TOKEN` 환경 변수를 설정합니다.

**옵션:**

| 플래그 | 설명 |
|------|-------------|
| --scaffold TYPE | 내장 스캐폴드(`simple`, `bare`, `blog`, `docs`, `book`) 또는 원격 소스(`github:user/repo[/path]`, URL) |
| --wizard | 대화형 위저드 실행 (TTY 전용) |
| --agents MODE | AGENTS.md 콘텐츠 모드: `remote`(가벼움, 기본값) 또는 `local`(전체 레퍼런스 내장) |
| -f, --force | 디렉터리가 비어 있지 않아도 강제로 생성 (기존 파일은 유지) |
| --clean | 스캐폴드 전에 대상의 기존 파일을 삭제 (`--force` 포함, 대상에 `.git/`이 있으면 거부) |
| --skip-agents-md | AGENTS.md 파일 생성 생략 |
| --skip-sample-content | 샘플 콘텐츠 파일 생성 생략 |
| --skip-taxonomies | 택소노미 설정과 템플릿 생략 |
| --include-multilingual LANGS | 다국어 지원 활성화 (예: `en,ko,ja`). 중복 코드는 경고와 함께 제거됩니다 |
| --minimal-config | 주석과 선택 섹션 없는 최소 `config.toml` 생성 |
| --full-config | 모든 주석과 선택 섹션을 포함한 전체 `config.toml` 생성 (탐색성 최대) |
| --list-scaffolds | 사용 가능한 내장 스캐폴드 목록 출력 후 종료 |
| -q, --quiet | 정보 출력과 배너 숨김 (오류는 stderr로 계속 출력) |
| -j, --json | 기계가 읽을 수 있는 JSON 출력: `--list-scaffolds`와 함께면 스캐폴드 목록, 그 외에는 `{"status","path","scaffold","files_created"}` 결과 |

### new

새 콘텐츠 파일을 만듭니다:

```bash
hwaro new                                     # 대화형 위저드(TTY): 모든 항목을 프롬프트로 입력
hwaro new content/about.md
hwaro new content/blog/my-post.md
hwaro new posts/my-post.md -a posts
hwaro new my-post.md --section blog --draft --tags "go,web" --date 2026-03-22
```

프론트 매터 템플릿이 채워진 마크다운 파일을 만듭니다. 커스터마이즈
가능한 템플릿인 **아키타입**을 지원합니다.

**대화형 모드:**

대화형 터미널에서 `<path>` 없이 `hwaro new`를 실행하면 안내 위저드가 열립니다.
제목, 설명, (제목과 섹션에서 만들어 낸) **추천 경로**, 태그, 날짜, 초안 여부,
아키타입을 차례로 묻고, 요약을 보여 준 뒤 확인을 받고 나서 파일을 씁니다.
이미 넘긴 플래그는 해당 프롬프트를 미리 채우므로 `hwaro new -t "My Post"`는
나머지만 묻습니다. 마지막 확인에서 `Ctrl-D`를 누르거나 `n`으로 답하면 아무것도
만들지 않고 취소합니다.

위저드는 비대화형 컨텍스트(파이프, CI, 에이전트, `--json`, `--quiet`)에서는
절대 실행되지 않고 대신 분류된 `HWARO_E_USAGE` 오류를 출력하므로, 스크립트
호출은 예측 가능하게 유지됩니다. `<path>`(그리고 필요한 플래그)를 주면
프롬프트를 완전히 건너뜁니다.

**옵션:**

| 플래그 | 설명 |
|------|-------------|
| -t, --title TITLE | 콘텐츠 제목 |
| --date DATE | 콘텐츠 날짜 (기본값: 현재, 예: `2026-03-22`) |
| --draft | 초안으로 표시 |
| --tags TAGS | 쉼표로 구분한 태그 |
| -s, --section NAME | 섹션 디렉터리 (예: `blog`, `docs`) |
| -a, --archetype NAME | 사용할 아키타입 |
| --bundle | 단일 파일 대신 리프 번들 디렉터리(`foo/index.md`) 생성 |
| --no-bundle | 단일 파일(`foo.md`) 강제; `[content.new].bundle = true`보다 우선 |
| --list-archetypes | 현재 프로젝트의 아키타입 목록 출력 후 종료 |
| --json | 기계가 읽을 수 있는 JSON 출력 (아키타입 목록과 분류된 오류) |

**아키타입:**

아키타입은 새 콘텐츠의 기본 프론트 매터를 정의하는 `archetypes/` 디렉터리의 템플릿 파일입니다:

- `archetypes/default.md` - 모든 콘텐츠의 기본 템플릿
- `archetypes/posts.md` - `hwaro new posts/...`에 사용
- `archetypes/tools/develop.md` - `hwaro new tools/develop/...`에 사용

아키타입 파일은 플레이스홀더를 지원합니다: `{{ title }}`, `{{ date }}`, `{{ draft }}`, `{{ tags }}`, `{{ description }}`

아키타입 예시 (`archetypes/posts.md`):
```
---
title: "{{ title }}"
date: {{ date }}
draft: false
tags: []
---

# {{ title }}
```

아키타입 매칭 우선순위:
1. 명시적 `-a` 플래그 (예: `-a posts`는 `archetypes/posts.md` 사용)
2. 경로 기반 매칭 (예: `posts/hello.md`는 `archetypes/posts.md` 확인)
3. 중첩 경로는 상위 아키타입을 시도 (예: `tools/dev/x.md`는 `tools/dev.md`, 그다음 `tools.md`)
4. `archetypes/default.md`로 대체
5. 아키타입이 없으면 내장 템플릿 사용

### build

사이트를 `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
```

**옵션:**

| 플래그 | 설명 |
|------|-------------|
| -i, --input DIR | 빌드할 프로젝트 디렉터리 (기본값: 현재 디렉터리) |
| -o, --output DIR | 출력 디렉터리 (기본값: public) |
| --base-url URL | `config.toml`의 `base_url`을 일시적으로 오버라이드 |
| -e, --env ENV | 환경 이름 (`config.<env>.toml` 오버라이드 로드) |
| -d, --drafts | 초안 콘텐츠 포함 |
| --include-expired | 만료된 콘텐츠 포함 |
| --include-future | 미래 날짜 콘텐츠 포함 |
| --minify | 출력 파일 압축(minify) (아래 참고) |
| --no-parallel | 병렬 처리 끄기 |
| --jobs N | 동시 렌더 워커 수. 기본값은 자동이며 사이트의 리스팅 fan-out에서 산정 (아래 참고) |
| --cache | 증분 빌드 캐시 사용 (아래 참고) |
| --full | 캐시를 비우고 전체 재빌드 강제 |
| --skip-highlighting | 구문 강조 끄기 |
| --skip-og-image | 자동 OG 이미지 생성 생략 |
| --skip-image-processing | 이미지 리사이즈와 LQIP 생성 생략 |
| --skip-cache-busting | CSS/JS 리소스의 캐시 버스팅 쿼리 파라미터 끄기 |
| --stream | 메모리 사용을 줄이는 스트리밍 빌드 사용 |
| --memory-limit SIZE | 스트리밍 빌드 메모리 제한 (예: `2G`, `512M`) |
| -v, --verbose | 상세 출력 |
| --profile | 단계별·템플릿별 빌드 시간 출력 |
| --debug | 빌드 후 디버그 정보 출력 |

**출력 디렉토리에 대해:** 전체 빌드는 빈 출력 디렉토리에서 시작하지만, hwaro는
자신이 책임질 수 있는 디렉토리만 비웁니다. 프로젝트 옆의 관례적인 `public/`,
`hwaro serve`가 쓰는 `.hwaro/serve`, 그리고 이전 빌드에서 hwaro가 직접 만들었거나
비어 있는 상태로 발견한 디렉토리입니다. 다른 파일이 이미 들어 있는 디렉토리를
`-o`로 지정하면(`-o ~/Documents/site`, 번들러와 공유하는 `dist/` 등) 그 파일들은
그대로 두고 사이트를 그 안에 씁니다. 이때 이전 빌드의 파일이 남아 있을 수 있다는
경고가 출력됩니다. 한 번 디렉토리를 비워 주면 이후부터는 hwaro가 관리합니다.
파일시스템 루트, 홈 디렉토리, 프로젝트 자체와 입력 디렉토리(`content/`,
`templates/`, `static/` 등)는 아예 거부됩니다.

**`--stream` / `--memory-limit` (스트리밍 빌드):**

페이지가 수천 개인 사이트에서는 렌더링된 HTML을 전부 메모리에 올리면 메모리 사용량이 커질 수 있습니다. 스트리밍 빌드는 Render 단계에서 페이지를 배치 단위로 처리하고, 각 배치를 디스크에 쓴 뒤 렌더링된 HTML을 해제합니다.

- `--stream`은 기본 배치 크기 500페이지로 스트리밍을 켭니다.
- `--memory-limit SIZE`는 스트리밍을 켜고 주어진 제한에 맞춰 배치 크기를 자동 계산합니다(휴리스틱: 페이지당 약 50KB). `G`, `M`, `K` 접미사를 받습니다(예: `2G`, `512M`, `256K`).
- 대체 수단으로 `HWARO_MEMORYLIMIT` 환경 변수도 설정할 수 있습니다. CLI 플래그가 환경 변수보다 우선합니다.

| `--stream` | `--memory-limit` | `HWARO_MEMORYLIMIT` | 결과 |
|---|---|---|---|
| - | - | - | 일반 빌드 |
| yes | - | - | 스트리밍, 배치=500 |
| - | 2G | - | 스트리밍, 배치≈20000 |
| - | - | 1G | 스트리밍, 배치≈10000 |
| yes | 512M | - | 스트리밍, 배치≈5000 |
| - | 2G | 1G | CLI 우선 (2G) |

빌드 결과물은 동일합니다. 스트리밍은 빌드 중 메모리 사용량에만 영향을 줍니다.

**`--minify`:**

이 플래그는 생성된 파일을 줄이되 압축 전 출력과 시각적으로 동일하게 유지합니다:

- **HTML**: 주석을 제거하고(조건부 주석, SSI 지시문, `<!-- more -->`는 보존), 줄 끝 공백을 지우고, 태그 내부 공백을 접고(속성 사이 연속 공백은 한 칸으로, 따옴표로 감싼 속성 값은 그대로), 태그 사이 공백은 이웃 요소 분류에 따라 접습니다. 어느 한쪽 이웃이라도 블록 레벨 요소면 공백을 완전히 제거합니다(블록 형제의 시작·끝·사이 공백은 어차피 브라우저가 접습니다). 양쪽 이웃이 *모두* 인라인일 때만 한 칸을 남겨 `<a>x</a> <a>y</a>`처럼 눈에 보이는 간격을 보존합니다.
- **JSON**: 공백과 줄바꿈을 제거해 압축된 출력을 만듭니다.
- **XML**: 태그 사이 공백을 제거해 파일 크기를 줄입니다.

공백에 민감한 요소(`<pre>`, `<code>`, `<textarea>`, `<script>`, `<style>`, `<svg>`, `<math>`, `<noscript>`)는 공백 처리 전에 추출했다가 그대로 복원하므로 내용을 절대 건드리지 않습니다.

더 공격적인 축소(속성 따옴표 처리, 엔티티 축약 등)가 필요하면 `html-minifier-terser`나 `minify-html` 같은 전용 도구로 `public/`을 후처리합니다.

**`--cache` (증분 빌드):**

켜면 Hwaro가 파일 수정 시각과 콘텐츠 체크섬을 프로젝트 루트의 `.hwaro_cache.json` 파일에 기록합니다. 이후 빌드에서는 지난 빌드 이후 바뀐 파일만 다시 렌더링합니다. 캐시는 템플릿과 설정 체크섬도 추적합니다. 템플릿이나 `config.toml`이 바뀌면 모든 항목이 자동으로 무효화되어 전체 페이지가 재빌드됩니다.

`--full`을 `--cache`와 함께 쓰면 깨끗하게 재빌드하면서도 다음 실행을 위한 캐시는 저장합니다:

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

자세한 내용은 [증분 빌드](/ko/features/incremental-build/)를 참고합니다.

**`--jobs` (렌더 동시성):**

기본적으로 Hwaro는 사이트의 **리스팅 fan-out**(페이지 하나를 렌더링할 때 사이트 전역 컬렉션에서 만들어내는 페이지 객체 수)을 기준으로 동시 렌더 워커 수를 정합니다. `--jobs N`은 그 값을 직접 지정합니다. 생성 결과물은 절대 바뀌지 않고, 한 번에 렌더링하는 페이지 수만 달라집니다.

유효한 병렬성의 상한을 결정하는 건 코어 수가 아니라 이 fan-out입니다. `{% for p in site.pages %}`나 `{% for p in section.pages %}` 반복은 항목마다 객체를 하나씩 할당하는데, 워커가 일정 수를 넘어가면 가비지 컬렉터의 전역 할당 락이 이 작업을 직렬화해서 추가 워커는 경합만 늘립니다. 그래서 자동 산정 값은 다음과 같습니다.

| 페이지 렌더 1회당 만들어지는 항목 수 | 워커 |
|---|---|
| 500 이상 (예: 대형 사이트에서 `page` 템플릿이 전체 페이지를 나열) | 1 |
| 100–499 | 2 |
| 100 미만 (대부분의 사이트) | 최대 4 |

전체 페이지를 나열하는 홈페이지 한 장은 여기에 걸리지 않습니다. 추정치는 렌더링되는 페이지들의 평균이라, 값싼 페이지 수천 장 사이에 비싼 리스팅 페이지가 하나 있어도 사이트는 빠른 경로에 남습니다.

```bash
hwaro build --jobs 4   # 자동 산정 값을 직접 지정
```

벤치마크 목적이 아니라면 설정하지 않는 편이 좋습니다. 저희가 측정하는 모든 코퍼스에서 자동 산정 값은 최적 고정값과 몇 % 이내입니다. `--no-parallel`과 함께 쓰면 `--jobs`는 효과가 없습니다.

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

지정하면 Hwaro가 빌드 전에 작업 디렉터리를 해당 경로로 바꿉니다. 먼저 `cd`하지 않고도 다른 디렉터리에 있는 사이트를 빌드할 수 있습니다.

- 모든 사이트 소스(`config.toml`, `content/`, `templates/`, `static/`)를 입력 디렉터리에서 읽습니다.
- **`-o` 없이:** 기본 출력 디렉터리 `public/`은 입력 디렉터리 안에 만들어집니다(즉, 그 사이트 자신의 `public/` 폴더). 이것이 자연스러운 동작입니다. `hwaro build -i ../my-site`는 `../my-site/public/`을 만듭니다.
- **`-o`와 함께:** 출력 경로는 (입력 디렉터리가 아니라) **현재 디렉터리** 기준으로 해석되므로, `hwaro build -i ../my-site -o ./dist`는 셸의 CWD에 있는 `./dist`에 출력합니다.
- `-i`를 생략하면 동작은 그대로이며 현재 디렉터리를 사용합니다.

### serve

라이브 리로드(기본 활성화)가 있는 개발 서버를 시작합니다:

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

> **serve 출력은 개발용 산출물입니다. 절대 배포하지 마세요.** `hwaro serve`는 전용 디렉터리 `.hwaro/serve/`에 빌드하고, 설정된 `output_dir`(기본 `public/`)은 전혀 건드리지 않습니다. 따라서 serve 세션이 배포 가능한 빌드를 덮어쓰는 일은 생기지 않습니다. `.hwaro/serve/`의 페이지들은 모든 링크에 개발 서버의 `base_url`(예: `http://127.0.0.1:3000`)이 박혀 있고, 디렉터리에는 `hwaro deploy`가 거부하는 `.hwaro-dev` 마커가 찍힙니다. 배포할 사이트는 `hwaro build`로 만드세요. `.hwaro/`는 알아서 버전 관리에서 빠집니다. hwaro가 디렉터리를 만들 때 자기 자신을 무시하는 `.hwaro/.gitignore`를 함께 쓰고, `hwaro init`도 출력 디렉터리·`.hwaro/`·`.hwaro_cache.json`을 포함한 프로젝트 `.gitignore`를 스캐폴드합니다.

**옵션:**

| 플래그 | 설명 |
|------|-------------|
| -i, --input DIR | 서빙할 프로젝트 디렉터리 (기본값: 현재 디렉터리) |
| -b, --bind HOST | 바인드 주소 (기본값: 127.0.0.1). IPv6 리터럴을 지원하며, 생성되는 모든 URL에서 대괄호로 감싸 표시됩니다(`-b ::1` → `http://[::1]:3000`) |
| -p, --port PORT | 포트 번호 (기본값: 3000) |
| --base-url URL | `config.toml`의 `base_url`을 일시적으로 오버라이드. URL에 경로가 있으면 개발 서버가 그 경로 아래에 사이트를 마운트합니다(아래 참고) |
| -e, --env ENV | 환경 이름 (`config.<env>.toml` 오버라이드 로드) |
| --minify | 압축된 출력 서빙 |
| --jobs N | 동시 렌더 워커 수. 기본값은 자동이며 사이트의 리스팅 fan-out에서 산정 |
| --open | 시작 후 브라우저 열기 |
| -d, --drafts | 초안 콘텐츠 포함 |
| --include-expired | 만료된 콘텐츠 포함 |
| --include-future | 미래 날짜 콘텐츠 포함 |
| -v, --verbose | 상세 출력 |
| --debug | 재빌드마다 디버그 정보 출력 |
| --access-log | HTTP 접근 로그 표시 (예: GET 요청). 각 줄에는 브라우저가 요청한 경로가 그대로 기록됩니다(개발 서버가 내부적으로 찾아가는 `/index.html`이 아니라 `/`) |
| --no-error-overlay | 브라우저 내 오류 오버레이 끄기 (기본값: 활성화) |
| --live-reload | 파일 변경 시 브라우저 라이브 리로드 켜기 (기본값: 활성화; 하위 호환용으로 유지) |
| --no-live-reload | 파일 변경 시 브라우저 라이브 리로드 끄기 |
| --header "NAME: VALUE" | 커스텀 응답 헤더 추가 (반복 가능). `config.toml`의 `[serve.headers]`와 병합 (CLI 우선). `hwaro serve`에만 적용 |
| --cache | 빌드 캐시 사용 (변경 없는 파일 생략) |
| --stream | 메모리 사용을 줄이는 스트리밍 빌드 사용 |
| --memory-limit SIZE | 스트리밍 빌드 메모리 제한 (예: `2G`, `512M`) |
| --fast-start | 홈페이지 + 최신 N개 페이지를 먼저 렌더링하고 나머지는 백그라운드에서 렌더링 |
| --fast-start-count N | `--fast-start`로 먼저 렌더링할 최근 페이지 수 (기본값: 20) |
| --skip-cache-busting | CSS/JS 리소스의 캐시 버스팅 쿼리 파라미터 끄기 |
| --skip-og-image | 자동 OG 이미지 생성 생략 |
| --skip-image-processing | 이미지 리사이즈와 LQIP 생성 생략 |
| --profile | 단계별·템플릿별 빌드 시간 출력 |

> **대규모 사이트의 빠른 개발 서버:** `config.toml`에 `[og.auto_image] lazy_generate = true`를 설정하면 `hwaro serve` 중 일괄 OG 생성을 생략합니다. 이미지는 첫 요청 시 생성됩니다. 전체 설명과 `--fast-start`를 곁들인 권장 워크플로는 [개발 서버 속도 개선](/ko/features/og-images/#개발-서버-속도-개선) 절을 참고합니다.

서버는 파일 변경을 감시해 자동으로 재빌드합니다. 무엇이 바뀌었는지에 따라 **스마트 재빌드 전략**을 사용합니다:

| 변경 유형 | 전략 | 설명 |
|-------------|----------|-------------|
| `config.toml` | 전체 재빌드 | 사이트 전체 재빌드 |
| `content/`만 | 증분 | 영향받는 콘텐츠 페이지만 재빌드 |
| `templates/`만 | 템플릿 재렌더링 | 기존 콘텐츠로 전체 페이지 재렌더링 |
| `static/`만 | 정적 복사 | 변경된 정적 파일만 복사 |
| 혼합 / 새 파일 / 삭제된 파일 | 전체 재빌드 | 사이트 전체 재빌드 |

**라이브 리로드:**

라이브 리로드는 **기본으로 켜져 있습니다**. 서버가 모든 HTML 응답에 작은 WebSocket 클라이언트 스크립트를 주입하고, 재빌드가 성공할 때마다 연결된 브라우저가 자동으로 페이지를 새로 고치므로 수동 새로 고침이 필요 없습니다. 클라이언트는 재연결에 지수 백오프(1초~30초)를 사용하므로 서버를 재시작해도 연결이 영구히 끊기지 않습니다.

이 동작을 끄려면 `--no-live-reload`를 줍니다(프로덕션과 비슷한 전달 방식을 로컬에서 테스트할 때 유용합니다). `--live-reload` 플래그는 기존 호출과의 하위 호환을 위해 아무 동작 없는 별칭으로 남아 있습니다.

`-i`를 지정하면 서버는 해당 디렉터리로 `cd`한 것처럼 동작하여 그 프로젝트 루트를 감시하고 서빙합니다.

**서브패스 미리보기 (`--base-url`에 경로 지정):**

```bash
hwaro serve --base-url http://localhost:3000/myblog/
```

사이트가 `/myblog/` 접두사가 붙은 링크로 빌드되고 같은 접두사 아래에서 서빙됩니다. 덕분에 프로젝트 페이지 배포(GitHub Pages, GitLab Pages)를 실제 게시될 모습 그대로 미리 볼 수 있습니다. 모든 링크가 로컬에서 404가 되는 홈페이지를 보는 대신에 말입니다.

- `/`는 `/myblog/`로 리디렉션됩니다.
- 접두사가 없는 요청도 그대로 해석되므로, 직접 입력한 에셋 경로가 계속 동작합니다.
- 라이브 리로드, 파일 감시, WebSocket 엔드포인트 모두 접두사 아래에서 동작합니다.

**요청 처리:**

- 서버는 `GET`, `HEAD`, `OPTIONS`에 응답합니다. 그 외 메서드는 404 페이지가 아니라 `Allow: GET, HEAD, OPTIONS` 헤더와 함께 `405 Method Not Allowed`를 반환합니다.
- 잘못된 형식의 요청 경로(예: 퍼센트 인코딩된 NUL 바이트)는 `400 Bad Request`를 반환합니다.
- `HEAD`는 대응하는 `GET`과 정확히 같은 헤더(라이브 리로드가 주입된 HTML의 `Content-Length`까지 포함)를 반환하며, 본문은 없습니다.
- 텍스트 응답(`.txt`, `.json`, `.xml`, `.js`, `.css`, `.svg`, …)은 파일 크기와 관계없이 항상 `; charset=utf-8`을 포함합니다.
- 디렉터리 리디렉션은 퍼센트 인코딩된 `Location`을 보냅니다(`/my%20page/`, `/%ED%95%9C%EA%B8%80/`). 백슬래시나 인코딩된 구분자(`%2F`, `%5C`)가 포함된 경로는 정적 호스트와 동일하게 서빙하지 않습니다.

**커스텀 응답 헤더 (`--header` / `[serve.headers]`):**

프로덕션 리버스 프록시, CDN, 정적 호스팅이 설정하는 헤더(보안 헤더, `Cache-Control`, 커스텀 CORS 등)를 재현해, 정적 출력을 배포하기 전에 로컬에서 테스트하는 용도입니다.

```toml
[serve.headers]
X-Frame-Options = "SAMEORIGIN"
X-Content-Type-Options = "nosniff"
Referrer-Policy = "strict-origin-when-cross-origin"
# Cache-Control = "public, max-age=3600"
```

```bash
hwaro serve --header "X-Custom: foo" --header "Cache-Control: no-store"
```

- CLI `--header` 값이 `config.toml`의 같은 키보다 우선합니다.
- 헤더는 **모든** 개발 서버 응답(HTML, 에셋, 404, 리디렉션, 라이브 리로드가 주입된 페이지, CORS 프리플라이트(`OPTIONS`) 응답)에 붙습니다.
- 이 기능은 `hwaro serve`에만 적용됩니다. 빌드가 디스크에 쓰는 파일은 그대로입니다.

### deploy

생성된 사이트를 설정된 대상에 배포합니다.

```bash
hwaro deploy [target ...]
hwaro deploy --target prod
hwaro deploy --dry-run
```

**옵션:**

| 플래그 | 설명 |
|------|-------------|
| -s, --source DIR | 배포할 소스 디렉터리 (기본값: deployment.source_dir 또는 public) |
| -t, --target NAME | 배포 대상 이름 (반복 지정 가능, 위치 인자와 동일) |
| --dry-run | 실제로 쓰지 않고 계획된 변경만 표시 |
| --confirm | 배포 전 확인 요청 |
| --force | 강제 업로드/복사 (파일 비교 무시). 빈 소스로 대상을 비우는 것도 허용 |
| --max-deletes N | 최대 삭제 수 (기본값: deployment.maxDeletes 또는 256, -1이면 제한 없음) |
| --list-targets | 설정된 배포 대상 목록 출력 후 종료 |
| --json | 기계가 읽을 수 있는 JSON 출력 (`--dry-run`이면 계획, 아니면 대상별 요약, `--list-targets`면 대상 목록) |
| -e, --env NAME | 불러올 설정 환경 (`HWARO_ENV`로도 지정) |
| -q, --quiet | 사람이 읽는 로그 출력 억제 |

**안전 규칙.** `deploy`는 정합성을 맞출 수 없는 대상을 파괴하는 대신 거부합니다.

- 소스 디렉터리가 비어 있거나 `include`/`exclude`가 아무 파일도 고르지 못하면
  대상을 지우지 않고 중단합니다. 먼저 `hwaro build`를 실행하거나, 의도적으로
  비우려면 `--force`를 넘기세요. `{source}`를 쓰지 않는 `command` 타깃은 소스를
  읽지 않으므로 이 검사에서 제외됩니다.
- `--max-deletes`는 삭제 단계를 제한합니다(기본 256, 음수면 해제). 내장
  `file://` 동기화에만 적용되며, 커맨드 대상이 자체적으로 쓰는 `--delete`는
  제한하지 않습니다.
- 대상에 있는 심볼릭 링크를 **따라가서** 쓰거나 지우지 않습니다. 파일이나
  디렉터리가 있어야 할 자리의 링크는 교체하고, 오래된 링크는 가리키는 대상을
  건드리지 않은 채 링크만 제거합니다.
- `--json`은 비대화형입니다. `--confirm`과 함께 쓰면 JSON 문서에 프롬프트를
  섞어 넣는 대신 오류로 실패합니다.

### doctor

설정, 템플릿, 구조 문제를 진단합니다 (최상위 단축 명령):

```bash
hwaro doctor               # 설정, 템플릿, 구조 문제 진단
hwaro doctor --fix         # 설정 값 정규화 (base_url 끝 슬래시, sitemap priority…)
hwaro doctor --approve     # 권장 설정 섹션을 config.toml에 추가
hwaro doctor --full        # 둘 다 (--fix --approve와 동일)
```

**종료 코드.** `doctor`는 보고된 가장 심각한 문제를 기준으로 분류된
종료 코드를 반환하므로, CI 파이프라인이 이 값으로 바로 게이트를 걸 수
있습니다:

| 결과 | 종료 코드 |
|---|---|
| 문제 없음, 경고만, 또는 info 수준 발견 | `0` |
| 설정 오류 (`config.toml` 누락/손상) | `3` (`HWARO_E_CONFIG`) |
| 템플릿 오류 (필수 파일 누락, 닫히지 않은 태그) | `4` (`HWARO_E_TEMPLATE`) |
| 콘텐츠 오류 (잘못된 프론트 매터, 해당 검사가 도입되면) | `5` (`HWARO_E_CONTENT`) |
| 그 외 error 수준 문제 | `1` |

경고(빈 `base_url`, 끝 슬래시, 중복 택소노미 이름 등)는 참고용이며
종료 코드를 바꾸지 않습니다.

콘텐츠 검증에는 `hwaro tool validate`를 사용합니다. 자세한 내용은 [doctor](/ko/start/tools/doctor/)를 참고합니다.

### tool

콘텐츠 관리를 위한 유틸리티 도구:

```bash
# 콘텐츠 도구
hwaro tool list all             # 전체 콘텐츠 파일 목록
hwaro tool list drafts          # 초안 파일 목록
hwaro tool convert to-yaml      # 프론트 매터를 YAML로 변환
hwaro tool convert to-toml      # 프론트 매터를 TOML로 변환
hwaro tool convert to-json      # 프론트 매터를 JSON으로 변환
hwaro tool check-links          # 죽은 외부 링크 검사
hwaro tool stats                # 콘텐츠 통계 표시
hwaro tool validate             # 콘텐츠 프론트 매터와 마크업 검증
hwaro tool unused-assets        # 참조되지 않는 정적 파일 찾기

# 사이트 도구
hwaro tool platform netlify       # Netlify 설정 생성
hwaro tool platform vercel        # Vercel 설정 생성
hwaro tool platform cloudflare    # Cloudflare Pages 설정 생성
hwaro tool platform github-pages  # GitHub Pages 배포 워크플로 생성
hwaro tool platform gitlab-ci     # GitLab CI 설정 생성
hwaro tool platform codeberg-pages # Codeberg Pages(Forgejo Actions) 워크플로 생성
hwaro tool doctor                 # 설정/템플릿/구조 문제 진단
hwaro tool import hugo /path      # Hugo에서 가져오기
hwaro tool import jekyll /path    # Jekyll에서 가져오기
hwaro tool export hugo            # Hugo 형식으로 내보내기
hwaro tool export jekyll          # Jekyll 형식으로 내보내기
hwaro tool agents-md --write      # AGENTS.md를 파일로 쓰기

# JSON 출력
hwaro tool list all --json
hwaro tool convert to-yaml --json
hwaro tool stats --json
hwaro tool validate --json
hwaro tool unused-assets --json
hwaro tool doctor --json
hwaro tool check-links --json
hwaro tool import jekyll /path --json
hwaro tool export hugo --json

# 파괴적/대량 작업을 쓰기 없이 미리보기
hwaro tool convert to-yaml --dry-run
hwaro tool import jekyll /path --dry-run
hwaro tool export hugo --dry-run
```

`list`와 `convert` 명령은 사용법에 표시된 위치 인자만 받습니다.
`check-links`, `stats`, `validate`, `unused-assets`는 위치 인자를 받지 않습니다.
`--` 뒤의 인자를 포함한 추가 위치 인자는 사용법 오류로 거부되므로, 경로나
다른 옵션에는 문서에 나온 플래그를 사용하세요.

**서브커맨드:**

| 분류 | 서브커맨드 | 설명 |
|----------|------------|-------------|
| 콘텐츠 | [list](/ko/start/tools/list/) | 상태별 콘텐츠 파일 목록 (all, drafts, published) |
| 콘텐츠 | [convert](/ko/start/tools/convert/) | 프론트 매터를 TOML, YAML, JSON 형식 간 변환 |
| 콘텐츠 | [check-links](/ko/start/tools/check-links/) | 콘텐츠 파일의 죽은 링크 검사 |
| 콘텐츠 | [stats](/ko/start/tools/stats/) | 콘텐츠 통계 표시 |
| 콘텐츠 | [validate](/ko/start/tools/validate/) | 콘텐츠 프론트 매터와 마크업 검증 |
| 콘텐츠 | [unused-assets](/ko/start/tools/unused-assets/) | 참조되지 않는 정적 파일 찾기 |
| 사이트 | [platform](/ko/start/tools/platform/) | 플랫폼 설정과 CI/CD 워크플로 파일 생성 |
| 사이트 | [doctor](/ko/start/tools/doctor/) | 설정, 템플릿, 구조 문제 진단 |
| 사이트 | import | WordPress, Jekyll, Hugo, Notion, Obsidian, Hexo, Astro, Eleventy에서 콘텐츠 가져오기 |
| 사이트 | [export](/ko/start/tools/export/) | 콘텐츠를 Hugo 또는 Jekyll로 내보내기 |
| 사이트 | [agents-md](/ko/start/tools/agents-md/) | AGENTS.md 파일 생성 또는 갱신 |

**공통 옵션:**

| 플래그 | 설명 |
|------|-------------|
| -c, --content-dir DIR | 특정 콘텐츠 디렉터리로 제한 |
| -j, --json | 결과를 JSON으로 출력 |
| -h, --help | 도움말 표시 |

자세한 사용법은 [도구와 자동 완성](/ko/start/tools/)을 참고합니다.

### completion

셸 자동 완성 스크립트를 생성합니다:

```bash
hwaro completion bash    # Bash 자동 완성 스크립트
hwaro completion zsh     # Zsh 자동 완성 스크립트
hwaro completion fish    # Fish 자동 완성 스크립트
```

**설치:**

```bash
# Bash (~/.bashrc에 추가)
eval "$(hwaro completion bash)"

# Zsh (~/.zshrc에 추가)
eval "$(hwaro completion zsh)"

# Fish (~/.config/fish/config.fish에 추가)
hwaro completion fish | source
```

자세한 설치 방법은 [도구와 자동 완성](/ko/start/tools/)을 참고합니다.

## 예시

```bash
# 개발 워크플로
hwaro serve --drafts --verbose

# HTTP 접근 로그를 켠 개발
hwaro serve --access-log

# 라이브 리로드 없는 개발 (프로덕션과 비슷한 서빙)
hwaro serve --no-live-reload

# 프로덕션 빌드
hwaro build

# 커스텀 출력 디렉터리
hwaro build -o dist

# 특정 포트에서 미리 보기
hwaro serve -p 8000 --open

# 다른 디렉터리의 사이트 빌드
hwaro build -i ~/projects/my-blog

# 다른 위치의 프로젝트를 빌드해 현재 디렉터리에 출력
hwaro build -i ~/projects/my-blog -o ./output

# 증분 빌드 (변경 없는 파일 생략)
hwaro build --cache

# 전체 재빌드 강제 + 캐시 재생성
hwaro build --cache --full

# 대규모 사이트용 스트리밍 빌드
hwaro build --stream
hwaro build --memory-limit 512M

# 환경 변수로 스트리밍 빌드
HWARO_MEMORYLIMIT=1G hwaro build

# 다른 디렉터리의 사이트 서빙
hwaro serve -i ~/projects/my-blog --open
```

## 전역 옵션

| 플래그 | 설명 |
|------|-------------|
| -h, --help | 도움말 표시 |
| -v, --verbose | 상세 출력 |

## 함께 보기

- [설정](/ko/start/config/) — CLI 플래그가 오버라이드하는 설정 옵션
- [빌드 훅](/ko/features/build-hooks/) — 빌드 전/후 명령
- [도구와 자동 완성](/ko/start/tools/) — 유틸리티 서브커맨드

---

Title: 설정
URL: https://hwaro.hahwul.com/ko/start/config/
Source: content/start/config.ko.md
Language: ko

모든 사이트 설정은 프로젝트 루트의 `config.toml`에 있습니다.

최상위 키에 오타가 있으면 조용히 무시하지 않고 경고합니다. `[markdonw]`나
`titel = "…"` 같은 오타는 아무 안내 없이 기능을 꺼버리기 때문입니다. 실제
키와 비슷하면 다음처럼 후보를 함께 알려줍니다.

```
Unknown key 'markdonw' in config.toml — hwaro does not read it. Did you mean 'markdown'?
```

이 검사는 최상위 키만 대상으로 하며, 섹션 안에 중첩된 키는 각 섹션의
로더가 검증합니다.

## 사이트 설정

```toml
title = "My Site"
description = "Site description for SEO"
base_url = "https://example.com"
```

| 키 | 타입 | 설명 |
|-----|------|-------------|
| title | string | 사이트 제목 |
| description | string | 사이트 설명 |
| base_url | string | 프로덕션 URL (끝 슬래시 없음) |

## 환경 변수

`config.toml`에서 환경 변수를 참조할 수 있습니다. 값은 TOML 파싱 전에 치환됩니다.

```toml
base_url = "${SITE_URL}"
title = "$SITE_TITLE"
description = "${SITE_DESC:-My awesome site}"
```

| 문법 | 설명 |
|--------|-------------|
| `${VAR}` | 환경 변수 값으로 치환 |
| `$VAR` | 위와 동일 (축약형) |
| `${VAR:-default}` | `VAR`가 없거나 비어 있으면 `default` 사용 |

기본값 없이 누락된 변수는 그대로 남고 빌드 경고가 발생합니다. 템플릿에서의 사용법은 [환경 변수](/ko/features/env-variables/)를 참고합니다.

## 빌드 옵션

```toml
[build]
output_dir = "public"
drafts = false
parallel = true
cache = false
hooks.pre = ["npm install", "npx tsc"]
hooks.post = ["npm run minify"]
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| output_dir | string | "public" | 출력 디렉터리 |
| drafts | bool | false | 초안 콘텐츠 포함 |
| parallel | bool | true | 병렬 처리 |
| cache | bool | false | 빌드 캐시 사용 |
| template_deps | bool | true | 템플릿 의존성을 추적해 템플릿 편집 시 해당 템플릿을 렌더링하는 페이지만 재빌드 |
| hooks.pre | array | [] | 빌드 전에 실행할 명령 |
| hooks.post | array | [] | 빌드 후에 실행할 명령 |

`output_dir`, `drafts`, `parallel`, `cache`는 각각 `hwaro build` 플래그에 대응하며, 플래그가 우선합니다.

```
명령줄 플래그  >  config.toml  >  기본값
```

즉 `hwaro build -o dist`는 config의 `output_dir`를 덮어쓰고, `drafts = false`여도 `hwaro build --drafts`를 쓰면 초안이 포함됩니다. 반대 방향은 없습니다. config 값을 다시 끄는 `--no-drafts`나 `--no-cache`는 존재하지 않으므로, 모든 빌드에 항상 적용할 때만 이 키들을 켜세요. `--no-parallel`만 예외로, `parallel = true`를 덮어씁니다.

이 설정들은 `hwaro serve`에도 적용됩니다. serve는 `output_dir`로 빌드하고 그 디렉터리를 서빙합니다. `hwaro deploy`도 이를 따릅니다. `[deployment] source_dir`가 설정되지 않았다면 `public`을 가정하지 않고 `output_dir`를 배포합니다.

`output_dir`에는 프로젝트 상대 경로와 절대 경로를 모두 쓸 수 있습니다. 프로젝트 밖으로 벗어나는 경로(`../out`)는 거부됩니다. 개발 서버가 프로젝트 밖에서는 서빙하지 않기 때문에, 그대로 두면 빌드는 serve가 읽지 않는 곳에 결과를 쓰게 됩니다.

오류 처리와 활용 사례는 [빌드 훅](/ko/features/build-hooks/)을 참고합니다.

## 마크다운

```toml
[markdown]
safe = false
lazy_loading = false
emoji = false
footnotes = true
task_lists = true
definition_lists = true
mermaid = false
math = false
math_engine = "katex"
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| safe | bool | false | 마크다운의 원시 HTML 제거 |
| lazy_loading | bool | false | 이미지에 `loading="lazy"` 자동 추가 |
| emoji | bool | false | 이모지 숏코드(예: `:smile:`)를 이모지 문자로 변환 |
| footnotes | bool | true | 각주 문법(`[^1]`) 사용 |
| task_lists | bool | true | 작업 목록 문법(`- [ ]` / `- [x]`) 사용 |
| task_list_classes | bool | false | 작업 목록 마크업에 GFM 클래스(`task-list-item`, `contains-task-list`) 추가 |
| definition_lists | bool | true | 정의 목록 문법(`Term\n: Definition`) 사용 |
| mermaid | bool | false | ` ```mermaid ` 블록을 `<div class="mermaid">`로 렌더링 |
| math | bool | false | 수식 문법(`$...$`, `$$...$$`) 사용 |
| math_engine | string | "katex" | 수식 렌더링 엔진 (`"katex"` 또는 `"mathjax"`) |
| smart_punctuation | bool | false | 타이포그래피용 인용부호/대시/줄임표 (`"x"` → “x”, `--` → –, `...` → …) |
| containers | bool | false | `:::note Title` … `:::` 커스텀 컨테이너 (admonition 마크업) |
| insert_anchor_links | string | "none" | 사이트 전역 헤딩 앵커 링크: `"none"`, `"left"`, `"right"` (페이지 프론트 매터가 우선) |
| external_links_target_blank | bool | false | 절대 http(s) 링크에 `target="_blank" rel="noopener"` 추가 |
| external_links_no_follow | bool | false | 절대 http(s) 링크에 `rel="nofollow"` 추가 |
| external_links_no_referrer | bool | false | 절대 http(s) 링크에 `rel="noreferrer"` 추가 |

문법 상세와 예시는 [마크다운 확장](/ko/features/markdown-extensions/)을 참고합니다.

## 콘텐츠

```toml
[content]
summary_length = 70
summary_ellipsis = "…"
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| summary_length | int | 70 | `<!-- more -->`도 `description`도 없는 페이지의 자동 요약 길이. 공백으로 구분되는 텍스트는 단어 수, CJK 위주 텍스트는 글자 수 ×2. `0`이면 자동 요약 비활성화 |
| summary_ellipsis | string | "…" | 자동 요약이 잘린 경우에만 끝에 추가되는 문자열 |

`page.summary`가 선택되는 방식은 [콘텐츠 요약](/ko/writing/pages/#콘텐츠-요약)을 참고하세요. `[content.files]`, `[content.new]`, `[[content.generate]]`는 아래 기능 설정 레퍼런스에 있습니다.

## 퍼머링크

콘텐츠 디렉터리 경로를 다른 URL 경로로 다시 씁니다. 링크를 깨뜨리지 않고 사이트 구조를 바꿀 때 유용합니다.

```toml
[permalinks]
"old/posts" = "posts"
"2023/drafts" = "archive/2023"
```

| 원본 (디렉터리) | 대상 (URL 경로) | 적용 예 |
|-------------------|-------------------|----------------|
| `content/old/posts/a.md` | `posts/` | `/old/posts/a/` -> `/posts/a/` |

규칙은 선언 순서대로 평가되고, 페이지의 디렉터리와 (정확히 또는 상위 접두사로) **처음** 일치하는 원본이 선택됩니다. 그 페이지에 대해 이후 규칙은 아예 확인하지 않습니다. 구체적인 접두사를 넓은 접두사보다 먼저 선언합니다(`"posts/tech"`를 `"posts"`보다 앞에). 그러지 않으면 넓은 규칙이 구체적인 규칙을 가립니다. 토큰 패턴에도 똑같이 적용되며, 특히 `""` catch-all 규칙은 다른 모든 규칙 **뒤에**, 맨 마지막에 둡니다.

### 토큰 패턴

`:token` 세그먼트가 들어간 대상은 Hugo 스타일 패턴으로, 디렉터리를 다시 매핑하는 대신 URL 전체를 새로 만듭니다:

```toml
[permalinks]
"posts" = "/:year/:month/:day/:slug/"
```

`content/posts/hello.md`의 날짜가 `2026-03-05`라면 페이지는 `/2026/03/05/hello/`에 게시됩니다.

| 토큰 | 확장 결과 |
|-------|------------|
| `:year` | 페이지 날짜의 연도 (`2026`) |
| `:month` | 페이지 날짜의 월, 0 채움 (`03`) |
| `:day` | 페이지 날짜의 일, 0 채움 (`05`) |
| `:slug` | 프론트 매터 `slug`, 없으면 파일명 스템 |
| `:title` | 슬러그화한 프론트 매터 `title` (슬러그화 결과가 비면 `:slug`로 대체) |
| `:section` | 페이지의 섹션 경로 (`posts/tech`); 루트 페이지는 비어 있어 세그먼트가 사라짐 |
| `:filename` | 파일명 스템, `slug` 오버라이드 무시 |

참고:

- 토큰은 경로 세그먼트 전체여야 하며, 알 수 없는 토큰은 설정 로드를 실패시킵니다.
- 패턴은 리프 페이지에만 적용됩니다. 섹션 `_index`와 번들 `index` 페이지는 패턴 규칙을 건너뜁니다(디렉터리 URL을 유지하거나, 뒤에 오는 일반 재매핑 규칙을 따릅니다).
- `date`가 없는 페이지가 `:year`/`:month`/`:day`를 쓰는 패턴에 걸리면 빌드가 실패합니다. 날짜를 넣거나, 프론트 매터에 명시적 `path`를 설정하거나, 날짜 토큰을 뺍니다. 게시되지 않는 페이지는 예외입니다: 초안(`--drafts` 없이), 만료/미래 날짜 페이지, 헤드리스 `render: false` 페이지는 빌드를 막지 않습니다.
- 프론트 매터의 명시적 `path`는 어떤 퍼머링크 규칙보다 항상 우선합니다.
- 원본 키가 비어 있으면(`""` 또는 `"/"`) 패턴 규칙이 모든 페이지의 catch-all이 됩니다. 처음 일치하는 규칙이 이기므로 뒤의 규칙을 전부 가리게 되니 반드시 마지막에 선언합니다.
- 기본 언어가 아닌 언어에서는 `/lang/` 접두사가 먼저 옵니다: `/ko/2026/03/05/hello/`.

## 링크

빌드 중 해석되지 않는 `@/path.md` 내부 링크를 어떻게 처리할지 제어합니다.

```toml
[links]
broken_internal = "error"
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| broken_internal | string | "warn" | `"warn"`은 해석되지 않은 `@/` 링크를 하나씩 로그로 남기고 원본 마크업을 유지; `"error"`는 위반 전체를 하나의 목록으로 모아 빌드를 실패시킴 (종료 코드 5) |

`@/` 링크 문법과 strict 모드의 `--cache` 주의 사항은 [페이지](/ko/writing/pages/#내부-링크)를 참고합니다.

## 택소노미

```toml
[[taxonomies]]
name = "tags"
feed = true
paginate_by = 10

[[taxonomies]]
name = "categories"
feed = true
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| name | string | — | 택소노미 이름 (프론트 매터에서 사용) |
| feed | bool | false | 택소노미 항목마다 RSS 피드 생성 |
| sitemap | bool | true | 택소노미 페이지를 사이트맵에 포함 |
| paginate_by | int | — | 택소노미 항목 페이지의 페이지당 글 수 |
| sort_by | string | "date" | 항목 안 페이지 정렬 기준: `"date"`(최신순), `"title"`, `"weight"` |
| reverse | bool | false | `sort_by`가 만든 순서를 뒤집음 |
| terms_sort_by | string | "name" | 택소노미 인덱스의 항목 목록 정렬: `"name"` 또는 `"count"` |

항목 피드는 `sort_by`와 무관하게 항상 최신순을 유지합니다. 전체 정렬
규칙은 [택소노미](/ko/writing/taxonomies/#정렬)를 참고합니다.

## 메뉴

이름을 붙인 내비게이션 메뉴로, 템플릿에서 `site.menus` / `get_menu()`로 렌더링합니다.

```toml
[[menus.main]]
name = "Posts"
url = "/posts/"
weight = 1

[[menus.main]]
name = "About"
url = "/about/"
weight = 2
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| name | string | — | **필수.** 없으면 경고와 함께 항목을 건너뜀 |
| url | string | "" | 루트 상대 경로 또는 절대 `http(s)://`/`//` URL |
| weight | int | 0 | 메뉴 내 정렬 순서 |
| identifier | string | `name` | 다른 항목이 `parent`로 참조하는 고유 키 |
| parent | string | none | 다른 항목의 `identifier` 아래에 이 항목을 중첩 |

페이지/섹션은 이 파일을 건드리지 않고도 자기 프론트 매터(`menus = ["main"]`)로 메뉴에 참여할 수 있습니다. 메뉴 테이블이 없는 `[languages.<code>]` 블록은 이 전역 메뉴를 상속하고, `[[languages.<code>.menus.<name>]]`을 선언하면 그 언어에서는 전역 메뉴를 대체합니다. 전체 레퍼런스(계층 구조, 언어별 동작, `active_path` 스타일링)는 [메뉴](/ko/features/menus/)를 참고합니다.

## 정적 파일

`static/` 아래의 모든 것은 디렉터리 구조를 유지한 채 사이트 루트로 그대로 복사되므로 `static/css/app.css`는 `/css/app.css`로 서빙됩니다. 숨김 항목도 포함되므로 `static/.well-known/security.txt`는 `/.well-known/security.txt`로 게시됩니다. 기본적으로 Hwaro는 흔한 OS·에디터·VCS 잔여 파일을 걸러내 프로덕션에 실려 가지 않게 합니다.

```toml
[static]
use_default_excludes = true              # 내장 잔여 파일 필터 (기본값)
exclude = ["*.bak", "drafts/**"]         # 추가로 건너뛸 패턴
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| use_default_excludes | bool | true | 내장 잔여 파일 차단 목록 필터링 (`.DS_Store`, `Thumbs.db`, `desktop.ini`, `.git`, vim 스왑 파일, …) |
| exclude | array | [] | 추가로 건너뛸 패턴. `*.bak` 같은 글롭은 모든 깊이에서 매칭, `drafts/**`는 하위 트리로 한정, 리터럴 이름은 정확한 파일이나 디렉터리에 고정 (`drafts`는 `drafts/…`를 제외) |

내장 차단 목록은 잔여 파일만 제거합니다. `.well-known/`, `.domains` 같은 정상적인 점(dot) 경로는 **절대** 걸러지지 않고 항상 게시되며, 콜드 빌드와 `--cache`/증분 빌드에서 동일하게 동작합니다. 내장 필터링을 완전히 끄려면 `use_default_excludes = false`로 설정합니다.

## 개발 서버

`hwaro serve`에만 적용되는 옵션입니다. `hwaro build` 출력에는 영향을 주지 않습니다.

```toml
[serve]
fast = true                          # 항상 빠른 개발 모드로 서빙

[serve.headers]
X-Frame-Options = "SAMEORIGIN"
Cache-Control = "no-store"
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| fast | bool | false | `--fast`를 준 것처럼 서빙 (OG 이미지 생성과 이미지 처리 생략); 명시적 CLI skip 플래그는 그대로 적용 |
| headers | table | {} | 모든 개발 서버 응답에 추가하는 커스텀 HTTP 응답 헤더; 키가 겹치면 CLI `--header` 값이 우선 |

대응하는 CLI 플래그는 [CLI](/ko/start/cli/#serve)의 serve 명령을 참고합니다.

## 기능 설정 레퍼런스

기능마다 전체 설정을 다루는 별도 문서가 있습니다. 아래는 `config.toml`의 모든 섹션을 정리한 빠른 레퍼런스입니다.

| 설정 섹션 | 문서 | 설명 |
|----------------|---------------|-------------|
| `[feeds]` | [SEO](/ko/features/seo/) | RSS/Atom 피드 생성 |
| `[sitemap]` | [SEO](/ko/features/seo/) | 사이트맵 XML 생성 |
| `[robots]` | [SEO](/ko/features/seo/) | robots.txt 생성 |
| `[og]` | [SEO](/ko/features/seo/) | OpenGraph & Twitter Card 메타 태그 |
| `[og.auto_image]` | [자동 OG 이미지](/ko/features/og-images/) | OG 미리보기 이미지 자동 생성 (빠른 개발 서버용 `lazy_generate` 포함) |
| `[search]` | [검색](/ko/features/search/) | 클라이언트 사이드 검색 인덱스 |
| `[highlight]` | [구문 강조](/ko/features/syntax-highlighting/) | 코드 구문 강조 |
| `[pagination]` | [페이지네이션](/ko/features/pagination/) | 섹션 페이지네이션 |
| `[auto_includes]` | [자동 인클루드](/ko/features/auto-includes/) | CSS/JS 파일 자동 인클루드 |
| `[assets]` | [에셋 파이프라인](/ko/features/asset-pipeline/) | CSS/JS 압축(minify) & 핑거프린팅 |
| `[sass]` | [Sass/SCSS](/ko/features/sass/) | 내장 SCSS 컴파일 (순수 Crystal) |
| `[image_processing]` | [이미지 처리](/ko/features/image-processing/) | 이미지 리사이즈 & LQIP |
| `[image_processing.lqip]` | [이미지 처리](/ko/features/image-processing/#lqip-저화질-이미지-플레이스홀더) | Base64 블러업 플레이스홀더 |
| `[content.files]` | [콘텐츠 파일](/ko/features/content-files/) | 마크다운이 아닌 파일 게시 |
| `[[content.generate]]` | [콘텐츠 생성](/ko/features/content-generation/) | `site.data` 레코드를 페이지로 구체화 |
| `[[data.remote]]` | [원격 데이터 소스](/ko/features/remote-data/) | 빌드 시 원격 데이터를 `site.data`로 가져오기 |
| `[static]` | [정적 파일](#정적-파일) | `static/` 복사에서 잔여 파일 필터링 / 경로 제외 |
| `[serve]` | [개발 서버](#개발-서버) | 개발 서버 응답 헤더 & 빠른 모드 |
| `[links]` | [링크](#링크) | 깨진 내부 `@/` 링크 처리 (경고 또는 빌드 실패) |
| `[series]` | [시리즈](/ko/features/series/) | 글을 순서 있는 시리즈로 묶기 |
| `[related]` | [관련 글](/ko/features/related-posts/) | 관련 콘텐츠 추천 |
| `[git]` | [Git 메타데이터](/ko/features/git-info/) | `page.git` 커밋 정보와 이력 기반 `updated`/`date` 폴백 |
| `[llms]` | [LLMs.txt](/ko/features/llms-txt/) | AI/LLM 크롤러 안내 |
| `[pwa]` | [PWA](/ko/features/pwa/) | 프로그레시브 웹 앱 지원 |
| `[amp]` | [AMP](/ko/features/amp/) | Accelerated Mobile Pages |
| `[deployment]` | [배포](/ko/deploy/) | 배포 대상 설정 |
| `[doctor]` | [doctor](/ko/start/tools/doctor/) | 알려진 진단 이슈 숨기기 |
| `languages.*` | [다국어](/ko/features/multilingual/) | 다국어 지원 |
| `[versions]` / `[[versions.list]]` | [버전별 문서](/ko/features/versioned-docs/) | 여러 문서 버전을 나란히 게시 |
| `[[menus.*]]` | [메뉴](/ko/features/menus/) | 이름을 붙인 내비게이션 메뉴 |

## 플러그인

```toml
[plugins]
processors = ["markdown"]
```

## 전체 예시

핵심 섹션을 모두 담은 완전한 `config.toml`입니다. 복사해서 필요에 맞게 고치면 됩니다.

```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"
"posts" = "/:year/:month/:day/:slug/"

[plugins]
processors = ["markdown"]

[[taxonomies]]
name = "tags"
feed = true

[[taxonomies]]
name = "categories"

[[menus.main]]
name = "Posts"
url = "/posts/"

# 기능 섹션 — 위 기능 설정 레퍼런스 참고
# [feeds], [sitemap], [robots], [og], [search], [highlight],
# [pagination], [auto_includes], [assets], [sass], [image_processing],
# [series], [related], [git], [llms], [pwa], [amp], [deployment], etc.
```

## 함께 보기

- [CLI](/ko/start/cli/) — 설정을 오버라이드하는 명령줄 옵션
- [환경별 설정](/ko/features/env-config/) — 환경별 오버라이드 (`config.production.toml`)

---

Title: 첫 사이트 만들기
URL: https://hwaro.hahwul.com/ko/start/first-site/
Source: content/start/first-site.ko.md
Language: ko

5분 만에 첫 Hwaro 사이트를 만듭니다.

## 1. 프로젝트 생성

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

내장 스캐폴드:

| 스캐폴드 | 설명 |
|----------|-------------|
| `simple` | 랜딩 페이지, 소규모 사이트 (기본값) |
| `bare` | 시맨틱 HTML만 있는 최소 구조 |
| `blog` | 태그, 읽기 시간, 이전/다음 글 이동이 있는 포스트 |
| `docs` | 사이드바와 이전/다음 페이지 이동이 있는 문서 |
| `book` | 챕터, 이전/다음 이동, 키보드 단축키가 있는 책 |

모든 스캐폴드는 CSS `light-dark()` 쌍 위에 만든 하나의 디자인 토큰 시스템을
공유하므로, 별도 설정 없이 읽는 사람의 OS 색상 모드(라이트/다크)를 그대로 따라갑니다. 스타일이 있는 스캐폴드에는 헤더에 테마 전환
버튼도 들어 있습니다. auto → light → dark 순으로 순환하고, 선택을
`localStorage`에 저장하며, 첫 페인트 전에 적용하기 때문에 화면이 번쩍이지
않습니다. 한 가지 모드로 고정하려면(다크 전용 사이트 등) 생성된
`css/style.css` 끝에 `:root { color-scheme: dark; }`를 추가합니다.

스캐폴드에는 몇 가지 모던한 요소도 들어 있습니다. 반투명 고정 헤더, 페이지
사이의 네이티브 크로스 문서 뷰 전환, 그리고 (블로그 글과 책 페이지의) CSS
전용 읽기 진행 표시선입니다. 모두 구형 브라우저에서는 자연스럽게 꺼지고,
모든 애니메이션은 `prefers-reduced-motion`을 존중합니다.

{% preview_gallery() %}
<a class="preview-item" href="/images/scaffolds/scaffold-simple.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-simple.png" alt="simple 스캐폴드" width="1280" height="800" loading="lazy"><div class="preview-label"><code>simple</code> — 랜딩 페이지, 소규모 사이트</div></a>
<a class="preview-item" href="/images/scaffolds/scaffold-bare.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-bare.png" alt="bare 스캐폴드" width="1280" height="800" loading="lazy"><div class="preview-label"><code>bare</code> — 시맨틱 HTML만 있는 최소 구조</div></a>
<a class="preview-item" href="/images/scaffolds/scaffold-blog.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-blog.png" alt="blog 스캐폴드" width="1280" height="800" loading="lazy"><div class="preview-label"><code>blog</code> — 태그와 카테고리가 있는 포스트</div></a>
<a class="preview-item" href="/images/scaffolds/scaffold-docs.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-docs.png" alt="docs 스캐폴드" width="1280" height="800" loading="lazy"><div class="preview-label"><code>docs</code> — 사이드바가 있는 문서</div></a>
<a class="preview-item" href="/images/scaffolds/scaffold-book.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-book.png" alt="book 스캐폴드" width="1280" height="800" loading="lazy"><div class="preview-label"><code>book</code> — 챕터가 있는 책</div></a>
{% end %}

> **팁:** 더 완성된 출발점이 필요하면 바로 쓸 수 있는 보일러플레이트 모음인 [Hwaro Examples](https://examples.hwaro.hahwul.com/)를 살펴보세요.

## 2. 개발 서버 시작

```bash
hwaro serve
```

`http://localhost:3000`을 엽니다. 변경 사항은 자동으로 다시 로드됩니다.

## 3. 프로젝트 구조

```
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)
├── data/            # 선택: site.data로 노출되는 JSON/YAML/TOML/CSV
└── public/          # Generated output
```

### 파일을 어디에 둘까

두 가지만 기억하면 됩니다.

**`data/`는 프로젝트 루트에 둡니다.** `content/` 안이 아니라 `config.toml` 옆입니다. 이 디렉터리의 파일은 자동으로 로드되고 파일 이름이 키가 되므로, `data/team.json`은 어느 템플릿에서든 `site.data.team`으로 쓸 수 있습니다.

```jinja
{% for member in site.data.team %}
  <li>{{ member.name }}</li>
{% endfor %}
```

하위 디렉터리는 중첩됩니다(`data/users/alice.yml` → `site.data.users.alice`). `hwaro init`은 이 디렉터리를 만들지 않으니 필요할 때 직접 추가하세요. 자세한 규칙은 [데이터 모델](/ko/templates/data-model/)을 참고하세요.

**이미지 같은 정적 파일은 `static/`에 둡니다.** `static/images/photo.jpg`는 출력물에서 `/images/photo.jpg`로 복사되므로, 앞에 슬래시를 붙여 참조합니다.

```
{{ figure(src="/images/photo.jpg", caption="A photo") }}
```

`example.com/my-site/`처럼 하위 경로에 배포할 때도 앞의 `/`를 그대로 두세요. Hwaro가 빌드 시점에 루트 상대 `src`와 `href`에 `base_url`의 하위 경로를 붙여 주기 때문에, 같은 콘텐츠가 양쪽에서 모두 동작합니다.

에셋을 그 파일을 쓰는 페이지 옆, 즉 `content/` 안에 두는 것도 가능하지만 이는 선택 기능입니다. 먼저 [콘텐츠 파일](/ko/features/content-files/)을 활성화하세요.

```toml
[content.files]
allow_extensions = ["jpg", "png", "svg", "pdf"]
```

## 4. 설정 수정

`config.toml`을 엽니다:

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

## 5. 페이지 만들기

```bash
hwaro new content/about.md
```

> **팁:** 인자 없이 `hwaro new`를 실행하면 대화형 위저드가 열립니다.
> 경로를 추천해 주고 제목, 설명, 태그 등을 대신 받아 줍니다.

`content/about.md`를 수정합니다:

```markdown
+++
title = "About"
+++

Welcome to my site!
```

`http://localhost:3000/about/`에서 확인합니다.

## 6. 섹션 만들기

섹션은 관련 콘텐츠를 묶는 단위입니다. 블로그 섹션을 만들어 봅니다:

```bash
mkdir -p content/blog
```

`content/blog/_index.md`를 만듭니다:

```markdown
+++
title = "Blog"
sort_by = "date"
+++

My blog posts.
```

`content/blog/first-post.md`를 만듭니다:

```markdown
+++
title = "My First Post"
date = "2024-01-15"
tags = ["hello"]
+++

Hello, world!
```

`http://localhost:3000/blog/`에서 확인합니다.

## 7. 프로덕션 빌드

```bash
hwaro build
```

`public/` 디렉터리를 아무 정적 호스트에나 배포하면 됩니다. 간단한 설정 방법은 [GitHub Pages](/ko/deploy/github-pages/) 배포 가이드에 있습니다.

## 선택: AI 에이전트와 함께 만들기

Claude Code, Cursor, Codex 같은 스킬 지원 에이전트를 쓴다면, Hwaro가 제공하는
두 개의 [에이전트 스킬](/ko/integrations/skills/)로 방금 만든 프로젝트를 다루는
방법을 에이전트에게 가르칠 수 있습니다:

| 스킬 | 하는 일 |
|-------|--------------|
| `hwaro` | `init`, `new`, `serve`, `build`, `doctor`와 콘텐츠 도구를 제대로 실행합니다. 텍스트 출력을 추측하는 대신 `--json` 출력 규약과 `HWARO_E_*` 종료 코드를 사용합니다. |
| `hwaro-design` | Hwaro의 Crinja 템플릿과 `light-dark()` 디자인 토큰 안에서 사이트를 디자인하고 리테마합니다. 전형적인 AI 느낌의 레이아웃을 피하는 안티슬롭 원칙을 따릅니다. |

명령 하나로 둘 다 설치합니다:

```bash
npx skills add hahwul/hwaro
```

이후 *"이 Hwaro 사이트에 projects 섹션을 추가해 줘"* 나 *"이 블로그를 따뜻한
다크 팔레트로 리테마해 줘"* 처럼 요청하면 에이전트가 알아서 맞는 스킬을
불러옵니다. 수동 설치 경로와 에이전트별 디렉터리는
[에이전트 스킬](/ko/integrations/skills/)을, 에이전트가 먼저 따라야 할
프로젝트별 규칙을 기록해 두려면 [agents-md](/ko/start/tools/agents-md/)를
참고합니다.

## 다음 단계

- [CLI](/ko/start/cli/) — 사용 가능한 모든 명령
- [설정](/ko/start/config/) — 전체 설정 레퍼런스
- [콘텐츠 작성](/ko/writing/) — 페이지, 섹션, 택소노미
- [에이전트 스킬](/ko/integrations/skills/) — AI 에이전트에게 사이트 제작과 디자인 맡기기
- [배포](/ko/deploy/) — 호스팅과 배포 가이드

---

Title: 설치
URL: https://hwaro.hahwul.com/ko/start/installation/
Source: content/start/installation.ko.md
Language: ko

Hwaro는 Crystal로 작성되었습니다. 소스에서 직접 빌드하거나 사전 빌드된 바이너리로 설치하면 됩니다.

## Homebrew

```bash
brew tap hahwul/hwaro
brew install hwaro
```

## Snapcraft

```bash
sudo snap install hwaro
```

## APK (Alpine Linux)

[최신 릴리스](https://github.com/hahwul/hwaro/releases/latest)에서 `.apk` 패키지를 내려받아 설치합니다:

```bash
apk add --allow-untrusted hwaro-*.apk
```

## DEB (Debian/Ubuntu)

[최신 릴리스](https://github.com/hahwul/hwaro/releases/latest)에서 `.deb` 패키지를 내려받아 설치합니다:

```bash
sudo dpkg -i hwaro_*_amd64.deb
```

## RPM (Fedora/RHEL/CentOS)

[최신 릴리스](https://github.com/hahwul/hwaro/releases/latest)에서 `.rpm` 패키지를 내려받아 설치합니다:

```bash
sudo rpm -i hwaro-*.x86_64.rpm
```

## AUR (Arch Linux)

```bash
yay -S hwaro
```

## Nix

### 설치

```bash
nix profile install github:hahwul/hwaro
```

### 설치 없이 실행

```bash
nix run github:hahwul/hwaro -- --version
```

### 개발 셸

```bash
nix develop github:hahwul/hwaro
```

개발 셸에는 Crystal, `shards`, `just`, `crystal2nix`가 함께 들어 있어 다른 것을
설치하지 않아도 `just build`와 `just test`를 바로 실행할 수 있습니다.

### 플레이크 입력으로 사용하기

```nix
{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  inputs.hwaro.url = "github:hahwul/hwaro";

  outputs = { nixpkgs, hwaro, ... }: {
    # `hwaro.packages.<system>.hwaro`를 쓰거나, `hwaro.overlays.default`를
    # nixpkgs 오버레이에 추가한 뒤 `pkgs.hwaro`로 사용하세요.
  };
}
```

지원 시스템은 `x86_64-linux`, `aarch64-linux`, `aarch64-darwin`입니다
(nixpkgs-unstable가 Intel macOS 지원을 중단했습니다). 플레이크가 공식 Crystal
툴체인을 고정해 두므로 컴파일러를 소스에서 빌드할 필요가 없습니다.

## 사전 빌드 바이너리

macOS와 Linux용 사전 빌드 바이너리를 [GitHub Releases](https://github.com/hahwul/hwaro/releases) 페이지에서 받을 수 있습니다.

1. [최신 릴리스](https://github.com/hahwul/hwaro/releases/latest)에서 플랫폼에 맞는 바이너리를 내려받습니다.
2. PATH에 포함된 디렉터리로 바이너리를 옮깁니다. **macOS 배포물은 단일 바이너리가
   아니라 tarball이므로, 옮기기 전에 아래 [macOS](#macos) 항목을 먼저 확인하세요.**

```bash
# Linux(amd64) 예시
chmod +x hwaro-v*-linux-x86_64
sudo mv hwaro-v*-linux-x86_64 /usr/local/bin/hwaro
```

### macOS

macOS 배포물은 단일 바이너리가 아니라 tarball입니다. 압축을 풀면 `hwaro`와
번들된 OpenSSL이 담긴 `lib/` 디렉터리가 나오고, 바이너리는 이 dylib들을
`@executable_path/lib` 경로로 읽습니다. 따라서 **`lib/`를 항상 바이너리와 함께
옮겨야 합니다.** 바이너리만 떼어 옮기면 실행되지 않습니다.

```bash
tar -xzf hwaro-v*-osx-arm64.tar.gz
sudo mkdir -p /usr/local/libexec/hwaro
sudo cp -R hwaro lib /usr/local/libexec/hwaro/
sudo ln -sf /usr/local/libexec/hwaro/hwaro /usr/local/bin/hwaro
```

심볼릭 링크는 안전합니다. macOS가 `@executable_path`를 계산하기 전에 링크를
먼저 해석하므로 dylib을 그대로 찾습니다. Homebrew도 같은 방식으로 설치합니다.

> **v0.20.0 한정.** 이 릴리스의 macOS tarball은 번들된 dylib의 코드 서명이 깨진
> 상태로 배포되어, Apple Silicon에서는 실행 즉시 프로세스가 종료됩니다
> (`zsh: killed hwaro`, 다른 메시지는 나오지 않습니다). quarantine 속성만 지워서는
> 해결되지 않습니다. 서명 자체가 깨져 있기 때문입니다. 반대로 다시 서명만 해도
> 막힐 수 있습니다. quarantine이 걸린 파일을 재서명하면 승인 상태가 초기화되기
> 때문입니다. 압축을 푼 디렉터리에서 아래 순서로 둘 다 실행하세요.
>
> ```bash
> xattr -dr com.apple.quarantine hwaro lib
> codesign --force --sign - lib/*.dylib hwaro
> ```
>
> 패치 릴리스가 나가면 이 과정은 필요 없습니다.

## 소스 빌드

### 사전 요구 사항

- [Crystal](https://crystal-lang.org/install/) 1.21+
- Git

### 빌드

```bash
git clone https://github.com/hahwul/hwaro
cd hwaro
shards install
shards build --release --no-debug
```

바이너리는 `./bin/hwaro`에 생성됩니다.

> Crystal **1.21 이상**이 필요합니다. 병렬 페이지 렌더링은 `src/main.cr`에서
> Crystal 기본 실행 컨텍스트 크기를 조정해 켜지므로 별도 빌드 플래그가
> 필요 없습니다. 워커 수는 `CRYSTAL_WORKERS=N`으로 조정할 수 있습니다(기본값은
> CPU 코어 수). 예전 `-Dpreview_mt` 플래그는 넣지 마세요. Crystal 1.21에서
> deprecated 되었고, 해당 스케줄러는 프로세스 종료 시 멈출 수 있습니다.
>
> `hwaro build` 실행 시(소스 빌드뿐 아니라 모든 설치 방식에서) Hwaro는
> Boehm GC를 함께 튜닝합니다(`GC_MARKERS=1`, `GC_INITIAL_HEAP_SIZE=256M`).
> 할당이 많은 사이트에서 빌드가 3~5배 빨라지는 것을 측정했으며, 대신
> 빌드 중 피크 메모리 사용량이 늘어납니다. 두 환경 변수를 직접
> export하면 내장 기본값보다 우선하고, `--memory-limit` 사용 시 힙
> 프리사이즈는 자동으로 비활성화됩니다. 자세한 내용은
> [전역 플래그 표](@/start/cli.md)를 참고하세요.

### PATH 등록 (선택)

```bash
# PATH에 포함된 디렉터리로 복사
sudo cp ./bin/hwaro /usr/local/bin/

# 또는 bin 디렉터리를 PATH에 추가
export PATH="$PATH:$(pwd)/bin"
```

## 설치 확인

```bash
hwaro --version
```

## 다음 단계

- [첫 사이트 만들기 →](/ko/start/first-site/)

---

Title: 도구와 자동 완성
URL: https://hwaro.hahwul.com/ko/start/tools/
Source: content/start/tools/_index.ko.md
Language: ko

Hwaro는 콘텐츠 관리를 돕는 유틸리티 도구와, CLI를 더 편하게 쓰기 위한 셸 자동 완성 스크립트를 제공합니다.

## 도구 명령

`hwaro tool` 명령은 콘텐츠 파일을 다루는 유틸리티 하위 명령을 제공합니다.

| 하위 명령 | 설명 |
|------------|-------------|
| [convert](/ko/start/tools/convert/) | 프론트 매터를 YAML과 TOML 형식 간에 변환 |
| [list](/ko/start/tools/list/) | 상태별 콘텐츠 파일 목록 출력 |
| [check-links](/ko/start/tools/check-links/) | 콘텐츠 파일의 깨진 링크 검사 |
| [stats](/ko/start/tools/stats/) | 콘텐츠 통계 표시 |
| [validate](/ko/start/tools/validate/) | 콘텐츠 프론트 매터와 마크업 검증 |
| [unused-assets](/ko/start/tools/unused-assets/) | 참조되지 않는 정적 파일 찾기 |
| [doctor](/ko/start/tools/doctor/) | 설정·템플릿·구조 문제 진단 |
| [platform](/ko/start/tools/platform/) | 호스팅 플랫폼 설정 파일 생성 |
| [import](/ko/start/tools/import/) | 다양한 플랫폼에서 콘텐츠 가져오기 |
| [export](/ko/start/tools/export/) | 다른 플랫폼으로 콘텐츠 내보내기 |
| [agents-md](/ko/start/tools/agents-md/) | AGENTS.md 파일 생성·갱신 |

> **사용 중단:** [ci (사용 중단)](/ko/start/tools/ci/)는 도움말에서 숨겨졌으며 [platform](/ko/start/tools/platform/)으로 대체되었습니다(예: `hwaro tool platform github-pages`).

---

## 셸 자동 완성

Hwaro는 셸별 자동 완성 스크립트를 생성해 명령, 하위 명령, 플래그를 탭으로 완성할 수 있게 합니다.

### 지원 셸

| 셸 | 명령 |
|-------|---------|
| Bash | `hwaro completion bash` |
| Zsh | `hwaro completion zsh` |
| Fish | `hwaro completion fish` |

### 설치

#### Bash

`~/.bashrc`에 추가합니다:

```bash
eval "$(hwaro completion bash)"
```

파일로 저장해도 됩니다:

```bash
hwaro completion bash > /etc/bash_completion.d/hwaro
```

#### Zsh

`~/.zshrc`에 추가합니다:

```bash
eval "$(hwaro completion zsh)"
```

fpath에 저장해도 됩니다:

```bash
hwaro completion zsh > ~/.zsh/completions/_hwaro
```

#### Fish

`~/.config/fish/config.fish`에 추가합니다:

```fish
hwaro completion fish | source
```

completions 디렉터리에 저장해도 됩니다:

```bash
hwaro completion fish > ~/.config/fish/completions/hwaro.fish
```

### 완성 대상

자동 완성 스크립트는 다음을 탭으로 완성합니다.

- **명령**: `hwaro <TAB>` → `init`, `build`, `serve`, `new`, `deploy`, `tool`, `completion`
- **하위 명령**: `hwaro tool <TAB>` → `convert`, `list`, `stats`, `validate`, `export` 등
- **플래그**: `hwaro build <TAB>` → `--output`, `--drafts`, `--minify` 등
- **위치 인자**: `hwaro completion <TAB>` → `bash`, `zsh`, `fish`
- **위치 인자 선택지**: `hwaro tool convert <TAB>` → `to-yaml`, `to-toml`

### 자동 갱신

자동 완성 스크립트는 명령 메타데이터에서 동적으로 생성됩니다. 새 명령이나 플래그가 추가된 버전으로 Hwaro를 업데이트한 뒤 스크립트를 다시 생성하면 자동으로 반영됩니다.

```bash
# hwaro 업데이트 후 다시 생성
eval "$(hwaro completion bash)"
```

## 함께 보기

- [CLI](/ko/start/cli/) — 전체 CLI 명령 레퍼런스
- [설정](/ko/start/config/) — 사이트 설정
- [빌드 훅](/ko/features/build-hooks/) — 커스텀 빌드 명령

---

Title: agents-md
URL: https://hwaro.hahwul.com/ko/start/tools/agents-md/
Source: content/start/tools/agents-md.ko.md
Language: ko

AI 에이전트 지침용 AGENTS.md 파일을 생성하거나 갱신합니다. 기존 프로젝트를 최신 AGENTS.md로 업데이트하거나 콘텐츠 모드를 전환할 때 유용합니다.

```bash
# 로컬(전체 내장) 버전을 stdout으로 출력
hwaro tool agents-md

# 원격(경량) 버전을 stdout으로 출력
hwaro tool agents-md --remote

# AGENTS.md 파일로 저장
hwaro tool agents-md --write

# 원격 버전을 파일로 저장
hwaro tool agents-md --remote --write

# 확인 없이 덮어쓰기
hwaro tool agents-md --write --force
```

## 콘텐츠 모드

| 모드 | 설명 |
|------|-------------|
| `--local` (기본값) | 전체 내장 레퍼런스(약 260줄). 콘텐츠 형식, 템플릿 변수, 설정 레퍼런스, AI 에이전트 참고 사항 포함. 오프라인이나 로컬 LLM 환경에 적합 |
| `--remote` | 경량 버전(약 50줄). 프로젝트 구조, 핵심 명령, 그리고 [온라인 문서](https://hwaro.hahwul.com)와 [LLM 레퍼런스](https://hwaro.hahwul.com/llms-full.txt) 링크가 담긴 AI 에이전트 참고 사항 포함 |

두 모드 모두 프로젝트 고유의 규칙과 컨벤션을 적을 수 있는 **Site-Specific Instructions** 섹션을 포함합니다. `--write`로 다시 생성해도 이 섹션은 기존 파일에서 그대로 이어집니다. 생성된 부분(모드 전환 포함)만 갱신되고 `## Site-Specific Instructions` 아래에 적은 내용은 변경 없이 보존됩니다. 보존은 정확히 이 헤딩을 기준으로 동작하므로, `## Site-Specific Instructions` 헤딩이 없는 기존 파일은 전체가 교체됩니다(실행 전에 프롬프트가, `--force`에서는 경고가 이를 알려줍니다).

## 옵션

| 플래그 | 설명 |
|------|-------------|
| --remote | 온라인 문서 링크가 있는 경량 버전 생성 |
| --local | 전체 내장 레퍼런스 생성 (기본값) |
| --write | stdout 대신 AGENTS.md 파일로 저장 |
| -f, --force | 확인 없이 기존 파일 재생성 (Site-Specific Instructions 섹션은 보존) |
| -h, --help | 도움말 표시 |

기본적으로 stdout에 출력하므로 저장하기 전에 내용을 살펴볼 수 있습니다. 파일로 저장하려면 `--write`를 사용합니다. `AGENTS.md`가 이미 있으면 `--force`를 쓰지 않는 한 확인을 요청합니다. 어느 쪽이든 **Site-Specific Instructions** 섹션은 다시 쓰기 과정에서 보존됩니다.

## `hwaro init`와의 관계

새 프로젝트를 만들 때는 `hwaro init`도 AGENTS.md 파일을 생성합니다. 콘텐츠 모드는 `--agents` 플래그로 지정합니다:

```bash
hwaro init my-site                  # 기본값: remote (경량)
hwaro init my-site --agents local   # 전체 내장 레퍼런스
hwaro init my-site --skip-agents-md # AGENTS.md 생성 생략
```

## 함께 보기

- [CLI](/ko/start/cli/#init) — init 명령 옵션
- [CLI](/ko/start/cli/#tool) — 전체 tool 명령

---

Title: check-links
URL: https://hwaro.hahwul.com/ko/start/tools/check-links/
Source: content/start/tools/check-links.ko.md
Language: ko

콘텐츠 파일에서 깨진 외부·내부 링크를 검사합니다.

```bash
hwaro tool check-links

# 결과를 JSON으로 출력
hwaro tool check-links --json

# 타임아웃과 동시 요청 수 지정
hwaro tool check-links --timeout 30 --concurrency 4

# 외부 또는 내부 링크만 검사
hwaro tool check-links --external-only
hwaro tool check-links --internal-only

# 알려진 불안정 호스트 무시, 봇 차단 상태 코드 허용
hwaro tool check-links --ignore-url twitter.com --allow-status 403,429
```

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -c, --content-dir DIR | 콘텐츠 디렉터리 (기본값: `content`) |
| --timeout SECONDS | HTTP 요청 타임아웃(초, 기본값: 10) |
| --concurrency N | 최대 동시 요청 수 (기본값: 8) |
| --external-only | 외부 링크만 검사 |
| --internal-only | 내부 링크만 검사 |
| --ignore-url PATTERN | URL이 PATTERN과 일치하는 링크는 건너뜀 (반복 가능) |
| --allow-status CODES | 나열한 HTTP 상태 코드를 정상으로 취급 (쉼표 구분) |
| -j, --json | 결과를 JSON으로 출력 |
| -h, --help | 도움말 표시 |

`--ignore-url`은 소스에 적힌 URL을 대소문자 구분 없는 부분 문자열로
매칭합니다. `--ignore-url twitter.com`은 `twitter.com`(또는 `Twitter.com`)이
포함된 모든 링크를 건너뛰고, `*`는 임의 문자열과 매칭됩니다
(`--ignore-url 'https://example.com/*'`). 여러 번 전달할 수 있으며, 매칭된
링크에는 요청 자체를 보내지 않습니다. 무시된 개수는 스캔 라인과 JSON의
`ignored_count`에 함께 표시되므로, "모두 정상"과 "패턴이 과하게 넓어 아무것도
검사하지 않음"을 기계적으로 구분할 수 있습니다.

`--allow-status`는 브라우저에는 정상 응답하면서 링크 검사기에는 `403`/`429`를
돌려주는 호스트를 위한 것으로, 나열된 상태 코드는 CI를 실패시키지 않습니다.

## 동작 방식

1. `content/` 디렉터리의 모든 마크다운 파일을 스캔
2. 외부 URL(http/https 링크)과 내부 링크(상대/절대 경로)를 수집
3. 외부 URL에 동시 HEAD 요청 전송 (호스트가 HEAD를 405/403/501로 거부하면
   GET으로 재시도, 리다이렉트는 최대 5회 추적)
4. 내부 링크 대상이 디스크에 존재하는지 확인 (`.md`, `_index.md`, `index.md` 검사)
5. 빌드가 생성하는 경로는 소스 파일 없이도 유효한 것으로 인정
6. 파이프라인이 만들어 내는 에셋은 직전 빌드 출력에서 확인
   ([빌드 출력을 근거로 사용하기](#빌드-출력을-근거로-사용하기) 참고)
7. 깨졌거나 접근할 수 없는 링크 보고

사설/내부 주소(localhost, RFC 1918 대역, `.local`/`.internal` 호스트)로
해석되는 외부 링크에는 요청을 보내지 않습니다. 이런 링크는 사람용 출력과
JSON의 `skipped_external` 항목 모두에 "건너뜀"으로 보고됩니다.

### 생성 경로

일부 URL은 원본 파일이 없고 빌드가 직접 씁니다. 이런 경로는 `config.toml`에서
유도하므로, 첫 빌드 **이전**에도 `check-links`를 돌릴 수 있습니다(린트 후 빌드
순서로 도는 CI가 이 경우입니다).

- `/sitemap.xml`, `/robots.txt`, `/llms.txt`, 검색 인덱스, `404.html`. 각각
  설정된 `filename`을 따릅니다
- 피드(`/rss.xml`, `/atom.xml`). 언어별 사본(`/ko/rss.xml`)과 섹션별
  사본(`/posts/rss.xml`) 포함. 섹션 피드는 해당 섹션의 `_index.md`가
  `generate_feeds = true`를 선언했을 때만 인정합니다. 빌드가 그때만 파일을
  쓰기 때문입니다
- 분류 목록·용어 페이지(`/tags/`, `/categories/rust/`)
- 페이지네이션 경로(`/posts/page/2/`). `paginate_by`를 실제로 선언한 섹션에만
  해당하므로, 페이지네이션이 없는 섹션의 `/page/N/` 링크는 여전히 보고됩니다

## 링크 유형

| 유형 | 설명 |
|------|-------------|
| 외부 | `http://`, `https://` 링크 — HTTP HEAD로 검사 |
| 내부 | 상대·절대 경로 링크 — 파일 시스템에서 검사 |
| 이미지 | `![alt](path)` 이미지 참조 — 파일 시스템에서 검사 |

## 출력 예시

```
hwaro: check-links content
scan: 30 external, 20 internal

    [err] content/blog/post.md
      -> https://old-site.com/page  404
    [err] content/blog/post.md
      -> ../missing-page  Internal link target not found
    [err] content/about.md
      -> /images/photo.png  Image not found
checked: 50 links, 3 dead
```

색상 터미널에서는 깨진 링크마다 `hwaro check-links` 헤딩 아래 `✗ file` 항목과
`→ url status` 상세 줄로 표시되고, 마지막에 `✦ checked` 결과 줄이 붙습니다(모든
링크가 정상이면 `checked: 50 links · all healthy`). 깨진 링크가 발견되면 명령이
0이 아닌 종료 코드를 반환하므로 CI 게이트로 쓸 수 있습니다.

## JSON 출력

```json
{
  "dead_internal": [
    {
      "link": {
        "file": "content/about.md",
        "url": "/images/photo.png",
        "kind": "image"
      },
      "status": -1,
      "error": "Image not found"
    }
  ],
  "dead_external": [
    {
      "link": {
        "file": "content/blog/post.md",
        "url": "https://old-site.com/page",
        "kind": "external"
      },
      "status": 404,
      "error": null
    }
  ],
  "skipped_external": [
    {
      "link": {
        "file": "content/notes/intranet.md",
        "url": "http://wiki.internal/page",
        "kind": "external"
      },
      "status": -1,
      "error": "Skipped: private/internal address"
    }
  ],
  "ignored_count": 0,
  "output_hint": null
}
```

`output_hint`는 빌드 출력 때문에 결과를 다르게 읽어야 할 때만 값이 들어가고,
그 외에는 `null`입니다(아래 참고). 사람용 출력에도 같은 문장이 나오며, JSON에
같이 담아 두어 터미널 출력을 보지 않는 CI에서도 놓치지 않게 했습니다.

## 빌드 출력을 근거로 사용하기

컴파일된 스타일시트, 리사이즈된 이미지 변형, `[content.files]`나 에셋
파이프라인으로 발행된 파일처럼 원본 소스로는 설명되지 않는 링크가 있습니다.
`check-links`는 이런 경로를 직전 빌드 결과인 `[build] output_dir`(기본값
`public/`)에서 찾으면 유효한 것으로 인정합니다. 빌드 밖에서 도는 명령에게는
그것이 유일한 근거이기 때문입니다.

이 디렉터리는 `hwaro build`가 만든 것이어야 합니다. Hwaro 0.19부터
`hwaro serve`는 `.hwaro/serve/`에 빌드하고 `output_dir`은 건드리지 않으므로,
serve만 쓰는 작업 흐름에는 아무것도 없습니다. 이제 이유 없이 깨진 링크 목록만
쏟아내는 대신 그 사실을 알려줍니다:

```
checked: 4 links, 1 dead
  [info] public/ holds no build output — run `hwaro build` first; check-links
         validates build output, not `hwaro serve` output (.hwaro/serve/)
```

- **없거나 비어 있음** — 그 때문에 죽은 것으로 보고된 링크와 함께 안내가
  출력됩니다.
- **`hwaro serve` 출력** (`.hwaro-dev` 마커가 남은 경우) — `hwaro deploy`와 같은
  규칙으로 근거에서 제외합니다. 마커는 `hwaro build`가 지웁니다.
- **가장 최근 소스 파일보다 오래됨** — 문제가 없어 보이는 결과 아래에 안내가
  붙습니다. 삭제한 페이지의 `index.html`이 그 트리에 남아 있으면 링크가 계속
  통과하기 때문입니다.

CI에서는 `check-links` 전에 `hwaro build`를 돌려 실제 출력과 대조하세요.
소스만으로 판단되는 경로(`/about/`, `/tags/`, 피드, 사이트맵)는 빌드 출력이
없어도 됩니다.

---

Title: ci (사용 중단)
URL: https://hwaro.hahwul.com/ko/start/tools/ci/
Source: content/start/tools/ci.ko.md
Language: ko

> **사용 중단:** `hwaro tool ci`는 `hwaro tool platform`으로 통합되었습니다. 대신 `hwaro tool platform github-pages`를 사용합니다.

```bash
# 이전 (사용 중단)
hwaro tool ci github-actions

# 새 명령
hwaro tool platform github-pages
```

전체 문서는 [platform](/ko/start/tools/platform/)을 참고합니다.

---

Title: convert
URL: https://hwaro.hahwul.com/ko/start/tools/convert/
Source: content/start/tools/convert.ko.md
Language: ko

콘텐츠 파일 전체의 프론트 매터를 TOML, YAML, JSON 형식 간에 변환합니다.

```bash
# 모든 프론트 매터를 YAML로 변환
hwaro tool convert to-yaml

# 모든 프론트 매터를 TOML로 변환
hwaro tool convert to-toml

# 모든 프론트 매터를 JSON으로 변환
hwaro tool convert to-json

# 특정 디렉터리만 변환
hwaro tool convert to-yaml -c posts

# 아무것도 바꾸지 않고 어떤 파일이 변환될지 미리보기
hwaro tool convert to-yaml --dry-run

# 결과를 JSON으로 출력
hwaro tool convert to-yaml --json
```

이 명령은 형식 인자(`to-yaml`, `to-toml`, `to-json`) 하나만 받습니다.
추가 위치 인자는 오류로 거부되므로 다른 옵션은 `--content-dir` 같은 플래그를
사용하세요.

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -c, --content-dir DIR | 특정 콘텐츠 디렉터리로 변환 범위 제한 |
| --dry-run | 파일을 변경하지 않고 변환 대상만 미리보기 |
| -j, --json | 결과를 JSON으로 출력 |
| -h, --help | 도움말 표시 |

변환은 파일을 제자리에서 다시 쓰며 프런트매터 주석을 보존할 수 없으므로,
중요한 트리에는 `--dry-run`을 먼저 실행하세요. 파일을 쓰지 않을 뿐 파일별
"dropping N comment line(s)" 경고를 포함한 전체 파이프라인이 동일하게
동작합니다.

## JSON 출력

```json
{
  "success": true,
  "message": "Converted 5 files to YAML",
  "converted_count": 5,
  "skipped_count": 2,
  "error_count": 0,
  "dry_run": false
}
```

## 건너뛴 파일

사람이 읽는 요약에는 건너뛴 이유가 함께 표시됩니다. `already TOML`,
`without front matter`, `not front matter`:

```
converted: 5 files · 2 skipped (1 already TOML, 1 not front matter)
```

이 중 `not front matter`를 눈여겨보세요. 파일 첫머리의 `---`/`+++` 쌍 안이
키/값 매핑이 아니라 본문(예: 수평선)이라는 뜻입니다. 그대로 변환하면 작성자의
글이 지워지므로 파일을 건드리지 않고 stderr에 파일명을 남깁니다.

## 예시

변환 전:

```markdown
+++
title = "My Post"
date = "2024-01-15"
tags = ["crystal", "tutorial"]
+++

Content here.
```

`hwaro tool convert to-yaml` 실행 후:

```markdown
---
title: "My Post"
date: "2024-01-15"
tags:
  - crystal
  - tutorial
---

Content here.
```

`hwaro tool convert to-json` 실행 후:

```markdown
{
  "title": "My Post",
  "date": "2024-01-15",
  "tags": [
    "crystal",
    "tutorial"
  ]
}

Content here.
```

---

Title: doctor
URL: https://hwaro.hahwul.com/ko/start/tools/doctor/
Source: content/start/tools/doctor.ko.md
Language: ko

Hwaro 사이트의 설정, 템플릿, 구조 문제를 진단합니다.

> 콘텐츠 검증(프론트 매터, 대체 텍스트, 내부 링크)은 [`hwaro tool validate`](/ko/start/tools/validate/)를 사용합니다.

```bash
hwaro doctor

# 특정 콘텐츠 디렉터리만 검사
hwaro doctor -c posts

# 설정 값 정규화 (base_url 끝 슬래시, sitemap priority 등)
hwaro doctor --fix

# 권장 설정 섹션을 config.toml에 추가
hwaro doctor --approve

# 둘 다 수행 (--fix --approve와 동일)
hwaro doctor --full

# config.toml을 수정하지 않고 변경 사항 미리 보기
hwaro doctor --full --dry-run

# 결과를 JSON으로 출력
hwaro doctor --json
```

> `hwaro tool doctor`도 하위 호환 별칭으로 동작합니다.

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -c, --content-dir DIR | 검사할 콘텐츠 디렉터리 (기본값: content) |
| --fix | 실제 수정 수행 — 값 정규화 (base_url 끝 슬래시, sitemap priority 등) |
| --approve | 권장 선택 설정 섹션을 승인하고 추가 |
| --full | `--fix`와 `--approve`를 모두 수행 |
| --dry-run | `config.toml`을 수정하지 않고 변경 사항 미리 보기 |
| --strict | 종료 코드 계산 시 경고를 오류로 취급 |
| --max-warnings N | 경고 수가 N을 초과하면 0이 아닌 코드로 종료 |
| -j, --json | 결과를 JSON으로 출력 |
| -q, --quiet | 정보 출력과 배너 숨김 |
| -h, --help | 도움말 표시 |

## 검사 항목

**설정 진단:**

- `base_url`이 설정되지 않았거나 끝 슬래시가 있음
- `title`이 아직 자리표시자(`Hwaro Site`, `My Hwaro Site`)임
- `sitemap.changefreq` 값이 유효하지 않음
- `sitemap.priority`가 범위(0.0~1.0)를 벗어남
- 택소노미 이름 또는 언어 코드 중복
- `search.format`, `markdown.math_engine`, `pwa.cache_strategy` 값이 유효하지 않음
- `default_language`에 대응하는 `[languages.<code>]` 블록이 없음
- `deployment.target` / `[related] taxonomies`가 정의되지 않은 대상을 참조함
- `[[menus.*]]` 항목의 `parent`가 같은 메뉴의 어떤 identifier와도 맞지 않음
- 참조한 파일·디렉터리가 존재하지 않음 (`[og] default_image`, `[pwa] icons`,
  `[auto_includes] dirs`, `[[assets.bundles]] files` 등). 자체 origin을 가진 값
  (`https://…`, `//cdn…`, `data:…`)은 원격 URL이라 검증할 수 없으므로 건너뜁니다.
- 라우트 검사를 뒷받침할 수 없는 빌드 출력 (아래 [빌드 출력을 근거로 사용하기](#빌드-출력을-근거로-사용하기) 참고)

**템플릿 진단:**

- 템플릿 디렉터리를 찾을 수 없음
- 필수 템플릿 누락 (`page.html`, `section.html`)
- 빌드와 동일한 Crinja 파서로 검사한 템플릿 문법 오류
  (프로젝트 전용 숏코드 태그는 오류로 보지 않습니다)

**콘텐츠 진단:**

- 콘텐츠 디렉터리를 찾을 수 없음 (빌드해도 페이지가 생성되지 않음)
- 파싱에 실패하는 front matter (TOML/YAML)
- `[[menus.*]]`에 선언되지 않은 메뉴 이름을 front matter가 등록함

**구조 진단:**

- `_index.md`가 없는 섹션 디렉터리

## 출력 예시

```
hwaro: doctor

  config.toml
    [ok]   file present & parseable
    [warn] base_url, title
    [ok]   sitemap (changefreq, priority)
    [ok]   taxonomies (duplicates)
    [ok]   search (format)
    [ok]   languages (default_language resolves)
    [ok]   markdown / pwa (valid enums)
    [ok]   image processing (widths set)
    [ok]   deployment / related (refs resolve)
    [ok]   menus (parent references)
    [ok]   referenced files & dirs
    [ok]   build output (route evidence)
    [ok]   sass (sources & enablement)

  templates/
    [ok]   required files (page.html, section.html)
    [ok]   template syntax

  content/
    [ok]   directory present
    [ok]   front matter (TOML/YAML parse)
    [ok]   front matter menus (declared in config)
    [info] section index files (_index.md)

Config:
  [warn] config.toml: base_url is not set

Structure:
  [info] content/docs: Section directory missing _index.md: docs/

checked: 0 errors, 1 warning, 1 info

Tip: Use 'hwaro tool validate' for content checks
```

스캔 자체가 실행되지 않은 검사는 통과(✓)가 아니라 `[--] … (skipped)`로
표시됩니다. 예를 들어 `templates/`가 없으면 `template syntax`가 그렇습니다.

색상 터미널에서는 검사 줄이 `hwaro doctor` 헤딩 아래 `✓`/`⚠`/`✗`/`ℹ` 기호로
표시되고, 요약은 심각도별 색이 입혀진 `✦ checked` 결과 줄로 출력됩니다. 문제가
없으면 `checked: no issues found — your site looks great`로 끝납니다.

## 빌드 출력을 근거로 사용하기

`[pwa] offline_page`와 `[pwa] precache_urls`는 파일이 아니라 라우트입니다.
doctor는 먼저 `content/`에서 찾고, 확장자가 있는 값(컴파일된 스타일시트,
리사이즈된 이미지 변형 등)은 마지막 빌드 결과인 `[build] output_dir`
(기본값 `public/`)에서 찾습니다.

이 디렉터리는 `hwaro build`가 만든 것이어야 합니다. Hwaro 0.19부터
`hwaro serve`는 `.hwaro/serve/`에 빌드하고 `output_dir`은 건드리지 않으므로,
serve만 쓰는 작업 흐름에서는 이 디렉터리가 없거나 예전 빌드에 멈춰 있습니다.
이제 doctor가 그 사실을 알려줍니다:

- **없거나 비어 있음** — 검증하지 못한 라우트와 함께 `build-output-unusable`로
  보고합니다: *"public/ holds no build output — run `hwaro build` first"*.
- **`hwaro serve` 출력** (`.hwaro-dev` 마커가 남은 경우) — `hwaro deploy`와 같은
  규칙으로 근거에서 제외합니다. 마커는 `hwaro build`가 지웁니다.
- **가장 최근 소스 파일보다 오래됨** — 그 트리로 통과시킨 라우트가 있으면
  `build-output-stale`로 보고합니다. 삭제한 페이지의 `index.html`이 아직 남아
  있을 수 있기 때문입니다.

둘 다 `info` 수준이며, 실제로 그 트리가 필요했을 때만 나타납니다. 빌드가
생성하는 경로를 참조하지 않는 사이트는 `public/` 이야기를 듣지 않습니다.

## 알려진 문제 무시

doctor가 보고하는 문제 중 이미 알고 있어 숨기고 싶은 것이 있으면, 해당 규칙 ID를 `config.toml`의 `[doctor]` 섹션에 추가합니다:

```toml
[doctor]
ignore = [
  "title-default",
  "structure-missing-index",
]
```

규칙 ID는 `hwaro doctor --json` 출력에서 확인하면 됩니다. 무시된 문제는 사람이 읽는 출력과 JSON 출력 모두에서 완전히 제외됩니다.

> `ignore`는 **warning**과 **info** 수준의 문제만 숨깁니다. 아래 표에서 ✗로
> 표시된 error 수준 규칙은 어차피 `hwaro build`를 실패시키는 문제라서 목록에
> 넣어도 CI 게이트를 끌 수 없습니다. doctor는 계속 보고하고, 해당 항목이
> 효과가 없다는 경고를 출력합니다.

### 사용 가능한 규칙 ID

✗ 표시가 있는 항목은 error 수준이며 무시할 수 **없습니다**.

| ID | 분류 | 설명 |
|----|----------|-------------|
| `config-not-found` | config | 설정 파일을 찾을 수 없음 ✗ |
| `config-parse-error` | config | 설정 파싱 실패 ✗ |
| `base-url-missing` | config | base_url이 설정되지 않음 |
| `base-url-trailing-slash` | config | base_url에 끝 슬래시가 있음 |
| `title-default` | config | title이 아직 자리표시자임 |
| `sitemap-changefreq-invalid` | config | 유효하지 않은 sitemap.changefreq |
| `sitemap-priority-range` | config | sitemap.priority가 범위를 벗어남 |
| `taxonomy-duplicate` | config | 택소노미 이름 중복 |
| `language-duplicate` | config | 언어 코드 중복 |
| `search-format-invalid` | config | 지원하지 않는 search.format |
| `default-language-undefined` | config | default_language에 대응하는 `[languages.<code>]` 없음 |
| `markdown-math-engine-invalid` | config | 지원하지 않는 markdown.math_engine |
| `pwa-cache-strategy-invalid` | config | 지원하지 않는 pwa.cache_strategy |
| `pwa-display-invalid` | config | 지원하지 않는 pwa.display |
| `image-processing-widths-empty` | config | image_processing이 켜져 있으나 widths가 비어 있음 (무음 no-op) |
| `deployment-target-undefined` | config | deployment.target에 대응하는 `[[deployment.targets]]` 없음 |
| `related-taxonomy-undefined` | config | `[related]`가 정의되지 않은 택소노미를 참조 |
| `menu-parent-undefined` | config | 메뉴 항목의 `parent`가 같은 메뉴의 identifier와 맞지 않음 |
| `config-path-missing` | config | 참조한 파일이 존재하지 않음 |
| `config-dir-missing` | config | 참조한 디렉터리가 존재하지 않음 |
| `build-output-unusable` | config | `[build] output_dir`로 라우트를 검증할 수 없음 (없거나 `hwaro serve` 출력) |
| `build-output-stale` | config | 소스보다 오래된 빌드 출력으로 라우트를 통과시킴 |
| `missing-config-*` | config_missing | 설정 섹션 누락 (예: `missing-config-pwa`) |
| `template-dir-missing` | template | 템플릿 디렉터리를 찾을 수 없음 ✗ |
| `template-required-missing` | template | 필수 템플릿 누락 ✗ |
| `template-syntax-error` | template | 템플릿 파싱 실패 ✗ |
| `template-read-error` | template | 템플릿 읽기 실패 ✗ |
| `content-dir-missing` | content | 콘텐츠 디렉터리를 찾을 수 없음 |
| `content-frontmatter-invalid` | content | front matter 파싱 실패 ✗ |
| `content-read-error` | content | 콘텐츠 파일 읽기 실패 ✗ |
| `menu-undeclared` | content | front matter의 메뉴 이름이 설정에 선언되지 않음 |
| `structure-missing-index` | structure | `_index.md`가 없는 섹션 |

어떤 규칙 ID와도 맞지 않는 항목은 "효과 없음" 경고로 알려주므로, 오타가 조용히
넘어가지 않습니다.

## JSON 출력

```json
{
  "schema_version": 1,
  "issues": [
    {
      "id": "base-url-missing",
      "level": "warning",
      "category": "config",
      "file": "config.toml",
      "message": "base_url is not set"
    }
  ],
  "summary": {
    "errors": 0,
    "warnings": 1,
    "infos": 0,
    "total": 1
  },
  "exit_code": 0
}
```

---

Title: export
URL: https://hwaro.hahwul.com/ko/start/tools/export/
Source: content/start/tools/export.ko.md
Language: ko

hwaro 콘텐츠를 다른 정적 사이트 생성기 형식으로 내보냅니다. `hwaro tool import`의 반대 방향 작업입니다.

원본 파일의 프론트 매터는 TOML(`+++`), YAML(`---`), JSON(`{...}`)을 지원합니다.
세 형식 모두 동일한 필드 매핑과 초안 제외 규칙을 적용합니다. 잘못된 JSON 프론트
매터는 본문에 복사하지 않고 내보내기 오류로 보고합니다.

```bash
# Hugo로 내보내기
hwaro tool export hugo

# Jekyll로 내보내기
hwaro tool export jekyll

# 출력·콘텐츠 디렉터리 지정
hwaro tool export hugo -o ~/hugo-site -c posts

# 초안 콘텐츠 포함
hwaro tool export jekyll --drafts

# 상세 출력
hwaro tool export hugo --verbose
```

## 지원 대상

| 대상 | 설명 |
|--------|-------------|
| hugo | Hugo 형식으로 내보내기 (TOML 프론트 매터, content/ 구조) |
| jekyll | Jekyll 형식으로 내보내기 (YAML 프론트 매터, _posts/ 파일명 규칙) |

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -o, --output DIR | 출력 디렉터리 (기본값: export) |
| -c, --content-dir DIR | 콘텐츠 디렉터리 (기본값: content) |
| -d, --drafts | 초안 콘텐츠 포함 |
| --dry-run | 아무것도 쓰지 않고 모든 대상 경로 미리보기 |
| -v, --verbose | 상세 출력 표시 |
| -j, --json | 파일별 매니페스트를 JSON으로 출력 |
| -h, --help | 도움말 표시 |

같은 디렉터리로 다시 내보내면 이전 출력을 **대체**합니다. 이것이 일반적인
갱신 워크플로입니다. 기존 파일을 대체한 실행은 요약에 개수와 함께 경고가
표시되고, JSON 매니페스트에서는 해당 행이 `overwritten`으로 표시됩니다(새
대상은 `exported`). 쓰기 전에 전체 매니페스트를 보려면 `--dry-run`을
사용하세요.

## JSON 출력

```json
{
  "success": true,
  "dry_run": false,
  "exported_count": 2,
  "skipped_count": 0,
  "error_count": 0,
  "files": [
    { "path": "export/_posts/2024-01-01-hello.md", "action": "exported" },
    { "path": "export/about.md", "action": "overwritten" }
  ]
}
```

`files`에는 페이지 번들 에셋을 포함해 기록된 모든 대상 경로가 나열되며,
카운트는 콘텐츠 문서만 셉니다.

## 필드 매핑

### Hugo

| Hwaro | Hugo |
|-------|------|
| title | title |
| date | date |
| description | description |
| draft | draft |
| updated | lastmod |
| tags | tags |
| series | series |
| aliases | aliases |
| image | images (배열) |
| expires | expiryDate |
| weight | weight |
| [taxonomies] 테이블 | 최상위 `tags` / `categories` / … 로 승격 |

그 외 프론트 매터 키는 Hugo 페이지 파라미터로 그대로 전달됩니다.

출력 구조는 `export/content/` 아래에 원본 디렉터리 배치를 그대로 유지합니다.

### Jekyll

| Hwaro | Jekyll |
|-------|--------|
| title | title |
| date | date |
| description | description |
| draft = true | published: false |
| tags | tags |
| categories | categories |
| image | image |
| template | layout |
| [taxonomies] 테이블 | 최상위 `tags` / `categories` / … 로 승격 |

출력 규칙:
- 일반 글은 `_posts/`에 `YYYY-MM-DD-slug.md` 파일명으로 저장
- 초안 글은 날짜 접두사 없이 `_drafts/`에 저장
- 섹션 인덱스 파일(`_index.md`)은 `index.md` 페이지로 변환
- 프론트 매터는 TOML, YAML, JSON에서 YAML(`---`)로 변환
- `[taxonomies]` 테이블은 최상위 키로 승격됩니다. Hugo도 Jekyll도 중첩 테이블에서
  분류 소속을 읽지 않기 때문입니다. 같은 이름의 최상위 키가 이미 있으면 그쪽이
  우선하며, 이는 빌드가 둘을 해석하는 순서와 같습니다

## 내부 링크

`@/` 접두사를 쓰는 내부 링크는 자동으로 절대 경로로 변환됩니다:

```markdown
<!-- Hwaro -->
[About](@/about/_index.md)

<!-- Exported -->
[About](/about)
```

## 출력 예시

```
hwaro: export hugo
source: content
output: export
exported: 38 files, 4 skipped
```

`errors` 수는 오류가 발생했을 때만 덧붙습니다. 색상 터미널에서는 같은 보고서가
`hwaro export` 헤딩 아래 정렬된 행과 `✦ exported` 결과 줄로 표시됩니다.

---

Title: import
URL: https://hwaro.hahwul.com/ko/start/tools/import/
Source: content/start/tools/import.ko.md
Language: ko

다른 정적 사이트 생성기나 플랫폼의 콘텐츠를 hwaro로 가져옵니다. [`hwaro tool export`](/ko/start/tools/export/)의 반대 방향 작업입니다.

```bash
# WordPress WXR 파일 가져오기
hwaro tool import wordpress path/to/export.xml

# Jekyll 사이트 디렉터리 가져오기
hwaro tool import jekyll path/to/jekyll-site

# Hugo 사이트 가져오기
hwaro tool import hugo path/to/hugo-site

# Notion 내보내기 가져오기
hwaro tool import notion path/to/notion-export

# Obsidian 볼트 가져오기
hwaro tool import obsidian path/to/vault

# 출력 디렉터리 지정과 초안 포함
hwaro tool import jekyll path/to/site -o content/blog --drafts

# 상세 출력
hwaro tool import hugo path/to/site --verbose
```

## 지원 소스

| 소스 | 입력 | 비고 |
|--------|-------|-------|
| wordpress | WXR XML 파일 | WordPress 내보내기 파일에서 글과 페이지를 가져옴 |
| jekyll | 사이트 디렉터리 | `_posts/`를 읽고 `--drafts` 사용 시 `_drafts/`도 읽음 |
| hugo | 사이트 디렉터리 | 섹션 배치를 유지하며 `content/`를 읽음 |
| notion | 내보내기 디렉터리 | Notion 내보내기의 `.md` 파일을 재귀적으로 가져옴 |
| obsidian | 볼트 디렉터리 | 노트를 재귀적으로 가져옴 (점으로 시작하는 폴더 제외) |
| hexo | 사이트 디렉터리 | `source/_posts/`와 `source/_drafts/`를 읽음 |
| astro | 사이트 디렉터리 | `src/content/` 컬렉션을 읽음 |
| eleventy | 사이트 디렉터리 | Eleventy 프론트 매터가 있는 마크다운 파일을 읽음 |

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -o, --output DIR | 출력 콘텐츠 디렉터리 (기본값: `content`) |
| -d, --drafts | 초안 콘텐츠 포함 |
| --force | 기존 파일을 건너뛰지 않고 덮어쓰기 |
| --dry-run | 아무것도 쓰지 않고 모든 대상 경로 미리보기 |
| -v, --verbose | 상세 출력 표시 |
| -j, --json | 파일별 매니페스트를 JSON으로 출력 |
| -h, --help | 도움말 표시 |

`--dry-run`은 충돌로 인한 이름 변경과 건너뛰기 판정을 포함해 모든 대상 경로를
실제와 동일하게 해석하되 디스크는 건드리지 않으므로, 대규모 임포트가 정확히
무엇을 할지 실행 전에 확인할 수 있습니다.

## JSON 출력

```json
{
  "success": true,
  "dry_run": false,
  "imported_count": 2,
  "skipped_count": 1,
  "error_count": 0,
  "files": [
    { "path": "content/posts/hello.md", "action": "imported" },
    { "path": "content/posts/second.md", "action": "imported" },
    { "path": "content/posts/existing.md", "action": "skipped" }
  ]
}
```

`action`은 `imported`, `skipped`(대상이 이미 존재하고 `--force` 미지정),
`overwritten`(`--force`로 기존 파일 대체) 중 하나입니다.
`files`에는 페이지 번들 에셋을 포함해 실행이 해석한 모든 대상 경로가
나열되며, 카운트는 콘텐츠 문서만 셉니다. 대상 경로를 해석하기 전에 건너뛴
소스(`--drafts` 없는 초안, 안전하지 않은 슬러그)는 카운트에만 반영되고 행은
없습니다.

## 동작

- 프론트 매터는 hwaro 기본 형식인 TOML(`+++`)로 변환됩니다. hwaro는 YAML 프론트 매터(`---`)도 지원합니다: 가져온 뒤 `hwaro tool convert to-yaml`을 실행하거나, 이후 `hwaro new`가 생성할 형식을 바꾸려면 `config.toml`에 `[content.new].front_matter_format = "yaml"`을 설정합니다. 다만 `front_matter_format`은 내장 템플릿에만 적용됩니다. 아키타입은 자신의 프론트 매터를 그대로 사용하고 모든 스캐폴드가 `archetypes/default.md`를 포함하므로, 이 설정을 적용하려면 해당 파일(또는 매칭되는 아키타입)을 삭제해야 합니다. [아키타입](/ko/writing/archetypes/) 문서를 참고합니다.
- HTML 콘텐츠(예: WordPress)는 마크다운으로 변환됩니다.
- 대상 경로에 이미 있는 파일은 덮어쓰지 않고 **건너뜁니다**. 다시 가져오려면 먼저 삭제하거나 이름을 바꾸거나, `--force`를 사용합니다.
- 두 소스 파일이 **같은** 대상 경로로 해석될 때(슬러그 중복, 제목이 같은 두 노트, `YYYY-MM-DD-` 날짜 접두사 제거, 컬렉션 하위 폴더 두 개가 한 섹션으로 병합되는 경우 등), 두 번째부터는 하나가 다른 하나를 조용히 덮어쓰지 않고 `slug-1.md`, `slug-2.md`, … 로 나란히 저장됩니다. 이름이 바뀐 대상의 개수는 파일마다 한 줄씩이 아니라 실행이 끝날 때 한 번만 보고됩니다.
- `--force`는 "이번 가져오기 이전부터 있던 파일을 덮어쓴다"는 뜻입니다. **같은 실행**에서 방금 쓴 파일을 다른 파일이 덮어쓰게 하지는 않습니다. 그런 경우는 위의 `-1` / `-2` 접미사가 붙습니다. 따라서 가져오기를 다시 실행해도 결과가 같습니다: 각 소스는 처음에 선택한 대상으로 다시 해석되어 건너뛰거나(`--force`면 덮어쓰기) 처리되며, 실행할 때마다 `-1` 사본이 쌓이지 않습니다.
- 알려진 글 유형만 가져옵니다 (예: WordPress의 `post`와 `page`).

## 출력 예시

```
hwaro: import jekyll
source: ./old-blog
output: content
imported: 42 files, 3 skipped
```

`errors` 수는 오류가 발생했을 때만 덧붙고, 건너뛴 파일이 있으면 `--force`를
안내하는 경고가 표시됩니다. 색상 터미널에서는 같은 보고서가 `hwaro import` 헤딩
아래 정렬된 행과 `✦ imported` 결과 줄로 표시됩니다.

## 함께 보기

- [`hwaro tool export`](/ko/start/tools/export/) — hwaro 콘텐츠를 다른 형식으로 내보내기
- [페이지](/ko/writing/pages/) — 프론트 매터 레퍼런스

---

Title: list
URL: https://hwaro.hahwul.com/ko/start/tools/list/
Source: content/start/tools/list.ko.md
Language: ko

상태별로 걸러낸 콘텐츠 파일 목록을 출력합니다.

```bash
# 모든 콘텐츠 파일 나열
hwaro tool list all

# 초안 파일만 나열
hwaro tool list drafts

# 발행된 파일만 나열
hwaro tool list published

# 특정 디렉터리의 파일 나열
hwaro tool list all -c posts

# 가장 최근 발행 파일 5개
hwaro tool list published --limit 5

# 제목순 정렬(A→Z), 또는 임의 정렬의 역순
hwaro tool list all --sort title
hwaro tool list all --sort path --reverse

# 결과를 JSON으로 출력
hwaro tool list all --json
```

이 명령은 필터 인자(`all`, `drafts`, `published`) 하나만 받습니다.
추가 위치 인자는 오류로 거부되므로 다른 옵션은 `--content-dir` 같은 플래그를
사용하세요.

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -c, --content-dir DIR | 특정 콘텐츠 디렉터리로 목록 범위 제한 |
| --sort KEY | 정렬 키: `date`(최신순, 기본값), `title`, `path` |
| -r, --reverse | 정렬 순서 뒤집기 |
| -n, --limit N | 최대 N개 파일만 표시 (정렬 후 적용) |
| -j, --json | 결과를 JSON으로 출력 |
| -h, --help | 도움말 표시 |

`--limit`은 정렬 후에 적용되므로 `--sort date --limit 5`는 "가장 최신 5개",
`--sort date --reverse --limit 5`는 가장 오래된 5개를 의미합니다.
`--sort title`은 템플릿 엔진의 `sort_by="title"`과 같은 대소문자 구분
정렬을 사용하므로 CLI 목록이 렌더링된 섹션 인덱스와 일치합니다.

필터 인자는 축약형 `draft`(`drafts`)와 `pub`(`published`)도 허용합니다.

## 필터

| 필터 | 설명 |
|--------|-------------|
| all | 모든 콘텐츠 파일 표시 |
| drafts | 초안만 표시 — `draft = true` 또는 상위 섹션에서 캐스케이드된 `draft` |
| published | 기본 `hwaro build`가 실제로 발행하는 파일만 표시 |

`published`는 "draft 표시가 없음"이 아니라 "빌드가 실제로 내보냄"을 뜻합니다.
기본 빌드는 미래 날짜(`date`가 미래) 페이지와 만료된(`expires`가 지난) 페이지도
제외하므로, 이들은 별도 상태로 보고됩니다.

| 상태 | 의미 |
|--------|---------|
| `[pub]` | 기본 빌드가 발행 |
| `[draft]` | 자체 또는 캐스케이드된 `draft = true` |
| `[future]` | `date`가 미래 (`--include-future`로 빌드 가능) |
| `[expired]` | `expires`가 지남 (`--include-expired`로 빌드 가능) |

## JSON 출력

```json
[
  {
    "path": "content/blog/my-post.md",
    "title": "My Post",
    "draft": false,
    "date": "2024-06-15T00:00:00+00:00",
    "status": "published",
    "expires": null
  },
  {
    "path": "content/blog/draft-post.md",
    "title": "Draft Post",
    "draft": true,
    "date": "2024-06-10T00:00:00+00:00",
    "status": "draft",
    "expires": null
  }
]
```

`status`는 `published`, `draft`, `future`, `expired` 중 하나입니다. `draft`는
기존 소비자를 위해 유지되며 실제 초안일 때만 true입니다.

---

Title: platform
URL: https://hwaro.hahwul.com/ko/start/tools/platform/
Source: content/start/tools/platform.ko.md
Language: ko

주요 제공자용 플랫폼 설정과 CI/CD 워크플로 파일을 생성합니다. `config.toml`과 콘텐츠 별칭을 읽어 바로 쓸 수 있는 배포 설정을 만듭니다.

```bash
# 호스팅 플랫폼
hwaro tool platform netlify
hwaro tool platform vercel
hwaro tool platform cloudflare

# CI/CD 워크플로
hwaro tool platform github-pages
hwaro tool platform gitlab-ci
hwaro tool platform codeberg-pages

# 사용자 지정 경로로 출력
hwaro tool platform netlify -o deploy/netlify.toml

# 파일 대신 stdout으로 출력
hwaro tool platform vercel --stdout
```

> **참고:** `hwaro tool ci`는 사용 중단되었습니다. 대신 `hwaro tool platform github-pages`를 사용합니다.

## 지원 플랫폼

| 플랫폼 | 출력 파일 | 설명 |
|----------|-------------|-------------|
| netlify | `netlify.toml` | 빌드 설정, 리다이렉트, 헤더 |
| vercel | `vercel.json` | 빌드 명령, 라우팅, 캐시 헤더 |
| cloudflare | `wrangler.toml` | Workers/Pages 사이트 설정 |
| github-pages | `.github/workflows/deploy.yml` | GitHub Actions 빌드 + 배포 워크플로 |
| gitlab-ci | `.gitlab-ci.yml` | GitLab CI/CD 파이프라인 |
| codeberg-pages | `.forgejo/workflows/deploy.yml` | Codeberg Pages(Forgejo Actions) 배포 워크플로 |

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -o, --output PATH | 출력 파일 경로 (기본값: 자동 감지) |
| --stdout | 파일 대신 stdout으로 출력 |
| -f, --force | 기존 파일을 경고 없이 덮어쓰기 |
| -h, --help | 도움말 표시 |

출력 파일이 이미 있으면 `--force`로 덮어씁니다.

## 생성되는 설정

각 설정에는 다음이 포함됩니다.

- **빌드 명령**: `hwaro build`
- **출력 디렉터리**: 설정한 `[build] output_dir` (기본값 `public/`). 값을
  바꾸면 생성되는 모든 설정 파일에 그대로 반영되므로, 호스팅 서비스가
  `hwaro build`가 실제로 쓰는 디렉터리를 배포합니다. `gitlab-ci`는 기본값이
  아닐 때 `pages` 잡에 `publish:`도 함께 추가합니다.
- **리다이렉트**: 프론트 매터에 정의한 페이지 [`aliases`](/ko/writing/pages/)에서 만든 301 리다이렉트 (예: `aliases: ["/old-url/"]`)
- **캐시 헤더**: 정적 에셋의 장기 캐싱

### Netlify 출력

```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 출력

```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"
        }
      ]
    }
  ]
}
```

## 함께 보기

- [GitHub Pages](/ko/deploy/github-pages/) | [GitLab CI](/ko/deploy/gitlab-ci/) | [Netlify](/ko/deploy/netlify/) | [Vercel](/ko/deploy/vercel/) | [Cloudflare Pages](/ko/deploy/cloudflare-pages/) | [Codeberg Pages](/ko/deploy/codeberg-pages/) — 플랫폼별 배포 가이드
- [CLI](/ko/start/cli/#tool) — 전체 tool 명령

---

Title: stats
URL: https://hwaro.hahwul.com/ko/start/tools/stats/
Source: content/start/tools/stats.ko.md
Language: ko

글 개수, 단어 수 지표, 태그 분포, 월별 발행 빈도 등 콘텐츠 통계를 표시합니다.

`published`는 기본 `hwaro build`가 실제로 내보내는 파일 수입니다. 빌드가 제외하는
파일은 각각의 이유로 따로 집계됩니다. `drafts`(자체 또는 상위 섹션에서 캐스케이드),
`future`(`date`가 미래), `expired`(`expires`가 지남). 단어 수·태그 분포·월별 차트는
발행되는 파일만 대상으로 합니다. 태그는 최상위 `tags` 목록에서 읽고, 없으면
`[taxonomies] tags` 테이블로 대체합니다. 빌드와 동일한 규칙입니다.

```bash
# 콘텐츠 디렉터리 통계 표시
hwaro tool stats

# 사용자 지정 콘텐츠 디렉터리 사용
hwaro tool stats -c posts

# 기본 15개 대신 상위 30개 태그 차트
hwaro tool stats --top 30

# JSON으로 출력
hwaro tool stats --json
```

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -c, --content-dir DIR | 콘텐츠 디렉터리 (기본값: content) |
| --top N | 차트에 상위 N개 태그 표시 (기본값: 15) |
| -j, --json | 결과를 JSON으로 출력 |
| -h, --help | 도움말 표시 |

## 출력 예시

```
hwaro: stats content
total: 42 files, 4 drafts · 1 future
words: 28,500 total, 678 avg
range: 120 min, 3,200 max

tags:
      crystal     12  ####################
      web          8  #############
      tutorial     5  ########

monthly:
      2024-01      3  ############
      2024-02      5  ####################
      2024-03      2  ########

counted: 42 files, 37 published, 4 drafts · 1 future
```

색상 터미널에서는 같은 보고서가 `hwaro stats` 헤딩, 정렬된 영수증 형식 행,
비례 막대 차트, `✦ counted` 결과 줄로 표시됩니다. 태그가 차트 예산을 넘으면
상위 N개만 차트로 그립니다(기본 `tags: top 15`, `--top N`으로 조정). JSON
출력은 `--top`과 무관하게 항상 모든 태그를 담습니다.

## JSON 출력

```json
{
  "total": 42,
  "published": 37,
  "drafts": 4,
  "future": 1,
  "expired": 0,
  "word_count": {
    "total": 28500,
    "average": 678,
    "min": 120,
    "max": 3200
  },
  "tags": {
    "crystal": 12,
    "web": 8,
    "tutorial": 5
  },
  "monthly": {
    "2024-01": 3,
    "2024-02": 5,
    "2024-03": 2
  }
}
```

---

Title: unused-assets
URL: https://hwaro.hahwul.com/ko/start/tools/unused-assets/
Source: content/start/tools/unused-assets.ko.md
Language: ko

정적 파일과 콘텐츠 옆에 함께 두는 에셋을 스캔해, 어떤 콘텐츠나 템플릿에서도 참조하지 않는 파일을 보고합니다.

```bash
# 사용하지 않는 에셋 찾기
hwaro tool unused-assets

# 디렉터리 지정
hwaro tool unused-assets -c posts -s assets

# 사용하지 않는 파일 삭제 (확인 프롬프트 표시)
hwaro tool unused-assets --delete

# 프롬프트 없이 삭제 (스크립트/CI)
hwaro tool unused-assets --delete --force

# JSON으로 출력
hwaro tool unused-assets --json

# JSON 모드에서 삭제 (프롬프트가 없으므로 --force 필요)
hwaro tool unused-assets --delete --force --json
```

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -c, --content-dir DIR | 콘텐츠 디렉터리 (기본값: content) |
| -s, --static-dir DIR | 정적 파일 디렉터리 (기본값: static) |
| -t, --templates-dir DIR | 참조 스캔 대상 템플릿 디렉터리 (기본값: templates) |
| --delete | 사용하지 않는 파일 삭제 (확인 프롬프트 표시) |
| -f, --force | 삭제 시 확인 프롬프트 생략 (`--json`에서 삭제하려면 필수) |
| -j, --json | 결과를 JSON으로 출력 |
| -h, --help | 도움말 표시 |

## 스캔 대상

**에셋 소스:**
- `static/` 디렉터리의 파일 (이미지, CSS, JS, 폰트, 미디어 등)
- 콘텐츠 디렉터리에 함께 있는 에셋 (`.md` 파일 옆의 마크다운 이외 파일)

**참조 소스:**
- 모든 콘텐츠 파일 (`.md`, `.markdown`)
- 템플릿 파일 (`.html`, `.j2`, `.jinja`, `.jinja2`, `.ecr`, 그리고 `.css`, `.js`, `.xml`, `.json`, `.webmanifest`, `.svg`, `.txt`)
- 다른 정적 파일을 참조할 수 있는 정적 소스 (`.css`, `.scss`, `.sass`, `.js`, `.json`, `.webmanifest`, `.xml`, `.svg`, `.txt`, `.html`, `.htm`)
- 데이터·번역 파일 (`data/`, `i18n/`의 `.yml`, `.yaml`, `.json`, `.toml`)
- 파일을 지정하는 `config.toml` 값

템플릿이 `templates/` 밖에 있다면 `--templates-dir`로 스캔 위치를 알려주세요.
그렇지 않으면 해당 템플릿의 에셋 참조가 보이지 않아, 실제로 쓰이는 에셋이
미사용으로 보고되고 `--delete`로 삭제될 수 있습니다.
명시적으로 전달한 `--templates-dir`은 반드시 존재해야 하며(경로는 현재
디렉터리 기준), 없는 경로면 템플릿 0개를 조용히 스캔하는 대신 실행을
거부합니다.

**지원 에셋 확장자:**
이미지(png, jpg, jpeg, gif, svg, webp, avif, ico, bmp, tiff, tif), 스타일시트(css), 스크립트(js), 폰트(woff, woff2, ttf, eot, otf), 미디어(mp4, webm, ogg, mp3, wav), 문서(pdf, zip).

## 출력 예시

```
hwaro: unused-assets static
total: 24
referenced: 20
unused: 4
unused files:
    - static/old-logo.png
    - static/unused-banner.jpg
    - content/blog/my-post/draft-image.png
    - static/deprecated.css
    [info] dynamic references (e.g. template variables) may cause false positives
found: 4 unused assets
```

색상 터미널에서는 정렬된 행으로 구성된 `hwaro unused-assets` 영수증과
`✦ found` 결과 줄로 표시됩니다(모두 참조 중이면 `found: no unused assets`).
`--delete`를 쓰면 확인 후 결과 줄이 `deleted: N files`로 바뀌고, 취소하면
`cancelled: no files deleted`가 됩니다.

## JSON 출력

```json
{
  "unused_files": [
    "static/old-logo.png",
    "static/unused-banner.jpg"
  ],
  "total_assets": 24,
  "referenced_count": 22,
  "unused_count": 2
}
```

## 제한 사항

- 템플릿 변수 등으로 동적으로 참조되는 에셋 파일명(예: `{{ page.image }}`)은 감지되지 않아 오탐(false positive)이 생길 수 있습니다.
- 감지는 파일명 매칭 기반입니다. 서로 다른 디렉터리의 두 파일이 이름이 같으면, 실제로는 하나만 쓰이더라도 둘 다 참조된 것으로 간주될 수 있습니다.

---

Title: validate
URL: https://hwaro.hahwul.com/ko/start/tools/validate/
Source: content/start/tools/validate.ko.md
Language: ko

콘텐츠 파일의 프론트 매터 완결성, 접근성, 구조 정합성을 검증합니다.

```bash
# 모든 콘텐츠 파일 검증
hwaro tool validate

# 특정 콘텐츠 디렉터리 검증
hwaro tool validate -c posts

# 경고도 CI 실패로 처리하거나, 허용 경고 수 상한 지정
hwaro tool validate --strict
hwaro tool validate --max-warnings 5

# JSON으로 출력
hwaro tool validate --json
```

## 옵션

| 플래그 | 설명 |
|------|-------------|
| -c, --content-dir DIR | 콘텐츠 디렉터리 (기본값: content) |
| --strict | 종료 코드 계산 시 경고를 오류로 취급 |
| --max-warnings N | 경고 수가 N을 넘으면 0이 아닌 코드로 종료 (기본값: 무제한) |
| -j, --json | 결과를 JSON으로 출력 |
| -h, --help | 도움말 표시 |

## 검사 항목

- 프론트 매터에 `title` 누락
- 프론트 매터에 `description` 누락
- 대체 텍스트가 없는 이미지 (`![](url)`)
- 깨진 내부 링크 (해석되지 않는 `@/` 접두사 경로)
- 프론트 매터 파싱 오류 (TOML/YAML/JSON)
- 유효하지 않은 날짜 형식
- 대소문자가 섞인 태그 (예: `crystal` 대신 `Crystal`)
- 초안 파일 (info로 보고)

## 출력 예시

```
hwaro: validate content

content/blog/draft.md:
      [warn] Missing description in frontmatter
      [info] File is marked as draft

content/about.md:
      [warn] Image missing alt text: ![](photo.jpg)
      [info] Tag has mixed case: "Crystal" (consider lowercase)

checked: 0 errors, 2 warnings, 2 info
```

색상 터미널에서는 발견 항목이 `hwaro validate` 헤딩 아래 `⚠`/`✗`/`ℹ` 기호로
표시되고, 마지막 줄은 심각도별 색이 입혀진 `✦ checked` 결과입니다. 오류 수준
문제가 발견되면 0이 아닌 종료 코드를 반환하므로 CI 게이트로 쓸 수 있습니다.

종료 코드는 `hwaro doctor`와 같은 규칙을 따릅니다. 오류 수준 발견은 콘텐츠
오류 코드(5)로, `--strict`/`--max-warnings`로 인한 경고 기반 실패는 일반
코드(1)로 종료되어 파일 자체의 문제와 게이트 강화로 인한 실패를 구분할 수
있습니다. 두 플래그는 `--json` 실행에도 동일하게 적용됩니다.

## 규칙 ID

| ID | 수준 | 설명 |
|----|-------|-------------|
| `content-title-missing` | warning | title이 없거나 "Untitled"임 |
| `content-description-missing` | warning | description 누락 |
| `content-alt-text-missing` | warning | 대체 텍스트가 없는 이미지 |
| `content-internal-link-broken` | warning | 깨진 `@/` 내부 링크 |
| `content-date-invalid` | warning | 인식할 수 없는 날짜 형식 |
| `content-frontmatter-toml-error` | error | TOML 프론트 매터 파싱 오류 |
| `content-frontmatter-yaml-error` | error | YAML 프론트 매터 파싱 오류 |
| `content-frontmatter-json-error` | error | JSON 프론트 매터 파싱 오류 |
| `content-read-error` | error | 콘텐츠 파일 읽기 실패 |
| `content-tag-mixed-case` | info | 대소문자가 섞인 태그 |
| `content-draft` | info | 초안으로 표시된 파일 |

## JSON 출력

```json
{
  "findings": [
    {
      "file": "content/blog/draft.md",
      "line": null,
      "rule": "content-description-missing",
      "severity": "warning",
      "message": "Missing description in frontmatter"
    }
  ]
}
```

---

Title: 템플릿
URL: https://hwaro.hahwul.com/ko/templates/
Source: content/templates/_index.ko.md
Language: ko

템플릿은 콘텐츠가 HTML로 바뀌는 방식을 정의합니다. Hwaro는 Jinja2 호환 엔진인 Crinja를 사용합니다.

## 템플릿 디렉터리

```
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
└── hooks/              # Markdown render-element overrides (link/image/heading/codeblock)
```

`shortcodes/` 디렉터리에는 마크다운에 삽입할 수 있는 재사용 컴포넌트를 둡니다. 사용법과 커스텀 숏코드 만드는 방법은 [콘텐츠 작성: 숏코드](/ko/writing/shortcodes/)를 참고합니다.

HTML 외에도 페이지/섹션은 `[outputs]` 설정으로 활성화한 형제 파일 `templates/page.<fmt>.jinja` / `templates/section.<fmt>.jinja`(JSON, XML, TXT, CSV)를 추가로 렌더링할 수 있습니다. [출력 포맷](/ko/features/output-formats/)을 참고합니다.

`hooks/` 디렉터리는 개별 마크다운 요소가 렌더링되는 방식을 재정의합니다. [렌더 훅](/ko/templates/render-hooks/)을 참고합니다.

## 템플릿 선택

| 콘텐츠 | 템플릿 |
|---------|----------|
| content/index.md | index.html 또는 page.html |
| content/about.md | page.html |
| content/blog/_index.md | section.html |
| content/blog/post.md | page.html |
| 택소노미 인덱스 | taxonomy.html |
| 택소노미 항목 | taxonomy_term.html |

## 간단한 예시

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

{% block content %}
<article>
  <h1>{{ page.title }}</h1>
  <time>{{ page.date }}</time>
  {{ content | safe }}
</article>
{% endblock %}
```

---

Title: 데이터 모델
URL: https://hwaro.hahwul.com/ko/templates/data-model/
Source: content/templates/data-model.ko.md
Language: ko

Hwaro의 템플릿 시스템은 **Site**, **Section**, **Page** 세 가지 핵심 타입을 중심으로 동작합니다. 이 페이지는 **템플릿 쪽 레퍼런스**로, 템플릿을 만들 때 쓸 수 있는 모든 속성과 변수를 다룹니다. 콘텐츠 작성과 프론트 매터 필드 설정은 [콘텐츠 작성](/ko/writing/)을 참고합니다.

## 계층 구조

```
Site
├── Config (title, base_url, ...)
├── Pages[] (standalone pages)
├── Sections[]
│   ├── Pages[] (pages in section)
│   └── Subsections[]
│       ├── Pages[]
│       └── Subsections[] (recursive)
└── Taxonomies{}
    └── Terms{}
        └── Pages[]
```

### 관계

- **Site**는 여러 **Section**과 독립 **Page**를 포함합니다
- **Section**은 **Page**와 자식 **Subsection**을 포함합니다
- **Subsection**은 제한 없이 중첩됩니다
- **Taxonomy**는 항목별로 **Page**를 묶습니다

## Site

최상위 컨테이너입니다. `config.toml`에서 설정합니다.

### 속성

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| site.title | String | 사이트 제목 |
| site.description | String | 사이트 설명 |
| site.base_url | String | 기본 URL(끝 슬래시 없음) |
| site.pages | Array<Page> | 섹션에 속하지 않은 모든 페이지 |
| site.sections | Array<Section> | 모든 섹션 인덱스 페이지 |
| site.taxonomies | Object | 모든 택소노미 그룹과 항목 |
| site.data | Object | `data/` 디렉터리에서 불러온 데이터 |
| site.authors | Object | 집계된 작성자 데이터 |
| site.menus | Object | **기본 언어**의 이름 있는 메뉴([메뉴](#메뉴) 참고) |

### 플랫 별칭

| 변수 | 동일 표현 |
|----------|------------|
| site_title | site.title |
| site_description | site.description |
| base_url | site.base_url |

### 데이터 디렉터리

보조 데이터는 `data/` 디렉터리에 둡니다. `.yml`, `.yaml`, `.json`, `.toml`로 끝나는 파일은 자동으로 로드되어 `site.data`로 노출됩니다.

#### 파일 구조

```text
data/
├── authors.yml
├── products.json
├── config.toml
└── users/
    ├── alice.yml
    ├── bob.yml
    └── cho.yml
```

#### 데이터 접근

데이터는 확장자를 뺀 파일 이름으로 접근합니다.

예를 들어 `data/products.json`이 다음과 같다면:

```json
[
  {"name": "Widget", "price": 10},
  {"name": "Gadget", "price": 20}
]
```

템플릿에서 이렇게 접근합니다.

```jinja
{% for product in site.data.products %}
  <h2>{{ product.name }}</h2>
  <p>{{ product.price }}</p>
{% endfor %}
```

#### 하위 디렉터리

`data/` 아래의 하위 디렉터리는 중첩된 맵이 됩니다. 각 파일은 확장자를 뺀 파일 이름을 키로 하는 자식이 되고, 부모 디렉터리 자체는 순회할 수 있습니다.

위 구조에서 `data/users/alice.yml`, `data/users/bob.yml`, `data/users/cho.yml`은 다음과 같이 노출됩니다.

- `site.data.users.alice`, `site.data.users.bob`, `site.data.users.cho` — 개별 파일 내용
- `site.data.users` — 모든 사용자를 순회할 수 있는 맵

```jinja
{% for name, user in site.data.users %}
  <h3>{{ name }}</h3>
  <p>{{ user.bio }}</p>
{% endfor %}
```

디렉터리는 얼마든지 중첩됩니다: `data/users/admins/root.yml` → `site.data.users.admins.root`.

**타임아웃.** 소스마다 연결 10초, 읽기 1회당 30초, 그리고 전체 120초가 주어집니다. 마지막 제한은 모든 리디렉션 구간과 본문 전체를 아우르므로, 읽기 타임아웃을 아슬아슬하게 피하며 바이트를 흘려보내는 소스가 빌드를 붙잡아 둘 수 없습니다. 어느 하나라도 초과하면 다른 실패와 마찬가지로 `on_error`가 처리합니다.

**충돌.** 디렉터리와 파일이 같은 이름을 공유하면(예: `data/users.yml`과 `data/users/`가 나란히 있는 경우) **디렉터리가 우선**하고 파일은 무시됩니다. 가려진 파일이 조용히 사라지지 않도록 Hwaro는 빌드 중에 경고를 출력합니다.

### 원격 데이터 소스

`site.data`는 `config.toml`에 선언한 HTTP(S) 엔드포인트에서도 채울 수 있습니다. 각 소스는 **빌드당 한 번, 렌더링이 시작되기 전에** 가져옵니다. 템플릿은 네트워크 요청을 일으키지 않고, 빌드가 접근하는 모든 엔드포인트를 한곳에서 볼 수 있습니다.

캐시 동작, 오프라인 오류 정책, 타임아웃, 보안 범위를 포함한 독립 설정 안내는
[원격 데이터 소스](/ko/features/remote-data/)를 참고하세요.

```toml
[[data.remote]]
key = "team"                # site.data.team으로 노출
url = "https://api.example.com/team"
format = "json"             # json | toml | yaml | csv (생략 가능, 아래 추론 참고)
headers = { Authorization = "Bearer ${API_TOKEN}" }
cache = "1h"                # 캐시된 사본이 이 시간보다 젊으면 요청을 건너뜀
on_error = "fail"           # fail | warn-and-use-cache | warn-and-skip
```

템플릿에서는 로컬 데이터 파일과 똑같이 `site.data.team`으로 사용합니다. 따라서 어떤 키를 `data/team.json`과 원격 소스 사이에서 옮겨도 템플릿은 손댈 필요가 없습니다. 레코드를 템플릿에 공급하는 대신 페이지 자체로 만들려면 [콘텐츠 생성](/ko/features/content-generation/)을 참고하세요.

| 필드 | 필수 | 의미 |
|------|------|------|
| `key` | 예 | `site.data` 아래의 이름. 문자, 숫자, `_`, `-`만 허용하며 각 키는 한 번만 선언할 수 있습니다. 키는 대소문자를 구분하지 않고 비교합니다. macOS와 Windows에서는 `Team`과 `team`이 같은 캐시 파일을 쓰게 되므로 중복으로 거부됩니다. |
| `url` | 예 | 절대 `http://` 또는 `https://` URL. 다른 스킴은 설정을 읽는 시점에 거부됩니다. |
| `format` | 아니요 | `json`, `toml`, `yaml`, `csv`. 생략하면 응답의 `Content-Type`, 그다음 (리디렉션을 모두 따라간 뒤) 실제로 도달한 URL의 파일 확장자에서 추론합니다. 둘 다 실패하면 `format`을 명시하라는 안내와 함께 가져오기가 실패합니다. |
| `headers` | 아니요 | 추가 요청 헤더. 자격 증명으로 취급되어 로그에 남지 않으며, 리디렉션이 원래 출처(origin)를 벗어나면 전송하지 않습니다. |
| `cache` | 아니요 | `"90s"`, `"30m"`, `"1h"`, `"7d"` 같은 디스크 캐시 TTL(`"1h30m"`처럼 조합 가능). 캐시가 신선한 동안에는 요청 자체를 건너뜁니다. `cache`가 없으면 매 빌드마다 다시 가져오지만, 마지막 페이로드는 `warn-and-use-cache`를 위해 항상 저장됩니다. |
| `on_error` | 아니요 | 가져오기나 파싱이 실패했을 때의 동작. `fail`(기본값)은 빌드를 중단하고, `warn-and-use-cache`는 경고 후 마지막으로 성공한 페이로드(나이 무관)로 빌드하며, `warn-and-skip`은 경고 후 이번 빌드에서 `site.data.<key>`를 비워 둡니다. |

CSV 페이로드는 행의 배열로 파싱되며 각 행은 공백을 제거한 문자열 셀의 배열입니다. `load_data()`가 `.csv` 파일에 대해 만드는 것과 같은 모양입니다.

**환경 변수.** `url`과 `headers` 값의 `${VAR}`는 환경 변수로 치환됩니다. 참조한 변수가 설정되어 있지 않으면 변수 이름을 명시한 오류와 함께 빌드가 실패합니다(`config.toml`의 다른 곳에서는 경고에 그칩니다). 기본값이 필요하면 `${VAR:-default}`를 쓰세요. 이 오류는 소스를 실제로 가져오는 시점에 발생하므로, 네트워크를 쓰지 않는 `hwaro deploy`, `hwaro new`, `hwaro tool ...`은 변수를 내보내지 않아도 그대로 동작합니다.

**캐싱.** 페이로드는 `.hwaro/remote_data/` 아래에 캐시됩니다. `data/`를 비롯해 `hwaro serve`가 감시하는 어떤 디렉터리에도 속하지 않으므로, TTL 안의 serve 재빌드는 API를 다시 호출하는 대신 캐시를 재사용하고, 캐시 기록이 재빌드를 유발하지도 않습니다. 이 캐시는 `hwaro build --full`에도 지워지지 않으며(페이지 캐시만 초기화됩니다), `on_error = "warn-and-use-cache"`와 함께 오프라인 빌드를 가능하게 하는 것도 이 캐시입니다. `.hwaro/`는 생성 시 자기 자신을 무시하는 `.hwaro/.gitignore`가 함께 쓰이므로 캐시가 `git status`에 나타나지 않습니다. 긴 `hwaro serve` 세션에서는 각 소스를 한 번 가져와 메모리에서 재사용합니다. `cache` TTL이 있는 항목은 TTL이 만료된 뒤 첫 전체 재빌드에서 다시 가져오고, TTL이 없는 항목은 저장할 때마다가 아니라 세션당 한 번만 가져옵니다. 세션이 이미 페이로드를 갖고 있는 상태에서 재요청이 실패하면 `on_error` 설정과 무관하게 경고를 남기고 기존 페이로드를 계속 사용하므로, 오프라인에서도 편집을 이어갈 수 있습니다. `hwaro build`는 빌드마다 별도 프로세스이므로 영향이 없으며 `cache`/`on_error`를 그대로 따릅니다. 페이로드가 바뀌면 `data/` 파일을 편집했을 때와 같은 방식으로 캐시된 페이지가 무효화됩니다.

**충돌.** 원격 `key`가 디스크에도 존재하면(예: `key = "team"` 옆에 `data/team.json`) 두 소스를 모두 명시한 설정 오류가 발생합니다. 하나의 키는 정확히 하나의 소스만 가져야 하므로, `site.data.team`이 어느 쪽이 이기는지에 따라 조용히 달라지는 일은 없습니다.

원격 소스는 의도적으로 설정 전용입니다. `load_data()`와 숏코드는 URL을 받을 수 없습니다. 소스마다 GET 요청 하나 이상이 필요하다면(페이지네이션, POST 본문, 응답 가공) [사전 빌드 훅](/ko/features/build-hooks/#api에서-데이터-가져오기)으로 `data/`에 받아 두세요.

### 사이트 작성자

Hwaro는 프론트 매터의 `authors` 필드(`authors = ["id"]`)에 정의된 모든 작성자를 `site.authors`로 자동 집계합니다.

#### 작성자 정의

`data/authors.yml`(또는 `.json`, `.toml`) 파일을 만들어 작성자 데이터를 보강할 수 있습니다. 키는 페이지 프론트 매터에서 쓴 작성자 ID와 일치해야 합니다.

**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"
```

#### 템플릿에서 사용

`site.authors` 객체는 사이트에서 발견된 모든 작성자를 담습니다. 각 작성자 객체는 다음을 갖습니다.
- `key`: 작성자 ID(예: "john-doe")
- `name`: 작성자 이름(데이터에서 가져오거나, 없으면 ID로 폴백)
- `pages`: 이 작성자가 쓴 페이지 목록(날짜순 정렬)
- `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 %}
```

### 예시

```jinja
<title>{{ site.title }}</title>
<link rel="canonical" href="{{ site.base_url }}{{ page.url }}">
```

---

## Section

관련 콘텐츠를 묶는, `_index.md`가 있는 디렉터리입니다.

### 속성

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| section.title | String | 섹션 제목 |
| section.description | String? | 섹션 설명 |
| section.pages | Array<Page> | 이 섹션의 페이지 |
| section.pages_count | Int | 페이지 수 |
| section.list | String | 미리 렌더링된 HTML 목록(`section_list`) |
| section.subsections | Array<Section> | 자식 섹션 |
| section.assets | Array<String> | 섹션의 정적 파일 |
| section.page_template | String? | 페이지 기본 템플릿 |
| section.paginate_path | String | 페이지네이션 URL 패턴 |
| section.redirect_to | String? | 리다이렉트 URL |

`section.html`에서 현재 섹션의 URL이 필요하면 `page.url`을 사용합니다.

### 플랫 별칭

| 변수 | 동일 표현 |
|----------|------------|
| section_title | section.title |
| section_description | section.description |
| section_list | 미리 렌더링된 페이지 HTML 목록 |

### 프론트 매터에서 오는 속성

| 속성 | 타입 | 기본값 | 설명 |
|----------|------|---------|-------------|
| sort_by | String? | "date" | 정렬 기준: date(최신순), weight(낮은 값 우선), title(A→Z) |
| reverse | Bool? | false | 기본 정렬 순서 뒤집기 — [콘텐츠 작성 › 섹션 › 정렬 방향](/ko/writing/sections/#정렬-방향) 참고 |
| paginate | Int? | — | 한 페이지에 표시할 페이지 수 |
| transparent | Bool | false | 페이지를 부모 섹션으로 전달 |
| generate_feeds | Bool | false | RSS 피드 생성 |

### 페이지 순회

```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 %}
```

### 하위 섹션 순회

```jinja
{% for sub in section.subsections %}
<div class="category">
  <a href="{{ sub.url }}">{{ sub.title }}</a>
  <span>({{ sub.pages_count }} articles)</span>
</div>
{% endfor %}
```

### section_list 사용

단순한 목록에는 미리 렌더링된 HTML을 사용합니다.

```jinja
<ul>{{ section_list | safe }}</ul>
```

마크업을 직접 구성하려면 `section.pages`를 순회합니다.

```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

개별 콘텐츠 파일(`.md`)입니다.

### 핵심 속성

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| page.title | String | 페이지 제목 |
| page.description | String? | 페이지 설명 |
| page.url | String | 상대 URL 경로 |
| page.permalink | String? | base_url을 포함한 절대 URL |
| page.section | String | 부모 섹션 이름 |
| page.date | String? | 발행일(YYYY-MM-DD) |
| page.updated | String? | 마지막 수정일 |
| page.language | String | 적용된 언어 코드 |
| page.translations | Array<TranslationLink> | 언어별 번역본 |
| page.version | Object? | 문서 버전 (버전이 없으면 `nil`) — [page.version](#pageversion) 참고 |
| page.version_links | Array<VersionLink> | 버전 전환기 행 (버전이 없으면 빈 배열) |

렌더링된 HTML 콘텐츠는 최상위 `content` 변수로 제공됩니다.

### 메타데이터 속성

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| page.draft | Bool | 초안 여부 |
| page.weight | Int | 정렬 가중치 |
| page.image | String? | 대표 이미지 경로 |
| page.authors | Array<String> | 작성자 이름 |
| page.taxonomies | Object | 이 페이지의 택소노미 항목(`page.taxonomies.tags`, `page.taxonomies.<name>`) |
| page.extra | Object | 커스텀 프론트 매터 필드 |

### 계산 속성

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| page.word_count | Int | 단어 수 |
| page.reading_time | Int | 읽기 시간(분) |
| page.summary | String? | 요약 HTML: `<!-- more -->` 앞부분, 없으면 `page.description`, 그것도 없으면 렌더링된 본문의 자동 발췌문(`[content] summary_length`, 이스케이프된 `<p>` 하나). 삽입할 때는 `\| safe`와 함께 사용(예: `{{ page.summary \| safe }}`). `<meta name="description">`에는 `page.description`을 직접 사용 |
| page.summary_truncated | Bool | `page.summary`가 잘린 자동 발췌문일 때만 `true` ("더 읽기" 링크에 유용) |
| page.assets | Array<String> | 페이지 번들의 정적 파일 |
| page.series | String | 프론트 매터의 시리즈 이름(없으면 빈 문자열) |
| page.series_index | Int | 시리즈 안에서 1부터 시작하는 순번(`[series]` 활성화 필요) |
| page.series_pages | Array<Page> | 같은 시리즈의 모든 페이지(`series_weight` 순 정렬) |
| page.related_posts | Array<Page> | 택소노미 항목을 공유하는 페이지(`[related]` 활성화 필요) |
| page.git | Object? | 소스 파일의 커밋 메타데이터(`[git]` 활성화 필요, 커밋되지 않았거나 생성된 페이지는 `nil`). 필드: `hash`, `short_hash`, `lastmod`(Time), `first_commit`(Time), `author_name`, `author_email` — [Git 메타데이터](/ko/features/git-info/) 참고 |

### 불리언 플래그

| 속성 | 타입 | 기본값 | 설명 |
|----------|------|---------|-------------|
| page.toc | Bool | false | 목차 표시 여부 |
| page.render | Bool | true | 렌더링 여부 |
| page.is_index | Bool | — | 인덱스 파일 여부 |
| page.generated | Bool | false | 자동 생성된 페이지 여부 |
| page.in_sitemap | Bool | true | 사이트맵 포함 여부 |
| page.in_search_index | Bool | true | 검색 인덱스 포함 여부 |

### 내비게이션 속성

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| page.lower | Page? | 읽기 순서상 이전 페이지 |
| page.higher | Page? | 읽기 순서상 다음 페이지 |
| page.ancestors | Array<Page> | 부모 섹션 체인 |
| page.translations | Array<TranslationLink> | 언어별 번역본 |

### 커스텀 메타데이터

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| page.extra | Object | 커스텀 프론트 매터 필드 |

### 플랫 별칭

| 변수 | 동일 표현 |
|----------|------------|
| 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 | 현재 택소노미 이름(택소노미 페이지) |
| taxonomy_term | 현재 택소노미 항목(택소노미 항목 페이지) |
| content | 렌더링된 HTML 콘텐츠 |

---

## 내비게이션 객체

### page.lower / page.higher

내비게이션은 mdBook이나 Docusaurus처럼 사이트 전체를 하나로 펼친 읽기 순서를 따릅니다. 페이지는 섹션 트리를 깊이 우선으로 순회하는 순서로 정렬됩니다: **섹션 인덱스 → 섹션 페이지 → 하위 섹션(재귀)**. 각 섹션 안에서는 그 섹션의 `sort_by` 설정(weight, date, title)에 따라 정렬됩니다.

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| .title | String | 페이지 제목 |
| .url | String | 페이지 URL |
| .description | String? | 페이지 설명 |
| .date | String? | 페이지 날짜 |

```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

브레드크럼에 쓰는 부모 섹션 목록:

```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.version

`[[versions.list]]`가 있는 사이트에서만 제공됩니다([버전별 문서](/ko/features/versioned-docs/) 참고). 어떤 버전 디렉터리에도 속하지 않는 페이지에서는 `nil`입니다.

| 속성 | 타입 | 설명 |
|------|------|------|
| .name | String | 버전 이름 (URL 세그먼트, 예: "v2") |
| .label | String | 표시 라벨 |
| .latest | Bool | 최신 버전인지 |
| .url | String | 페이지 언어 기준 버전 루트 URL |

### page.version_links

설정된 버전마다 한 행씩, 설정 순서대로.

| 속성 | 타입 | 설명 |
|------|------|------|
| .name | String | 버전 이름 |
| .label | String | 표시 라벨 |
| .latest | Bool | 최신 버전인지 |
| .url | String | 그 버전에 같은 페이지가 있으면 그 URL, 없으면 그 버전의 루트 |
| .exists | Bool | 대응 페이지 존재 여부 |
| .current | Bool | 현재 페이지의 버전인지 |

```jinja
{% for v in page.version_links %}
<a href="{{ base_url }}{{ v.url }}"{% if v.current %} aria-current="page"{% endif %}>{{ v.label }}</a>
{% endfor %}
```

전역 `versions` 리스트(`{% for v in versions %}`, `versions.latest`, `versions.all`)는 현재 페이지 언어 기준 모든 버전의 루트 URL을 노출합니다.

### page.translations

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| .code | String | 언어 코드(예: "en") |
| .url | String | 번역된 페이지 URL |
| .title | String | 해당 언어의 제목 |
| .is_current | Bool | 현재 페이지의 언어인지 |
| .is_default | Bool | 기본 언어인지 |

```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 %}
```

---

## page.extra 접근

프론트 매터의 커스텀 메타데이터:

```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>
```

프론트 매터 최상위에 쓴 `outputs = ["json"]`도 마찬가지로 알려지지 않은 일반 키로 취급되어 `page.extra.outputs`에 들어가며, 해당 페이지/섹션에 한해 `[outputs]` 설정 기본값을 재정의합니다. [출력 포맷](/ko/features/output-formats/)을 참고합니다.

---

### 시간 변수

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| current_year | Int | 현재 연도(예: 2025) |
| current_date | String | 현재 날짜(YYYY-MM-DD) |
| current_datetime | String | 현재 날짜와 시간 |

```jinja
<footer>&copy; {{ current_year }} {{ site.title }}</footer>
```

---

### SEO 변수

**미리 렌더링된 HTML**(하위 호환):

| 변수 | 설명 |
|----------|-------------|
| og_tags | OpenGraph 메타 태그 |
| twitter_tags | Twitter Card 메타 태그 |
| og_all_tags | OG와 Twitter 태그 전부 |
| canonical_tag | 캐노니컬 링크 태그 |
| hreflang_tags | Hreflang 대체 링크 태그(다국어) |
| pagination_seo_links | `<link rel="prev/next">` 태그 |

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

메타 태그 마크업을 직접 구성할 때 쓰는 **구조화된 데이터**:

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| seo.canonical_url | String | 전체 캐노니컬 URL(base_url + 페이지 URL) |
| seo.og_type | String | OpenGraph 타입(기본: "article") |
| seo.og_image | String | 절대 경로로 해석된 이미지 URL |
| seo.twitter_card | String | Twitter 카드 타입(기본: "summary_large_image") |
| seo.twitter_site | String | Twitter 사이트 핸들 |
| seo.twitter_creator | String | Twitter 작성자 핸들 |
| seo.fb_app_id | String | Facebook 앱 ID |
| seo.hreflang | Array | `page.translations`와 동일 |

페이지 제목, 설명, URL, 이미지는 `page.title`, `page.description`, `page.url`, `page.image`로 얻습니다. `seo` 객체는 SEO에 특화된 계산 값(해석된 URL, 설정 값)을 제공합니다.

```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>
```

---

### 에셋 변수

편의를 위해 미리 렌더링된 `<link>`·`<script>` 태그입니다. `config.toml` 설정에서 생성됩니다.

| 변수 | 설명 |
|----------|-------------|
| highlight_css | 구문 강조 CSS `<link>` 태그 |
| highlight_js | 구문 강조 JS `<script>` 태그 |
| highlight_tags | CSS와 JS 태그 전부 |
| auto_includes_css | 자동 인클루드된 CSS `<link>` 태그 |
| auto_includes_js | 자동 인클루드된 JS `<script>` 태그 |
| auto_includes | 모든 자동 인클루드 태그 |
| pwa_tags | PWA manifest 링크, theme-color 메타, 서비스 워커 등록 태그(`[pwa]` 비활성 시 빈 문자열) |

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

---

### 목차

프론트 매터에 `toc = true`가 있을 때만 사용할 수 있습니다.

**미리 렌더링된 HTML**(하위 호환):

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| toc | String | 생성된 목차 HTML |
| toc_obj.html | String | 같은 목차 HTML의 객체 형태 |

```jinja
{% if page.toc %}
<aside class="toc">
  {{ toc | safe }}
</aside>
{% endif %}
```

목차 마크업을 직접 구성할 때 쓰는 **구조화된 데이터**:

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| toc_obj.headers | Array | 구조화된 목차 헤더 객체 |
| toc_obj.headers[].level | Int | 헤딩 레벨(2-6) |
| toc_obj.headers[].id | String | 앵커 ID |
| toc_obj.headers[].title | String | 헤딩 텍스트 |
| toc_obj.headers[].permalink | String | 전체 앵커 퍼머링크 |
| toc_obj.headers[].children | Array | 중첩된 자식 헤더(같은 구조) |

```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 %}
```

---

### Paginator

섹션·택소노미 항목 템플릿에서 페이지네이션이 활성화된 경우([섹션 프론트 매터](/ko/writing/sections/#프론트-매터)의 `paginate`, 택소노미는 `paginate_by`) 사용할 수 있습니다. 1페이지는 섹션 URL에, 이후 페이지는 `{url}/{paginate_path}/{n}/`에 생성됩니다.

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| paginator.paginate_by | Int | 페이지당 항목 수 |
| paginator.base_url | String | 페이저 기본 URL(`{url}/{paginate_path}/`) |
| paginator.number_pagers | Int | 전체 페이지 수 |
| paginator.first | String | 첫 페이지 URL |
| paginator.last | String | 마지막 페이지 URL |
| paginator.previous | String? | 이전 페이지 URL(첫 페이지에서는 nil) |
| paginator.next | String? | 다음 페이지 URL(마지막 페이지에서는 nil) |
| paginator.pages | Array<Page> | 현재 페이저의 페이지 목록 |
| paginator.current_index | Int | 현재 페이지 번호(1부터 시작) |
| paginator.total_pages | Int | `number_pagers`와 동일 |

같은 데이터를 `pagination_obj` 변형으로도 쓸 수 있습니다. `previous_url`, `next_url`, `first_url`, `last_url`, `current_page`, `total_pages`, `total_items`, `per_page`, `has_previous`, `has_next`, 그리고 `html`(미리 렌더링된 내비게이션, 플랫 변수 `pagination`으로도 제공)을 노출합니다.

```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 %}
```

---

### 택소노미 변수

택소노미 템플릿에서 사용할 수 있습니다.

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| taxonomy_name | String | 택소노미 이름(예: "tags") |
| taxonomy_term | String | 현재 항목 이름(인덱스 페이지에서는 빈 문자열) |
| content | String | 미리 렌더링된 목록 HTML(항목 또는 페이지) |

목록을 직접 구성하려면 `get_taxonomy()`를 사용합니다. [택소노미](/ko/writing/taxonomies/)를 참고합니다.

---

## 메뉴

`site.menus`는 **기본 언어**의 이름 있는 메뉴(설정의 `[[menus.*]]` + 프론트 매터의 `menus`/`menu` 등록)를 노출합니다. 템플릿 안에서는 `site.menus.<name>`보다 `get_menu(name="...")`을 권장합니다. **현재 페이지**의 언어를 기준으로 해석하고, 없으면 기본 언어로 폴백합니다.

```jinja
{% for item in get_menu(name="main") %}
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
{% endfor %}
```

### 엔트리 속성

| 속성 | 타입 | 설명 |
|----------|------|--------------|
| name | String | 표시 레이블 |
| url | String | 아무것도 붙지 않은 루트 상대 경로, 또는 손대지 않은 외부 URL — `page.url`과 비교 가능 |
| href | String | 내부 링크면 `url`에 사이트 `base_path`를 적용한 값, 외부면 그대로 — `<a href>`에는 이 값을 사용 |
| identifier | String | 메뉴 안에서 고유한 키 |
| weight | Int | 정렬 순서 |
| external | Bool | `http://`, `https://`, `//` URL이면 `true` |
| children | Array\<Entry\> | `parent`가 이 엔트리의 `identifier`와 일치하는 중첩 엔트리 |
| page | Page? | 등록한 페이지의 데이터(프론트 매터로 등록된 엔트리만; 설정으로만 등록됐거나 섹션에서 등록된 엔트리는 nil) |

전체 설정/프론트 매터 레퍼런스, 계층 구조, 언어별 동작은 [메뉴](/ko/features/menus/)를 참고합니다.

---

## 타입 레퍼런스

### 요약표

| 타입 | 설명 |
|------|-------------|
| String | 텍스트 값 |
| String? | 선택적 텍스트(nil 가능) |
| Int | 정수 |
| Bool | true/false |
| Array<T> | T 타입의 목록 |
| Object | 키-값 맵 |

### 템플릿에서 확인

```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) }}
```

---

## 함께 보기

- [문법](/ko/templates/syntax/) — Jinja2 기본
- [함수](/ko/templates/functions/) — 데이터 조회 함수
- [필터](/ko/templates/filters/) — 값 변환

---

Title: 필터
URL: https://hwaro.hahwul.com/ko/templates/filters/
Source: content/templates/filters.ko.md
Language: ko

필터는 템플릿에서 값을 변환합니다. 파이프 `|` 연산자로 적용합니다.

Hwaro는 표준 Crinja(Jinja2) 내장 필터(`upper`, `lower`, `join`, `map`, `select`, `batch` 등) 위에 자체 필터를 얹어 제공하므로, 아래 어디서든 두 종류 모두 사용할 수 있습니다.

## 문법

```jinja
{{ value | filter }}
{{ value | filter(arg="value") }}
{{ value | filter1 | filter2 }}
```

## 텍스트 필터

| 필터 | 설명 | 예시 |
|--------|-------------|---------|
| upper | 대문자로 변환 | {{ "hello" \| upper }} → HELLO |
| lower | 소문자로 변환 | {{ "HELLO" \| lower }} → hello |
| capitalize | 첫 글자를 대문자로 | {{ "hello" \| capitalize }} → Hello |
| trim | 앞뒤 공백 제거 | {{ "  hi  " \| trim }} → hi |
| replace | 텍스트 치환 | {{ "hello" \| replace("l", "x") }} → hexxo |
| slugify | URL 슬러그로 변환 | {{ "Hello World" \| slugify }} → hello-world |
| truncate_words | 단어 수 제한. `end`로 말줄임 문자 지정(기본 `...`) | {{ text \| truncate_words(20, end="…") }} |

## HTML 필터

| 필터 | 설명 | 예시 |
|--------|-------------|---------|
| safe | HTML을 이스케이프하지 않음 | {{ content \| safe }} |
| strip_html | HTML 태그 제거 | {{ html \| strip_html }} |
| markdownify | 마크다운 렌더링 | {{ text \| markdownify }} |
| xml_escape | XML 이스케이프 | {{ text \| xml_escape }} |

`markdownify`는 사이트의 [`[markdown]`](/ko/features/markdown-extensions/)
설정 중 safe 모드와 `smart_punctuation`을 따르므로, 같은 텍스트가 페이지
본문에서 렌더링되는 결과와 일치합니다. 나머지 확장 파이프라인(각주, 정의
목록, 컨테이너 등)은 적용되지 않습니다.

## 배열 필터

| 필터 | 설명 | 예시 |
|--------|-------------|---------|
| length | 길이 | {{ items \| length }} |
| first | 첫 요소(빈 컬렉션이면 빈 값) | {{ items \| first }} |
| last | 마지막 요소(빈 컬렉션이면 빈 값) | {{ items \| last }} |
| reverse | 순서 뒤집기 | {{ items \| reverse }} |
| sort | 배열 정렬 | {{ items \| sort }} |
| join | 요소 이어 붙이기 | {{ tags \| join(", ") }} |
| split | 문자열 분할 | {{ "a,b,c" \| split(pat=",") }} |
| where | 필드 값으로 객체 필터링 | {{ posts \| where(attribute="draft", value=false) }} |
| sort_by | 필드로 객체 정렬 | {{ posts \| sort_by(attribute="date", reverse=true) }} |
| group_by | 필드로 객체 그룹화 | {{ posts \| group_by(attribute="section") }} |

## 컬렉션 필터

| 필터 | 설명 | 예시 |
|--------|-------------|---------|
| unique | 중복 제거 | {{ items \| unique }} |
| flatten | 중첩 배열 평탄화 | {{ nested \| flatten }} |
| compact | nil/빈 값 제거 | {{ items \| compact }} |

## 수학 필터

| 필터 | 설명 | 예시 |
|--------|-------------|---------|
| ceil | 올림하여 정수로 | {{ 3.2 \| ceil }} → 4 |
| floor | 내림하여 정수로 | {{ 3.8 \| floor }} → 3 |

## i18n 필터

| 필터 | 설명 | 예시 |
|--------|-------------|---------|
| t | 키 번역 | {{ "nav.home" \| t }} |
| pluralize | 단수/복수형 선택 | {{ count \| pluralize(singular="item", plural="items") }} |

`t` 필터는 `i18n/` 디렉터리의 TOML 파일에서 번역 키를 찾습니다. 현재 페이지의 언어를 먼저 보고 기본 언어로 폴백하며, 번역이 없으면 키 자체를 반환합니다. i18n 파일 구성은 [다국어](/ko/features/multilingual/)를 참고합니다.

## 디버그 필터

| 필터 | 설명 | 예시 |
|--------|-------------|---------|
| inspect | 디버그용 표현 | {{ value \| inspect }} |

## URL 필터

| 필터 | 설명 | 예시 |
|--------|-------------|---------|
| absolute_url | base를 포함한 전체 URL | {{ "/about/" \| absolute_url }} |
| relative_url | base_url 접두사 추가 | {{ "/img.png" \| relative_url }} |
| active_path | 이 URL이 현재 페이지(또는 그 상위)인지 | {{ item.url \| active_path }} |

`active_path`는 URL(보통 [메뉴](/ko/features/menus/) 엔트리의 `item.url`)을 현재 페이지와 비교합니다. 기본은 정확히 일치할 때만 참이고, `ancestor=true`를 넘기면 하위 페이지도 매칭합니다.

```jinja
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
<a href="{{ item.href }}"{% if item.url | active_path(ancestor=true) %} class="open"{% endif %}>{{ item.name }}</a>
```

비교 전에 양쪽 모두 끝 슬래시 하나로 정규화되므로 `/posts`와 `/posts/`는 같습니다. 루트 경로(`/`)는 `ancestor=true`여도 정확히 일치할 때만 매칭됩니다. 외부 `item.url`(`http://`, `https://`, `//`)은 절대 매칭되지 않습니다.

## 데이터 필터

| 필터 | 설명 | 예시 |
|--------|-------------|---------|
| default | 폴백 값 | {{ value \| default(value="N/A") }} |
| jsonify | JSON 인코딩 | {{ data \| jsonify }} |
| date | 날짜 포맷 | {{ page.date \| date("%Y-%m-%d") }} |

## 예시

### safe 필터

렌더링된 콘텐츠에는 항상 `safe`를 사용합니다.

```jinja
{{ content | safe }}
{{ og_tags | safe }}
{{ toc | safe }}
```

### 기본값

```jinja
{{ page.description | default(value=site.description) }}
{{ page.image | default(value="/images/default.png") }}
```

### 날짜 포맷

```jinja
<time>{{ page.date | date("%B %d, %Y") }}</time>
```

포맷 코드:
- `%Y` — 연도(2024)
- `%m` — 월(01-12)
- `%d` — 일(01-31)
- `%B` — 월 이름(January)
- `%b` — 월 축약형(Jan)

### URL 처리

```jinja
<a href="{{ page.url | absolute_url }}">Permalink</a>
<img src="{{ "/logo.png" | relative_url }}">
```

### 문자열과 체이닝

```jinja
{{ page.title | lower | slugify }}
{{ content | strip_html | truncate_words(100) }}
{{ description | default(value="No description") | upper }}

{% set tags = "a,b,c" | split(pat=",") %}
{% for tag in tags %}
  <span>{{ tag | trim }}</span>
{% endfor %}
```

### 컬렉션 질의

```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 %}

{# Unique tags across all pages #}
{% set all_tags = site.pages | map(attribute="tags") | flatten | unique %}
```

### 번역

```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>
```

---

## 테스트

테스트는 `{% if %}` 문에서 조건을 평가합니다.

| 테스트 | 설명 | 예시 |
|------|-------------|---------|
| startswith | ~로 시작 | `{% if page.url is startswith("/blog/") %}` |
| endswith | ~로 끝남 | `{% if page.url is endswith("/") %}` |
| containing | 포함 | `{% if page.url is containing("docs") %}` |
| matching | 정규식 일치 | `{% if asset is matching("[.](jpg\|png)$") %}` |
| empty | 비어 있음 | `{% if page.description is empty %}` |
| present | 비어 있지 않음 | `{% if page.title is present %}` |

### 테스트 예시

```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 %}
```

### 내장 테스트

```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 %}
```

---

## 함께 보기

- [데이터 모델](/ko/templates/data-model/) — 사용할 수 있는 변수
- [함수](/ko/templates/functions/) — 템플릿 함수
- [문법](/ko/templates/syntax/) — 템플릿 기본

---

Title: 함수
URL: https://hwaro.hahwul.com/ko/templates/functions/
Source: content/templates/functions.ko.md
Language: ko

템플릿에서 데이터를 조회하고 URL을 생성하는 내장 함수입니다.

## 데이터 조회

### get_page()

경로나 URL로 아무 페이지나 가져옵니다.

```jinja
{% set about = get_page(path="about.md") %}
{% if about %}
<a href="{{ about.url }}">{{ about.title }}</a>
{% endif %}
```

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| path | String | 소스 상대 경로(예: `about.md`) 또는 URL 경로(예: `/about/`) |

**반환값:** Page? (못 찾으면 nil). 표준 [Page 속성](/ko/templates/data-model/#page)을 노출하되, 렌더링 시점에 계산되는 필드(`permalink`, `lower`/`higher`, `ancestors`, `series_index`, `series_pages`, `related_posts`)는 제외됩니다.

**예시:**

```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()

섹션 이름, 소스 경로, 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 %}
```

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| path | String | 섹션 이름(`blog`), 경로(`blog/_index.md`), 또는 URL(`/blog/`) |

**반환값:** Section? (못 찾으면 nil)

**반환 속성:**

| 속성 | 타입 |
|----------|------|
| title | String |
| description | String? |
| url | String |
| path | String |
| name | String |
| pages | Array<Page> |
| pages_count | Int |
| assets | Array<String> |

**예시:**

```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()

택소노미 항목과 그에 속한 페이지에 접근합니다.

```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 %}
```

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| kind | String | 택소노미 이름(예: "tags", "categories") |

**반환값:** Taxonomy? (못 찾으면 nil)

**반환 속성:**

| 속성 | 타입 |
|----------|------|
| name | String |
| items | Array<Term> |

`items`의 순서는 해당 택소노미의
[`terms_sort_by`](/ko/writing/taxonomies/#정렬)를 따릅니다. `"name"`(기본값,
가나다순) 또는 `"count"`(페이지 수 내림차순, 동수일 때 이름 오름차순)입니다.
개수는 모든 언어를 합산한 사이트 전체 기준으로, 루트 택소노미 인덱스
페이지와 동일합니다.

**Term 속성:**

| 속성 | 타입 |
|----------|------|
| name | String |
| slug | String |
| pages | Array<Page> |
| count | Int |

---

### get_taxonomy_url()

택소노미 항목의 URL을 생성합니다.

```jinja
<a href="{{ get_taxonomy_url(kind='tags', term='crystal') }}">
  Crystal articles
</a>
```

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| kind | String | 택소노미 이름 |
| term | String | 항목 이름 |

**반환값:** String(절대 URL)

---

### get_menu()

이름 있는 메뉴의 해석된 엔트리 트리에 접근합니다([메뉴](/ko/features/menus/)).

```jinja
{% for item in get_menu(name="main") %}
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
{% endfor %}
```

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| name | String | 메뉴 이름(예: "main", "footer") |

**반환값:** Array\<Entry\>. **현재 페이지**의 언어를 기준으로 해석하고, 그 언어에 `name` 메뉴 엔트리가 없으면 기본 언어로 폴백합니다. 알 수 없거나 등록되지 않은 메뉴 이름은 빈 배열을 반환하므로(nil이 아님) `{% for %}` 루프에서 오류가 나지 않습니다.

**엔트리 속성:**

| 속성 | 타입 | 설명 |
|----------|------|--------------|
| name | String | 표시 레이블 |
| url | String | 아무것도 붙지 않은 루트 상대 경로, 또는 손대지 않은 외부 URL |
| href | String | 내부 링크면 `url`에 `base_path`를 적용한 값, 외부면 그대로 — `<a href>`에는 이 값을 사용 |
| identifier | String | 메뉴 안에서 고유한 키 |
| weight | Int | 정렬 순서 |
| external | Bool | `http://`, `https://`, `//` URL이면 `true` |
| children | Array\<Entry\> | 중첩 엔트리 |
| page | Page? | 등록한 페이지의 데이터(프론트 매터로 등록된 엔트리만) |

현재 페이지와 무관하게 **기본 언어**의 메뉴가 꼭 필요할 때만 `site.menus.<name>`을 사용합니다. 공용 내비게이션 파셜 안에서는 거의 언제나 `get_menu()`가 맞는 선택입니다.

---

## 데이터 로딩

### load_data()

외부 데이터 파일(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 %}
```

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| path | String | 데이터 파일 경로 |

**반환값:** 파싱된 데이터 또는 nil

`load_data()`는 로컬 파일 시스템만 읽으며, 경로는 프로젝트 디렉터리 안에서 해석됩니다. 프로젝트 밖의 파일도, URL도 읽을 수 없습니다. HTTP(S) GET 요청 하나의 페이로드라면 [`[[data.remote]]`](/ko/features/remote-data/)로 `site.data`에 노출하세요. 여러 요청이나 변형이 필요하면 [빌드 훅](/ko/features/build-hooks/)으로 `data/`에 내려받습니다. `data/` 아래 파일은 `load_data()` 호출 없이도 `site.data`로 노출됩니다.

**지원 포맷:**

| 확장자 | 포맷 |
|-----------|--------|
| .json | JSON |
| .toml | TOML |
| .yaml, .yml | YAML |
| .csv | CSV(배열의 배열) |

**예시:**

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 %}
```

---

## 환경 변수

### env()

템플릿에서 환경 변수를 읽습니다.

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

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| name | String | 환경 변수 이름 |
| default | String? | 변수가 없을 때의 폴백 값(선택) |

**반환값:** String(환경 변수 값, 기본값, 또는 빈 문자열)

변수가 없고 기본값도 지정하지 않으면 빈 문자열을 반환하고 빌드 경고를 남깁니다.

**예시:**

```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 함수

### url_for()

base_url이 포함된 URL을 생성합니다.

```jinja
<a href="{{ url_for(path='/about/') }}">About</a>
<img src="{{ url_for(path='/images/logo.png') }}">
```

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| path | String | 변환할 경로 |

**반환값:** String(절대 URL)

---

### get_url()

`url_for()`의 별칭입니다. 어느 이름을 써도 됩니다.

```jinja
<a href="{{ get_url(path='/about/') }}">About</a>
```

---

### asset()

번들되거나 핑거프린트된 에셋을 최종 URL로 해석합니다. [에셋 파이프라인](/ko/features/asset-pipeline/)이 활성화되어 있으면 입력한 이름을 빌드 매니페스트에서 찾아 항상 해시가 붙은 파일 이름을 돌려줍니다.

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

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| name | String | 번들 또는 에셋 이름(예: `main.css`, `app.js`) |

**반환값:** String. `base_url` 아래의 절대 URL. 매니페스트에 항목이 없으면 이름을 그대로 `base_url` 아래 경로로 반환하므로, 파이프라인을 켜기 전에도 템플릿이 그대로 동작합니다.

---

### asset_url()

`asset()`의 별칭입니다. 템플릿에서 더 읽기 좋은 쪽을 사용하면 됩니다.

---

### now()

현재 날짜와 시간을 가져옵니다.

```jinja
{# Default format #}
<p>Generated: {{ now() }}</p>

{# Custom format #}
<p>Year: {{ now(format="%Y") }}</p>
<p>Date: {{ now(format="%B %d, %Y") }}</p>
```

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| format | String? | 날짜 포맷 문자열(선택) |

**반환값:** String

**포맷 코드:**

| 코드 | 설명 | 예시 |
|------|-------------|---------|
| %Y | 연도 | 2025 |
| %m | 월(01-12) | 01 |
| %d | 일(01-31) | 15 |
| %B | 월 이름 | January |
| %b | 월 축약형 | Jan |
| %H | 시(00-23) | 14 |
| %M | 분 | 30 |
| %S | 초 | 45 |

---

## 미디어 함수

### resize_image()

리사이즈된 이미지 변형을 돌려줍니다. [이미지 처리](/ko/features/image-processing/)가 활성화되어 있으면 자동 생성된 리사이즈 이미지의 URL을, 아니면 원본 URL을 반환합니다.

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

**파라미터:**

| 이름 | 타입 | 설명 |
|------|------|-------------|
| path | String | 이미지 경로(예: `/images/photo.jpg`) |
| width | Int | 요청 너비(픽셀, 0 = 원본) |
| height | Int | 요청 높이(픽셀, 0 = 원본) |

**반환값:** 다음 속성을 가진 객체:

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| url | String | 리사이즈된 변형의 URL(사용할 수 없으면 원본) |
| width | Int | 선택된 변형의 실제 너비. 변형이 없으면 요청한 너비 |
| height | Int | 요청한 높이(전달하지 않으면 0) |
| lqip | String | 작은 JPEG 플레이스홀더의 Base64 데이터 URI(LQIP 비활성 시 빈 문자열) |
| dominant_color | String | 이미지 주요 색상의 16진수 색상 문자열, 예: `#a3b2c1`(LQIP 비활성 시 빈 문자열) |

이 함수는 설정된 `widths` 중 가장 가까운 너비를 고릅니다. `width=500`을 요청했고 설정된 너비가 `[320, 640, 1024]`라면 640px 변형(요청 이상인 가장 작은 너비)을 반환합니다. 충분히 큰 것이 없으면 가장 큰 변형으로 폴백합니다.

변형은 절대 확대하지 않으므로 900px 원본에 `width=1024`를 요청하면 900px 파일이
나오고, `img.width`도 `900`을 반환합니다. 따라서
`<img width="{{ img.width }}">`가 브라우저가 실제로 내려받는 파일과 일치합니다.
`height`는 전달한 값 그대로입니다(전달하지 않으면 `0`). 증분 빌드에서는 변형
맵을 파일 이름으로 복원하기 때문에, 모든 이미지를 디코딩하지 않고서는 실제
높이를 알 수 없습니다.

`lqip`과 `dominant_color` 속성은 `[image_processing.lqip]`이 활성화되어 있어야 합니다. 꺼져 있으면 빈 문자열을 반환합니다.

**예시:**

```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"
>
```

`config.toml`에서 `[image_processing]`을 활성화해야 합니다. 설정 방법은 [이미지 처리](/ko/features/image-processing/)를 참고합니다.

---

## 모범 사례

### 항상 nil 확인

```jinja
{% set page = get_page(path="featured.md") %}
{% if page %}
{{ page.title }}
{% else %}
<p>Coming soon</p>
{% endif %}
```

### 함수 결과 재사용

```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>
```

### 데이터 파일 정리

```
data/
├── navigation/
│   ├── main.json
│   └── footer.json
├── team.yaml
└── products.toml
```

---

## 함께 보기

- [데이터 모델](/ko/templates/data-model/) — Site, Section, Page 타입
- [데이터 모델 › Paginator](/ko/templates/data-model/#paginator) — 섹션 템플릿의 페이지네이션 객체
- [필터](/ko/templates/filters/) — 값 변환

---

Title: 렌더 훅
URL: https://hwaro.hahwul.com/ko/templates/render-hooks/
Source: content/templates/render-hooks.ko.md
Language: ko

렌더 훅을 사용하면 hwaro의 마크다운 파서를 건드리지 않고 개별 마크다운 요소(링크, 이미지, 헤딩, 펜스 코드 블록, 인용문, 표)가 HTML로 바뀌는 방식을 재정의할 수 있습니다. `templates/hooks/`에 템플릿을 두면 모든 페이지의 해당 요소가 내장 마크업 대신 그 템플릿을 거쳐 렌더링됩니다.

`templates/hooks/render-*` 템플릿을 하나도 만들지 않으면 아무것도 바뀌지 않습니다. hwaro는 지금까지와 완전히 동일하게 렌더링합니다.

## 파일 구조

```
templates/
└── hooks/
    ├── render-link.html        # [text](url "title")
    ├── render-image.html       # ![alt](url "title")
    ├── render-heading.html     # ## Heading
    ├── render-codeblock.html   # ```lang ... ```
    ├── render-blockquote.html  # > quoted
    └── render-table.html       # | GFM | tables |
```

파일마다 독립적으로 동작하므로 재정의하고 싶은 것만 추가하면 됩니다. `render-image.html`만 있는 사이트는 이미지 래퍼만 커스텀되고 나머지는 기본 렌더링을 유지합니다.

그 밖의 `hooks/render-*` 이름은 인식되지 않으며 빌드 시 경고를 남깁니다.

## 컨텍스트 변수

모든 값은 Crinja `Value`이고, 다른 hwaro 템플릿과 마찬가지로 **필요한 곳은 이미 HTML 이스케이프되어** 있습니다. `| e` 필터를 쓰기 전에 아래 [규칙 1](#규칙)을 먼저 확인합니다.

### `render-link.html`

| 변수 | 설명 |
|----------|--------------|
| `destination` | 링크 대상. 이스케이프됨. `markdown.safe = true`이고 대상이 안전하지 않은 프로토콜(`javascript:` 등)을 쓰면 빈 문자열 |
| `title` | 링크의 `"title"` 텍스트. 이스케이프됨. 없으면 빈 문자열 |
| `text` | 이미 렌더링된 링크 내부 HTML(중첩 마크업이 들어 있을 수 있고, 링크가 이미지를 감싸면 훅으로 렌더링된 `<img>`가 들어 있을 수도 있음) |

### `render-image.html`

| 변수 | 설명 |
|----------|--------------|
| `destination` | 이미지 `src`. 이스케이프됨(안전하지 않은 프로토콜 규칙은 링크와 동일) |
| `alt` | 이미지의 alt 텍스트. 마크다운 소스의 alt에 인라인 마크업이 중첩돼 있어도 순수 텍스트만(CommonMark와 동일: 이미지의 "자식"은 태그를 만들지 않음) |
| `title` | 이미지의 `"title"` 텍스트. 이스케이프됨. 없으면 빈 문자열 |

### `render-heading.html`

| 변수 | 설명 |
|----------|--------------|
| `level` | 헤딩 레벨 정수(`1`–`6`) |
| `text` | 이미 렌더링된 헤딩 내부 HTML |
| `id` | 헤딩의 id. 마크다운 소스의 커스텀 `{#id}`이거나, 자동 생성 후 중복 제거된 슬러그(`heading`, `heading-1`, `heading-2`, …) |

### `render-codeblock.html`

| 변수 | 설명 |
|----------|--------------|
| `lang` | 펜스의 언어 토큰. 이스케이프됨(`` ```python ``의 `python`). 언어 없는 펜스는 빈 문자열 |
| `options` | 언어 뒤의 Zola/Pandoc 스타일 `{...}` 옵션 블록 원문([구문 강조](/ko/features/syntax-highlighting/) 참고), `{...}` 블록이 없으면 정보 문자열의 나머지 텍스트. 이스케이프됨 |
| `code` | 펜스 본문. HTML 이스케이프됨 |
| `highlighted` | 서버 모드로 구문 강조된 본문(hljs 클래스 span). `[highlight] mode`가 `"server"`가 아니거나, 강조가 꺼져 있거나, 해당 언어의 렉서가 없으면 빈 문자열. `{hide_lines=…}` 펜스 옵션은 이미 적용된 상태로, 서버 모드에서 숨긴 줄은 템플릿(그리고 `code`)에 절대 도달하지 않음 |
| `name` | 파싱된 `{name=...}`/`{title=...}` 파일 이름 레이블. 이스케이프됨. 없으면 빈 문자열 |
| `copy` | 이 블록에 복사 버튼이 적용되면 `"true"`(`[highlight] copy` / 펜스별 `{copy=...}`, mermaid에는 절대 적용 안 됨), 아니면 빈 문자열. 어떤 마크업을 출력할지는 템플릿이 결정 |

### `render-blockquote.html`

| 변수 | 설명 |
|----------|--------------|
| `text` | 이미 렌더링된 인용문 내부 HTML. 블록 수준 콘텐츠(문단, 목록, 중첩 인용)이며 보통 개행으로 끝남 |

### `render-table.html`

| 변수 | 설명 |
|----------|--------------|
| `html` | 완성된 기본 `<table>...</table>` 마크업 전체 |
| `header_html` | 표의 `<thead>...</thead>` 부분 |
| `body_html` | 표의 `<tbody>...</tbody>` 부분. 헤더만 있는 표는 빈 문자열 |

모든 훅 템플릿은 추가로 표준 `page`(`url`, `title`, `path`, `language`)와 `config`(`base_url`, `title`) 변수도 볼 수 있습니다.

## 기본 출력과 동일한 템플릿

다음 템플릿들은 hwaro의 기본 출력을 그대로 재현하므로 수정의 출발점으로 쓰기 좋습니다.

```jinja
{# templates/hooks/render-link.html #}
<a href="{{ destination }}"{% if title is present %} title="{{ title }}"{% endif %}>{{ text }}</a>
```

```jinja
{# templates/hooks/render-image.html #}
<img src="{{ destination }}" alt="{{ alt }}"{% if title is present %} title="{{ title }}"{% endif %} />
```

```jinja
{# templates/hooks/render-heading.html #}
<h{{ level }} id="{{ id }}">{{ text }}</h{{ level }}>
```

```jinja
{# templates/hooks/render-codeblock.html #}
<pre><code{% if lang is present %} class="language-{{ lang }} hljs"{% endif %}>{% if highlighted is present %}{{ highlighted }}{% else %}{{ code }}{% endif %}</code></pre>
```

```jinja
{# templates/hooks/render-blockquote.html #}
<blockquote>
{{ text }}</blockquote>
```

```jinja
{# templates/hooks/render-table.html #}
{{ html }}
```

`{% if title %}`이 아니라 `{% if title is present %}`인 점에 주의합니다. Crinja의 참/거짓 판정은 `false`/`0`/nil만 거짓으로 보기 때문에, 그냥 `{% if title %}`을 쓰면 title이 없을 때도 `title=""`이 렌더링됩니다. 커스텀 `is present`/`is empty` 테스트(hwaro 자체 템플릿 전반에서도 사용)가 이를 올바르게 확인합니다.

codeblock 템플릿의 ` hljs` 클래스는 기본 설정(`[highlight] enabled = true`. 대부분의 Highlight.js 테마가 이 클래스를 기준으로 기본 스타일을 적용)에서의 기본 출력과 일치합니다. 강조를 완전히 껐다면 기본 출력은 ` hljs` 없이 `class="language-{{ lang }}"`을 내보내므로, 바이트 단위로 동일하게 맞추려면 훅에서도 빼면 됩니다.

## 예시: figure로 감싼 이미지

```jinja
{# templates/hooks/render-image.html #}
<figure>
  <img src="{{ destination }}" alt="{{ alt }}" loading="lazy" />
  {% if title is present %}<figcaption>{{ title }}</figcaption>{% endif %}
</figure>
```

이제 마크다운의 모든 `![alt](src "caption")`이 캡션 달린 `<figure>`로 렌더링되므로 콘텐츠 파일마다 이미지 마크업을 따로 쓸 필요가 없습니다.

## 규칙

1. **값은 이미 이스케이프되어 있으니 그대로 출력합니다.** hwaro 템플릿은 (다른 곳과 마찬가지로) 자동 이스케이프가 꺼져 있고, `destination`/`title`/`alt`/`lang`/`options`/`code`는 렌더러가 이미 HTML 이스케이프한 값입니다. 이들을 `| e`에 통과시키면 이중 이스케이프가 되고, `text`나 `highlighted`를 통과시키면 이미 렌더링된 HTML이 깨집니다.
2. **관례대로 큰따옴표로 감싼 `href`/`src` 속성을 유지합니다.** 이후 단계 전부(`@/internal-page.md` 링크 해석, 루트 상대 링크의 서브패스(`base_path`) 접두사 처리, 반응형 이미지 `srcset`/`sizes` 주입, `loading="lazy"`)가 *최종* HTML을 대상으로 `href="..."` / `src="..."` 패턴을 찾는 일반 텍스트 패스로 동작합니다. 따옴표 없는 속성이나 작은따옴표 속성을 내보내는 훅, 또는 대상을 일반적인 속성 값이 아닌 형태로 바꿔 버리는 훅은 해당 요소를 이 모든 처리에서 제외시킵니다. `@/` 접두사가 붙은 `destination`은 `InternalLinkResolver`가 찾아 해석할 수 있도록 반드시 `href="..."` 안에 들어가야 합니다.
3. **`render-heading.html`은 `<hN id="{{ id }}">` 요소를 출력해야 합니다.** 목차(`{{ toc }}` / `page.toc`)와 `insert_anchor_links`는 둘 다 최종 HTML에서 `id` 속성이 있는 `<h1>`~`<h6>` 태그를 찾아 후처리합니다. 헤딩 태그가 아닌 것을 렌더링하거나 `id`를 빼먹는 훅은 조용히 둘 다에서 빠집니다.
4. **`{{ text }}`를 변형하지 않습니다.** 이미 렌더링된 HTML이고, 숏코드를 쓰는 페이지에서는 나중 패스에서 숏코드 출력으로 치환될 내부 플레이스홀더 주석(`<!--HWARO-SHORTCODE-PLACEHOLDER-N-->`)이 들어 있을 수 있습니다. `text`를 필터링·잘라내기·재이스케이프하면 그 플레이스홀더가 깨지거나 미아가 될 수 있습니다.
5. **Mermaid는 자기 펜스를 직접 처리합니다.** `[markdown] mermaid = true`이면 `` ```mermaid `` 펜스는 항상 기존 Mermaid 파이프라인(`<div class="mermaid">…</div>`)을 거치고 `render-codeblock.html`은 절대 거치지 않습니다. "모든 훅은 일치하는 모든 요소에 항상 적용된다"의 설정으로 결정되는 예외입니다. `mermaid = false`로 설정하면 codeblock 훅이 mermaid 펜스도 다른 언어처럼 렌더링합니다.
6. **어드모니션은 자기 인용문을 직접 처리합니다.** `[markdown] admonitions = true`(기본값)이면 `> [!NOTE]` 스타일 인용문은 계속 어드모니션 파이프라인(`<div class="admonition admonition-note">…</div>`)을 거치고 `render-blockquote.html`은 절대 거치지 않습니다. Mermaid와 같은, 설정으로 결정되는 패턴입니다. `admonitions = false`로 설정하면 그런 인용문도 다른 인용문처럼 훅을 거칩니다.
7. **`render-table.html` 출력에 빈 줄을 넣지 않습니다.** 표 훅의 출력은 본 파싱 *이전에* 마크다운에 삽입되는데, HTML 블록은 첫 빈 줄에서 끝나므로 그 뒤는 다시 마크다운으로 파싱됩니다. hwaro가 안전장치로 출력에서 빈 줄을 제거해 주므로 여러 줄 템플릿도 동작하지만, 빈 줄에 의존하는 마크업은 쓰지 않는 것이 좋습니다.
8. **훅은 표 셀, 각주 본문, 정의 목록, 프론트 매터의 `description`/요약 텍스트 안에는 적용되지 않습니다.** 이들은 훅이 붙는 본 Markd 파서를 전혀 거치지 않는 별도의 단순한 인라인 마크다운 경로로 렌더링됩니다(`render-table.html`이 표 자체를 감싸더라도 표 *셀*은 그 경로를 유지합니다). 버그가 아니라 알려진 제약입니다.

## 증분 빌드

`templates/hooks/` 아래 파일 편집은 `hwaro build --cache`와 `hwaro serve`에서 다른 템플릿 편집과 똑같이 추적됩니다. 다만 훅은 어떤 페이지 템플릿에서도 `{% include %}`/`{% extends %}`로 도달하지 않기 때문에, hwaro가 영향을 받는 페이지를 좁혀낼 수 없습니다. `templates/hooks/render-*.html` 파일을 편집하면 `[build] template_deps` 설정과 무관하게 **모든** 페이지가 다시 렌더링됩니다. [증분 빌드](/ko/features/incremental-build/)를 참고합니다.

## 함께 보기

- [구문 강조](/ko/features/syntax-highlighting/) — `render-codeblock.html`에 전달되는 펜스 언어/옵션 파싱
- [마크다운 확장](/ko/features/markdown-extensions/) — `{#custom-id}` 헤딩과 Mermaid 다이어그램
- [템플릿](/ko/templates/) — 템플릿 디렉터리 구조와 선택 규칙

---

Title: 문법
URL: https://hwaro.hahwul.com/ko/templates/syntax/
Source: content/templates/syntax.ko.md
Language: ko

Hwaro는 Jinja2 호환 템플릿 엔진인 Crinja를 사용합니다. 이 페이지는 핵심 문법을 다룹니다.

## 변수

이중 중괄호로 값을 출력합니다.

```jinja
{{ page.title }}
{{ site.description }}
{{ content }}
```

## 주석

```jinja
{# This is a comment #}
```

## 조건문

```jinja
{% if page.description %}
<meta name="description" content="{{ page.description }}">
{% endif %}
```

else와 함께:

```jinja
{% if page.draft %}
<span class="badge">Draft</span>
{% else %}
<span class="badge">Published</span>
{% endif %}
```

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 %}
```

## 반복문

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

인덱스와 함께:

```jinja
{% for tag in page.tags %}
{% if not loop.first %}, {% endif %}
{{ tag }}
{% endfor %}
```

반복 변수:

| 변수 | 설명 |
|----------|-------------|
| loop.index | 현재 반복 횟수(1부터 시작) |
| loop.index0 | 현재 반복 횟수(0부터 시작) |
| loop.first | 첫 반복에서 true |
| loop.last | 마지막 반복에서 true |
| loop.length | 전체 항목 수 |

## 템플릿 상속

### 베이스 템플릿

`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>
```

### 자식 템플릿

`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 %}
```

## 인클루드

부분 템플릿을 불러옵니다.

```jinja
{% include "partials/header.html" %}
<main>{{ content | safe }}</main>
{% include "partials/footer.html" %}
```

## 변수

변수를 설정합니다.

```jinja
{% set author = page.authors | first %}
<span>By {{ author }}</span>
```

## 필터

파이프 연산자로 값을 변환합니다.

```jinja
{{ page.title | upper }}
{{ content | safe }}
{{ page.date | date("%B %d, %Y") }}
{{ page.authors | join(", ") }}
```

전체 필터 목록은 [필터](/ko/templates/filters/)를 참고합니다.

## 테스트

조건을 평가합니다.

```jinja
{% if page.url is startswith("/blog/") %}
<span>Blog post</span>
{% endif %}

{% if page.description is empty %}
<meta name="description" content="{{ site.description }}">
{% endif %}
```

테스트는 필터가 아니지만 같은 페이지에 문서화되어 있습니다. [필터 › 테스트](/ko/templates/filters/#테스트)를 참고합니다.

## 공백 제어

마이너스 기호로 공백을 제거합니다.

```jinja
{%- if condition -%}
trimmed
{%- endif -%}
```

## raw 블록

Jinja 문법을 그대로 출력합니다.

```jinja
{% raw %}
{{ this will not be parsed }}
{% endraw %}
```

## 연산자

### 비교

| 연산자 | 설명 |
|----------|-------------|
| `==` | 같음 |
| `!=` | 같지 않음 |
| `<` | 미만 |
| `>` | 초과 |
| `<=` | 이하 |
| `>=` | 이상 |

### 논리

| 연산자 | 설명 |
|----------|-------------|
| `and` | 둘 다 참 |
| `or` | 둘 중 하나라도 참 |
| `not` | 부정 |

```jinja
{% if page.section == "blog" and not page.draft %}
<article>{{ content | safe }}</article>
{% endif %}
```

### 포함 여부

```jinja
{% if "tutorial" in page.tags %}
<span class="badge">Tutorial</span>
{% endif %}
```

## 자주 쓰는 패턴

### 활성 내비게이션

```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>
```

### 조건부 메타 태그

```jinja
<head>
  {% if page.description %}
  <meta name="description" content="{{ page.description }}">
  {% endif %}
  {{ og_all_tags | safe }}
</head>
```

### 섹션별 레이아웃

```jinja
<body data-section="{{ page.section }}">
  {% if page.section == "docs" %}
  {% include "partials/sidebar.html" %}
  {% endif %}
  
  <main>{{ content | safe }}</main>
</body>
```

### 빈 목록 확인과 반복

```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 %}
```

## 함께 보기

- [데이터 모델](/ko/templates/data-model/) — 사용할 수 있는 변수
- [함수](/ko/templates/functions/) — 내장 함수
- [필터](/ko/templates/filters/) — 필터와 테스트

---

Title: 콘텐츠 작성
URL: https://hwaro.hahwul.com/ko/writing/
Source: content/writing/_index.ko.md
Language: ko

콘텐츠는 `content/` 디렉터리에 둡니다. TOML(`+++`), YAML(`---`), JSON(`{...}`) 프론트 매터를 붙인 마크다운으로 작성합니다. 기본은 TOML이고 YAML도 널리 권장되며, JSON은 선호하는 사용자를 위해 지원합니다.

## 콘텐츠 유형

| 유형 | 파일 | URL |
|------|------|-----|
| 페이지 | about.md | /about/ |
| 섹션 | blog/_index.md | /blog/ |
| 섹션 페이지 | blog/post.md | /blog/post/ |

## 기본 콘텐츠 파일

```markdown
+++
title = "My Page"
date = "2024-01-15"
+++

Content in **Markdown**.
```

## 시작 순서

**페이지**에서 콘텐츠 파일과 프론트 매터의 기본을 먼저 익힙니다. 이어서 **섹션**을 읽고 블로그나 문서처럼 콘텐츠를 그룹으로 묶는 방법을 배웁니다. 그다음에는:

- **택소노미** — 태그, 카테고리, 커스텀 그룹으로 페이지 분류
- **숏코드** — 마크다운 안에 재사용 가능한 컴포넌트(YouTube, 알림, 갤러리) 삽입
- **아키타입** — `hwaro new`가 콘텐츠를 빠르게 스캐폴드하도록 템플릿 정의

---

Title: 아키타입
URL: https://hwaro.hahwul.com/ko/writing/archetypes/
Source: content/writing/archetypes.ko.md
Language: ko

아키타입은 새 페이지의 기본 프론트 매터와 콘텐츠 구조를 정의하는 콘텐츠 템플릿입니다. `hwaro new`로 콘텐츠를 만들 때 아키타입이 일관된 출발점을 제공합니다.

`hwaro init`은 기본 `archetypes/default.md`를(블로그 스캐폴드의 `posts.md`처럼 스캐폴드별 아키타입도 함께) 만들어 주므로, `hwaro new`는 별도 설정 없이 `description` 필드가 포함된 프론트 매터(기본 TOML, YAML과 JSON도 지원)를 바로 사용합니다. 사이트 관례에 맞게 수정하거나 확장하면 됩니다.

## 개요

아키타입은 프로젝트 루트의 `archetypes/` 디렉터리에 둡니다:

```
my-site/
├── archetypes/
│   ├── default.md      # Default template
│   ├── posts.md        # For content/posts/
│   └── tools/
│       └── develop.md  # For content/tools/develop/
├── content/
├── templates/
└── config.toml
```

## 아키타입 작성

아키타입은 프론트 매터와 선택적 본문이 있는 마크다운 파일입니다. 새 콘텐츠를 만들 때 치환되는 플레이스홀더를 사용합니다.

### 사용 가능한 플레이스홀더

| 플레이스홀더 | 설명 |
|-------------|-------------|
| `{{ title }}` | 콘텐츠 제목(`-t` 플래그 또는 파일명에서) |
| `{{ date }}` | 현재 로컬 날짜(`YYYY-MM-DD`) 또는 `--date` 값 그대로 |
| `{{ tags }}` | `--tags`로 받은 태그의 TOML 배열(없으면 `[]`) |
| `{{ draft }}` | `--draft`를 줬거나 대상 경로에 `drafts` 디렉터리가 포함되면 `true`, 그 외에는 `false` |
| `{{ description }}` | 대화형 `hwaro new` 마법사에서 입력받은 설명. 없으면 빈 문자열 |

### 아키타입 예시

`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...
```

## 아키타입 매칭

`hwaro new`를 실행하면 아키타입이 다음 순서로 매칭됩니다:

### 1. 명시적 플래그(`-a`)

```bash
hwaro new -t "My Article" -a posts
```

출력 경로와 무관하게 `archetypes/posts.md`를 사용합니다.

### 2. 경로 기반 매칭

```bash
hwaro new posts/hello-world.md
```

`archetypes/posts.md`가 있는지 확인합니다.

### 3. 중첩 경로 매칭

```bash
hwaro new tools/develop/mytool.md
```

다음 순서로 시도합니다:
1. `archetypes/tools/develop.md`
2. `archetypes/tools.md`
3. `archetypes/default.md`

### 4. 기본 아키타입

일치하는 아키타입이 없으면 `archetypes/default.md`를 사용합니다.

### 5. 내장 템플릿

아키타입이 하나도 없으면 내장 기본 템플릿을 사용합니다. 이 템플릿의 포맷과 기본 필드는 `config.toml`의 `[content.new]`로 제어합니다:

```toml
[content.new]
front_matter_format = "toml"         # "toml"(기본값), "yaml", "json"
default_fields = ["description"]      # 빈 값으로 스캐폴드할 추가 키
bundle = false                        # true: foo.md 대신 foo/index.md 스캐폴드
```

내장 필드(`title`, `date`, `draft`, `tags`)와 겹치는 항목은 빈 값으로 중복 생성되지 않도록 무시됩니다.

### 리프 번들(디렉터리) 레이아웃

다국어 형제 파일(`index.ko.md`)이나 페이지 옆에 함께 둘 이미지를 계획하고 있다면 페이지당 디렉터리 레이아웃이 필요합니다:

```
content/abcd/
└── index.md
```

레이아웃은 실행 단위, 아키타입 단위, 사이트 단위로 고를 수 있습니다:

- **CLI:** `hwaro new posts/hello.md --bundle`(단일 파일 형태를 강제하려면 `--no-bundle`).
- **아키타입:** 아키타입 첫 줄에 `<!-- hwaro: bundle -->`을 두면 그 아키타입을 쓰는 모든 `hwaro new`가 번들 모드를 기본으로 사용합니다. 이 지시자는 생성된 콘텐츠에서 제거됩니다.
- **설정:** `[content.new]` 아래 `bundle = true`로 사이트 전체 기본을 정합니다.

우선순위는 CLI > 아키타입 > 설정 > 단일 파일(기본값) 순입니다.

## 사용 예시

### 기본 사용법

```bash
# 경로 기반 아키타입 매칭 사용
hwaro new posts/my-first-post.md

# 제목을 명시적으로 지정
hwaro new posts/my-post.md -t "My First Post"

# 특정 아키타입 사용
hwaro new -t "Quick Note" -a posts
```

### 콘텐츠 유형별 생성

```bash
# 블로그 글 (archetypes/posts.md 사용)
hwaro new posts/new-article.md

# 문서 (archetypes/docs.md 사용)
hwaro new docs/getting-started.md

# 도구 페이지 (archetypes/tools.md 또는 archetypes/tools/develop.md 사용)
hwaro new tools/develop/my-tool.md
```

## 추천 아키타입

### 블로그 글(`archetypes/posts.md`)

```markdown
+++
title = "{{ title }}"
date = {{ date }}
draft = false
authors = []
tags = []
categories = []
description = "{{ description }}"
image = ""
+++

# {{ title }}

Introduction paragraph.

## Content
```

### 문서(`archetypes/docs.md`)

```markdown
+++
title = "{{ title }}"
date = {{ date }}
weight = 10
toc = true
+++

Brief description of this documentation page.

## Overview

## Usage

## Examples
```

### 기본(`archetypes/default.md`)

```markdown
+++
title = "{{ title }}"
date = "{{ date }}"
draft = {{ draft }}
description = "{{ description }}"
tags = {{ tags }}
+++

# {{ title }}
```

`hwaro init`이 만들어 주는 `archetypes/default.md`와 같은 내용입니다. `{{ description }}` 플레이스홀더는 플래그 방식에서는 빈 문자열로, 대화형 `hwaro new` 마법사에서는 입력한 값으로 치환됩니다.

## 팁

- **일관된 메타데이터**: 자주 쓰는 프론트 매터 필드를 아키타입에 모두 정의합니다
- **섹션별 아키타입**: 콘텐츠 섹션마다 알맞은 기본값을 가진 아키타입을 만듭니다
- **중첩 구성**: 콘텐츠 구조에 맞춰 `archetypes/` 안에 하위 디렉터리를 사용합니다
- **초안 처리**: `{{ draft }}`는 `--draft`를 줬을 때, 대화형 마법사에서 초안 토글을 켰을 때, 대상 경로에 `drafts/` 세그먼트가 포함될 때 `true`가 됩니다

## 함께 보기

- [페이지](/ko/writing/pages/) — 프론트 매터 필드 레퍼런스
- [CLI](/ko/start/cli/) — `hwaro new` 명령

---

Title: 페이지
URL: https://hwaro.hahwul.com/ko/writing/pages/
Source: content/writing/pages.ko.md
Language: ko

페이지는 사이트의 HTML 페이지가 되는 마크다운 파일입니다. 이 문서는 **콘텐츠 작성 방법**, 즉 프론트 매터 필드, 마크다운 문법, 파일 구성을 다룹니다. 이 필드를 템플릿에서 읽는 방법은 [데이터 모델](/ko/templates/data-model/#page)을 참고합니다.

## 기본 구조

```markdown
+++
title = "My Page"
date = "2024-01-15"
+++

Your content in **Markdown**.
```

`+++` 블록이 TOML 프론트 매터입니다. YAML(`---` 구분자)과 JSON(파일 맨 앞의 최상위 `{...}` 객체)도 지원합니다. 그 아래 내용이 HTML로 변환됩니다.

```markdown
---
title: "My Page"
date: "2024-01-15"
---

Your content in **Markdown**.
```

```markdown
{
  "title": "My Page",
  "date": "2024-01-15"
}

Your content in **Markdown**.
```

JSON은 파일 맨 앞에서 처음으로 짝이 맞는 `{...}`가 프론트 매터가 되며, 별도 구분자가 필요 없습니다. 파일은 반드시 `{`로 시작해야 합니다(앞 공백 불가).

## 프론트 매터

### 필수

| 필드 | 타입 | 설명 |
|-------|------|-------------|
| title | string | 페이지 제목 |

### 주요 필드

| 필드 | 타입 | 기본값 | 설명 |
|-------|------|---------|-------------|
| date | string | — | 발행일. `YYYY-MM-DD`, 시간 포함 가능(`YYYY-MM-DD HH:MM:SS` 또는 RFC 3339 datetime). 따옴표 없는 TOML/YAML 날짜도 허용 |
| description | string | — | SEO 설명 |
| draft | bool | false | 프로덕션 빌드에서 제외 |
| template | string | "page" | 사용할 템플릿 |
| weight | int | 0 | 정렬 순서(낮을수록 앞) |
| image | string | — | 소셜 공유용 대표 이미지 |
| tags | array | [] | 태그 택소노미 항목 |
| categories | array | [] | 카테고리 택소노미 항목 |

### 전체 필드

| 필드 | 타입 | 설명 |
|-------|------|-------------|
| updated | string | 마지막 수정일 |
| slug | string | 커스텀 URL 슬러그 |
| path | string | 커스텀 URL 경로 |
| aliases | array | 이 페이지로 리다이렉트할 URL 목록 |
| authors | array | 작성자 이름 |
| toc | bool | 목차 표시 |
| in_search_index | bool | 검색 포함 여부 |
| in_sitemap | bool | 사이트맵 포함 여부 |
| insert_anchor_links | bool | 헤딩 앵커 추가 |
| redirect_to | string | 페이지를 이 URL로 리다이렉트 |
| render | bool | 페이지를 출력으로 렌더링(기본값: true) |
| expires | date | 이 날짜 이후 자동 제외 |
| series | string | 묶음용 시리즈 이름 |
| series_weight | int | 시리즈 내 정렬 순서 |
| extra | table | 커스텀 메타데이터 |

## 예시

### 블로그 글

```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...
```

### 초안

```markdown
+++
title = "Work in Progress"
draft = true
+++

Not visible in production.
```

초안 포함 빌드: `hwaro build --drafts`

### 만료 콘텐츠

```markdown
+++
title = "Limited Time Offer"
expires = 2025-12-31
+++

Automatically excluded from builds after the expiry date.
```

만료된 콘텐츠 포함 빌드: `hwaro build --include-expired`

만료까지 7일 이내인 페이지는 빌드 경고를 냅니다.

### 미래 날짜 콘텐츠

`date`가 미래인 페이지는 빌드에서 자동으로 빠집니다. 콘텐츠 예약 발행에 유용합니다.

```markdown
+++
title = "Coming Soon"
date = 2099-01-01
+++

Published only after the date arrives.
```

미래 콘텐츠 포함 빌드: `hwaro build --include-future`

### 시리즈 글

```markdown
+++
title = "Part 1: Introduction"
series = "Crystal Tutorial"
series_weight = 1
+++

First part of the series.
```

`config.toml`에서 `[series]`를 켜면 빌드 시점에 `page.series_index`(1부터 시작하는 위치)와 `page.series_pages`(시리즈의 전체 페이지)가 계산됩니다. 둘 다 템플릿 전용 값이며 프론트 매터 필드가 아닙니다. [데이터 모델](/ko/templates/data-model/#계산-속성)을 참고합니다.

### 커스텀 템플릿

```markdown
+++
title = "Landing Page"
template = "landing"
+++

Uses `templates/landing.html` instead of `page.html`.
```

### 가중치 정렬

```markdown
+++
title = "Introduction"
weight = 1
+++
```

```markdown
+++
title = "Getting Started"
weight = 2
+++
```

weight가 낮을수록 앞에 옵니다.

### URL 별칭

```markdown
+++
title = "New Page"
aliases = ["/old-url/", "/another-old-url/"]
+++

Redirects from old URLs to this page.
```

각 alias는 **이 사이트 안의 경로**입니다. 빌드가 해당 위치에 리다이렉트
스텁을 씁니다. 절대 URL(`https://example.com/old/`)이나 프로토콜 상대
URL(`//example.com/old/`)은 이 빌드가 게시할 수 있는 대상이 아니므로
경고와 함께 건너뜁니다.

### 커스텀 메타데이터

```markdown
+++
title = "Product Review"

[extra]
rating = 4.5
featured = true
pros = ["Fast", "Reliable"]
+++
```

템플릿에서 접근: `{{ page.extra.rating }}`

## 전체 프론트 매터 레퍼런스

모든 필드를 한 블록에 모았습니다. 복사한 뒤 필요 없는 항목을 지우면 됩니다.

```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"
+++
```

## 콘텐츠 요약

`page.summary`는 목록 페이지, 피드, 소셜 카드에 표시되는 글의 요약입니다. 다음 소스 중 먼저 존재하는 것으로 채워집니다:

1. `<!-- more -->` 마커 앞의 콘텐츠 (HTML로 렌더링)
2. 프론트 매터의 `description` 필드
3. 렌더링된 본문에서 자동으로 잘라낸 발췌문

`<!-- more -->`로 요약 범위를 명시적으로 지정합니다:

```markdown
+++
title = "Long Article"
+++

This is the summary shown in listings.

<!-- more -->

The full article continues here...
```

### 자동 요약

마커도 `description`도 없는 페이지에는 자동 요약이 생성됩니다. 렌더링된 본문의 처음 70단어를 `<p>` 하나로 감싸고, 텍스트가 잘린 경우에만 말줄임표(`…`)를 붙입니다. 발췌문은 렌더링된 HTML에서 만들어지므로 숏코드는 확장되고 코드 블록, 헤딩, 이미지, figure는 건너뛰어 자연스러운 산문으로 읽힙니다.

단어가 공백으로 구분되지 않는 CJK 위주 텍스트(한국어, 일본어, 중국어)는 설정값의 2배를 글자 수로 셉니다. `summary_length = 70`이면 최대 140자입니다. 절단은 단어 경계(CJK는 글자 경계)에서 이루어지며 엔티티나 멀티바이트 문자를 쪼개지 않습니다.

`config.toml`에서 조정하거나 끌 수 있습니다:

```toml
[content]
summary_length = 70      # 단어 수 (CJK: 글자 수 ×2); 0이면 자동 요약 비활성화
summary_ellipsis = "…"   # 텍스트가 실제로 잘린 경우에만 추가
```

`page.summary_truncated`는 자동 발췌문이 잘렸을 때만 `true`이므로, 필요한 곳에만 "더 읽기" 링크를 표시할 수 있습니다. 자동 요약은 마커나 `description`을 대체하지 않으므로 이미 요약이 있는 페이지의 출력은 그대로 유지됩니다.

## 마크다운 문법

### 텍스트

```markdown
**bold** and *italic*
`inline code`
[link](https://example.com)
![image](/img.jpg)
```

### 목록

```markdown
- Unordered
- Items

1. Ordered
2. Items
```

### 코드 블록

````markdown
```javascript
console.log("Hello");
```
````

### 표

```markdown
| Header | Header |
|--------|--------|
| Cell   | Cell   |
```

표 셀 안에서도 인라인 마크다운이 동작합니다: **굵게**, *기울임*, `코드 스팬`, `[links](url)`, `![images](url)`, ~~취소선~~.

```markdown
| Feature        | Example                          |
|----------------|----------------------------------|
| Bold           | **important**                    |
| Italic         | *emphasis*                       |
| Code           | `config.toml`                    |
| Link           | [Hwaro](https://example.com)     |
| Image          | ![logo](/img/logo.png)           |
| Strikethrough  | ~~deprecated~~                   |
```

### 내부 링크

`@/`를 사용하면 다른 콘텐츠 페이지를 소스 경로로 링크할 수 있습니다. Hwaro가 빌드 시점에 올바른 출력 URL로 변환합니다.

```markdown
[Read the post](@/blog/my-post.md)
[About section](@/about/_index.md)
[With anchor](@/blog/my-post.md#introduction)
```

최종 URL을 몰라도 된다는 점이 장점입니다. Hwaro가 콘텐츠 경로에서 URL을 계산합니다. 대상 페이지가 없으면 링크는 그대로 남고 빌드 중 경고가 기록됩니다.

| 문법 | 변환된 URL |
|--------|-------------|
| `@/blog/post.md` | `/blog/post/` |
| `@/blog/_index.md` | `/blog/` |
| `@/blog/post.md#section` | `/blog/post/#section` |

#### 엄격 모드

경고에서 그치지 않고 빌드를 실패시키려면 `config.toml`에서 켭니다:

```toml
[links]
broken_internal = "error"  # 기본값: "warn"
```

error 모드에서는 모든 페이지의 미해결 `@/` 링크를 모아 하나의 목록(`source.md → @/target (reason)`)으로 출력하며 빌드가 실패하고, CI용 종료 코드 5로 매핑됩니다. `hwaro serve` 중에는 실패가 에러 오버레이에 표시되고 서버는 계속 동작합니다.

`--cache` 사용 시 주의: 웜 빌드에서는 다시 렌더링된 페이지만 재검사하므로, 변경되지 않은 페이지 안의 깨진 링크는 그 페이지가 다시 렌더링될 때까지 드러나지 않습니다. 완전한 검사를 위해 CI에서는 `--cache` 없이 콜드 빌드를 실행합니다.

### 인용문

```markdown
> Quote text
```

### 어드모니션

GitHub 스타일 알림 블록(admonition)이 스타일이 적용된 콜아웃으로 렌더링됩니다. 인식하는 타입: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`.

```markdown
> [!NOTE]
> Pay attention to this paragraph.

> [!WARNING]
>
> Body can also live in its own paragraph.

> [!TIP] 커스텀 제목
> 마커와 같은 줄에 적은 텍스트는 제목이 됩니다(Obsidian / Hugo 문법).
```

출력은 `<div class="admonition admonition-{type}">`이며, 제목 문단(`<p class="admonition-title">`) 뒤에 본문이 이어집니다. 커스텀 제목이 없으면 타입 이름(`Note`, `Tip`, …)이 제목으로 쓰입니다. 스타일은 사이트 CSS에서 지정합니다. Hwaro는 시맨틱 마크업만 내보냅니다.

어드모니션과 일반 인용문 안에서도 테이블을 쓸 수 있습니다. 평소처럼 각 행 앞에 `>`를 붙이면 됩니다(`> | a | b |`, `> |---|---|`).

`config.toml`의 `[markdown]` 아래에 `admonitions = false`를 두면 비활성화됩니다.

제한 사항: 타입은 대소문자를 구분하며(`[!NOTE]`만 인식, `[!note]`는 안 됨), 어드모니션 본문 안에 중첩된 인용문이 있으면 바깥 어드모니션이 일찍 닫힙니다. 인라인 이스케이프는 없습니다. 백슬래시 이스케이프(`\[!NOTE\]`)도 같은 문자를 렌더링하면서 여전히 어드모니션을 발동시키므로, 토큰을 문자 그대로 출력해야 한다면 기능 자체를 끄면 됩니다.

### 커스텀 헤딩 ID

헤딩 줄 끝에 `{#custom-id}`를 붙이면 자동 생성 슬러그를 덮어씁니다. 제목을 고쳐도 깨지지 않는 안정적인 앵커 URL이 필요할 때 유용합니다.

```markdown
## Installation Guide {#install}
```

`<h2 id="install">Installation Guide</h2>`로 렌더링됩니다. 목차와 `[link](#install)` 링크 모두 커스텀 id를 사용합니다.

id에 허용되는 문자: 문자(모든 문자 체계), 숫자, `_`, `-`, `:`. id는 숫자로 시작해도 됩니다 — `{#1-create-a-project}`도 유효하며, 번호가 붙은 헤딩을 번역할 때 원문 앵커를 그대로 유지하려면 이 형태가 필요합니다. 다만 `-`나 `:`로 시작할 수는 없습니다. CommonMark는 ATX 헤딩 앞에 공백을 3칸까지 허용하며, 더 깊이 들여 쓰면 그 줄이 코드 블록이 되어 `{#id}`가 적용되지 않습니다.

`config.toml`의 `[markdown]` 아래에 `heading_ids = false`를 두면 비활성화됩니다.

커스텀 헤딩 ID에는 `markdown.safe = false`가 필요합니다. safe 모드에서는 `{#id}` 문법이 출력에서 제거되고 id도 적용되지 않습니다. safe 모드와 명시적 id가 동시에 필요하면 raw HTML 헤딩을 사용합니다. 한 페이지에 같은 `{#id}`를 두 번 쓰면 id 속성이 중복되며, 앵커는 첫 번째가 우선합니다.

`{#id}` 단축 문법은 더 일반적인 `{#id .class key=val}` 속성 블록(`[markdown] attributes = true`)의 특수한 경우이며, 속성 블록은 인라인 이미지에도 적용됩니다. [마크다운 확장](/ko/features/markdown-extensions/)을 참고합니다.

### 정의 목록

```markdown
Term
: Definition body

Another term
: Definition with **bold**, *italic*, `code`, [a link](https://example.com), and ~~strikethrough~~
: A second definition for the same term
```

용어와 정의 양쪽에서 인라인 마크다운이 동작합니다. raw HTML은 안전을 위해 이스케이프됩니다.

## 에셋 코로케이션

이미지, PDF 같은 관련 에셋을 콘텐츠 파일과 같은 디렉터리에 함께 둘 수 있습니다. 이를 **페이지 번들(Page Bundle)**이라고 부릅니다.

이 기능을 쓰려면 마크다운 파일 이름을 `index.md`(일반 페이지) 또는 `_index.md`(섹션 페이지)로 바꾸고, 페이지 이름을 딴 디렉터리 안에 넣습니다.

**구조 예시:**

```text
content/
└── blog/
    ├── my-trip/
    │   ├── index.md        <-- The page content
    │   ├── photo.jpg       <-- Asset
    │   └── data.json       <-- Asset
    └── _index.md
```

Hwaro는 페이지 번들 디렉터리의 마크다운이 아닌 파일 전부를 상대 경로를 유지한 채 출력 디렉터리로 복사합니다.

마크다운에서는 상대 경로로 이 에셋에 링크하면 됩니다:

```markdown
![My Trip Photo](photo.jpg)

[Download Data](data.json)
```

### 템플릿에서 에셋 접근

템플릿에서는 `page.assets`로 함께 둔 에셋 목록에 접근합니다. 파일의 상대 경로 배열을 반환합니다.

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

## URL 매핑

| 파일 | URL |
|------|-----|
| content/index.md | `/` |
| content/about.md | `/about/` |
| content/blog/post.md | `/blog/post/` |

## 함께 보기

- [섹션](/ko/writing/sections/) — 관련 페이지 묶기
- [데이터 모델](/ko/templates/data-model/) — 템플릿에서의 페이지 속성

---

Title: 섹션
URL: https://hwaro.hahwul.com/ko/writing/sections/
Source: content/writing/sections.ko.md
Language: ko

섹션은 관련 콘텐츠를 묶는 디렉터리입니다. `_index.md` 파일이 필요합니다.

## 섹션 생성

```
content/
└── blog/
    ├── _index.md     # Section index → /blog/
    ├── first.md      # Page → /blog/first/
    └── second.md     # Page → /blog/second/
```

## 섹션 인덱스

모든 섹션에는 `_index.md`가 필요합니다:

```markdown
+++
title = "Blog"
description = "Latest articles"
sort_by = "date"
+++

Welcome to my blog.
```

## 프론트 매터

| 필드 | 타입 | 기본값 | 설명 |
|-------|------|---------|-------------|
| title | string | — | 섹션 제목(필수) |
| description | string | — | 섹션 설명 |
| template | string | "section" | 사용할 템플릿 |
| page_template | string | — | 하위 페이지의 기본 템플릿 |
| sort_by | string | "date" | 정렬 기준: date, weight, title ([정렬 방향](#정렬-방향) 참고) |
| reverse | bool | false | 기본 정렬 방향 뒤집기 ([정렬 방향](#정렬-방향) 참고) |
| paginate | int | — | 한 페이지에 표시할 항목 수 |
| paginate_path | string | "page" | 페이저 URL의 경로 세그먼트(기본값이면 `/blog/page/2/` 형태) |
| transparent | bool | false | 페이지를 상위 섹션으로 넘김 |
| generate_feeds | bool | false | RSS 피드 생성 |
| redirect_to | string | — | 섹션을 렌더링하는 대신 이 URL로 가는 HTML 리다이렉트 페이지 생성 |
| draft | bool | false | 프로덕션에서 제외 |
| weight | int | 0 | 섹션 정렬 순서 |
| cascade | table | — | 하위 항목이 상속하는 기본값 ([캐스케이드](#캐스케이드) 참고) |

## 캐스케이드

섹션의 `[cascade]` 테이블은 그 아래 모든 페이지와 섹션의 프론트 매터 기본값을 정합니다. 페이지 자신의 프론트 매터가 항상 우선하고, 더 깊은 캐스케이드가 얕은 캐스케이드를 덮어씁니다. 캐스케이드를 선언한 섹션 자신은 영향을 받지 않습니다.

```toml
+++
title = "Blog"

[cascade]
template = "post"
tags = ["blog"]

[cascade.extra]
banner = "default-banner.png"
+++
```

이제 이 섹션 아래 모든 페이지는 `post` 템플릿으로 렌더링되고, `blog` 태그를 가지며, `page.extra.banner`를 노출합니다. 페이지가 해당 필드를 직접 지정하지 않았을 때에 한합니다. `extra`와 `taxonomies`는 키 단위로 병합됩니다: 페이지 자신의 키가 우선하고, 캐스케이드된 키가 빈자리를 채웁니다.

캐스케이드 가능한 키: `template`, `draft`, `render`, `toc`, `insert_anchor_links`, `in_sitemap`, `in_search_index`, `tags`, `taxonomies`, `authors`, `extra`. URL에 영향을 주는 키(`slug`, `path`, `aliases`)는 캐스케이드할 수 없으며 경고와 함께 무시됩니다.

다국어 사이트에서 캐스케이드는 자기 언어 트리 안에서만 적용됩니다. `_index.ko.md`는 `.ko` 페이지에, `_index.md`는 기본 언어 페이지에 캐스케이드됩니다.

## 정렬 방향

`sort_by` 값마다 자연스러운 기본 방향이 다르며, 작성자가 보통 기대하는 방향에 맞춰져 있습니다:

| `sort_by` | 기본 순서 | `reverse = true`일 때 |
|-----------|---------------|------------------------|
| `date`    | 최신순(내림차순) | 오래된 순 |
| `weight`  | 낮은 weight 우선(오름차순) | 높은 weight 우선 |
| `title`   | A → Z(오름차순) | Z → A |

`reverse`는 선택한 `sort_by`의 자연스러운 방향을 그대로 뒤집습니다. 예를 들어 `date`로 정렬한 블로그 인덱스는 기본이 최신순이고, `reverse = true`를 주면 오래된 순으로 바뀝니다.

```toml
+++
title = "Blog"
sort_by = "date"
# reverse = false (기본값) → 최신순
# reverse = true           → 오래된 순
+++
```

## 예시

### 페이지네이션이 있는 블로그

```toml
+++
title = "Blog"
sort_by = "date"
paginate = 10
paginate_path = "p"
+++
```

생성 결과: `/blog/`, `/blog/p/2/`, `/blog/p/3/`

기본값 `paginate_path = "page"`를 쓰면 URL은 `/blog/page/2/`, `/blog/page/3/`, … 형태가 되고, 1페이지는 항상 섹션 URL에 그대로 있습니다.

### 문서

```toml
+++
title = "Docs"
page_template = "doc-page"
sort_by = "weight"
+++
```

모든 페이지가 `doc-page.html` 템플릿을 사용하고 weight 순으로 정렬됩니다.

### 피드가 있는 섹션

```toml
+++
title = "News"
generate_feeds = true
+++
```

`/news/rss.xml`을 생성합니다.

## 전체 프론트 매터 레퍼런스

모든 필드를 한 블록에 모았습니다. 복사한 뒤 필요 없는 항목을 지우면 됩니다.

```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
+++
```

## 중첩 섹션

섹션은 다른 섹션을 포함할 수 있습니다:

```
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/
```

템플릿에서 하위 섹션에 접근:

```jinja
{% for sub in section.subsections %}
<a href="{{ sub.url }}">{{ sub.title }}</a>
<small>({{ sub.pages_count }})</small>
{% endfor %}
```

## 템플릿 변수

섹션 페이지(`_index.md`)를 렌더링할 때 다음 변수를 쓸 수 있습니다:

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| section.title | String | 현재 섹션 제목 |
| section.description | String | 현재 섹션 설명 |
| section.pages | Array<Page> | 현재 섹션 목록에 표시되는 페이지 |
| section.pages_count | Int | `section.pages`의 항목 수 |
| section.list | String | 미리 렌더링된 HTML 목록(`section_list`와 동일한 값) |
| section.subsections | Array<Section> | 직계 하위 섹션(`title`, `description`, `url`, `pages_count`) |
| section.assets | Array<String> | 섹션과 함께 둔 에셋 |
| section.page_template | String | 하위 페이지의 기본 템플릿 이름 |
| section.paginate_path | String | 페이지네이션 경로 세그먼트 |
| section.redirect_to | String | 설정된 경우 리다이렉트 대상 |
| section_list | String | `section.list`와 동일 |
| pagination | String | 미리 렌더링된 페이지네이션 HTML |
| paginator | Object | 구조화된 페이지네이션 객체 — [데이터 모델 › Paginator](/ko/templates/data-model/#paginator) 참고 |

현재 섹션 URL은 `page.url`을 사용합니다.

### `section.list` / `section_list`

```jinja
<ul class="auto-list">
  {{ section.list | safe }}
</ul>
```

`paginator`로 커스텀 페이지네이션 UI를 만드는 방법은 [데이터 모델 › Paginator](/ko/templates/data-model/#paginator)를 참고합니다.

## 투명 섹션

`transparent = true`를 주면 페이지가 상위 섹션에 합쳐집니다:

```toml
+++
title = "2024 Posts"
transparent = true
+++
```

페이지가 상위 섹션의 `section.pages` 목록에 나타납니다.

## 에셋 코로케이션

일반 페이지처럼 섹션에도 에셋을 함께 둘 수 있습니다. 마크다운이 아닌 파일을 `_index.md`와 같은 디렉터리에 넣으면 됩니다.

**구조 예시:**

```text
content/
└── gallery/
    ├── _index.md       <-- The section index
    ├── banner.jpg      <-- Section asset
    └── icon.png        <-- Section asset
```

이 에셋은 섹션 기준 상대 위치로 출력 디렉터리에 복사됩니다.

### 템플릿에서 에셋 접근

템플릿에서는 `section.assets`로 섹션 에셋 목록에 접근합니다. 파일의 상대 경로 배열(콘텐츠 디렉터리 기준)을 반환합니다.

```jinja
<!-- In section.html -->
<div class="gallery">
  {% for asset in section.assets %}
    <img src="{{ get_url(path=asset) }}" alt="Section Asset">
  {% endfor %}
</div>
```

## 섹션 vs 페이지

| 파일 | 유형 | URL |
|------|------|-----|
| _index.md | 섹션 인덱스 | `/blog/` |
| index.md | 일반 페이지 | `/blog/` |

하위 페이지 목록이 필요하면 `_index.md`를 사용합니다.

## 함께 보기

- [페이지](/ko/writing/pages/) — 개별 콘텐츠 파일과 프론트 매터
- [택소노미](/ko/writing/taxonomies/) — 태그와 카테고리로 콘텐츠 분류
- [데이터 모델](/ko/templates/data-model/) — 템플릿에서의 섹션 속성

---

Title: 숏코드
URL: https://hwaro.hahwul.com/ko/writing/shortcodes/
Source: content/writing/shortcodes.ko.md
Language: ko

숏코드는 마크다운 콘텐츠 안에서 쓸 수 있는 재사용 가능한 템플릿 조각입니다. 커스텀 숏코드는 `templates/shortcodes/`에 두는 Jinja2 템플릿입니다. 템플릿 언어 레퍼런스는 [문법](/ko/templates/syntax/)을 참고합니다.

## 숏코드 사용

콘텐츠 파일에서는 두 가지 문법이 동작합니다:

```markdown
{{ shortcode_name(arg1="value", arg2="value") }}
```

또는 명시적으로:

```markdown
{{ shortcode("shortcode_name", arg1="value") }}
```

### 블록 숏코드 닫기

블록 숏코드는 두 가지 닫기 스타일을 지원합니다:

- **단순 닫기(bare closer)**:
  ```jinja
  {% note %}...{% end %}
  ```

- **이름 있는 닫기(named closer)** (권장):
  ```jinja
  {% note %}...{% endnote %}
  {% alert(type="info") %}...{% endalert %}
  ```

단순하지 않은 콘텐츠에는 **이름 있는 닫기**(`{% endNAME %}`)를 강력히 권장합니다. 여러 숏코드를 섞어 쓰거나 깊게 중첩할 때 마크다운을 읽고 유지보수하기가 훨씬 쉬워집니다.

## 내장 숏코드

Hwaro에는 템플릿 파일 없이 바로 동작하는 내장 숏코드가 들어 있습니다.

### youtube

YouTube 동영상을 삽입합니다.

```markdown
{{ youtube(id="dQw4w9WgXcQ") }}
{{ youtube(id="dQw4w9WgXcQ", width="800", height="450") }}
```

| 파라미터 | 기본값 | 설명 |
|-------|---------|-------------|
| `id` | (필수) | YouTube 동영상 ID |
| `width` | `560` | 플레이어 너비 |
| `height` | `315` | 플레이어 높이 |
| `title` | `YouTube Video` | 접근성용 제목 |

### vimeo

Vimeo 동영상을 삽입합니다.

```markdown
{{ vimeo(id="123456789") }}
```

| 파라미터 | 기본값 | 설명 |
|-------|---------|-------------|
| `id` | (필수) | Vimeo 동영상 ID |
| `width` | `560` | 플레이어 너비 |
| `height` | `315` | 플레이어 높이 |
| `title` | `Vimeo Video` | 접근성용 제목 |

### gist

GitHub Gist를 삽입합니다.

```markdown
{{ gist(user="octocat", id="abc123") }}
{{ gist(user="octocat", id="abc123", file="hello.rb") }}
```

| 파라미터 | 기본값 | 설명 |
|-------|---------|-------------|
| `user` | (필수) | GitHub 사용자 이름 |
| `id` | (필수) | Gist ID |
| `file` | (없음) | 표시할 특정 파일 |

### alert / callout

알림 상자를 표시합니다. 콘텐츠를 감싸는 블록 숏코드로 사용합니다.

단순 닫기와 이름 있는 닫기를 모두 지원합니다(복잡한 페이지에는 이름 있는 닫기를 권장합니다):

```markdown
{% alert(type="warning", title="Caution") %}Be careful with this!{% end %}
{% alert(type="tip") %}Using named closer also works{% endalert %}
```

(명확성을 위해 이름 있는 닫기 스타일을 권장합니다.)

| 파라미터 | 기본값 | 설명 |
|-------|---------|-------------|
| `type` | `info` | `info`, `warning`, `danger`, `tip`, `success` |
| `title` | (없음) | 선택적 제목 |

### figure

캡션을 붙일 수 있는 이미지입니다.

```markdown
{{ figure(src="/img/photo.jpg", alt="A photo", caption="My caption") }}
```

| 파라미터 | 기본값 | 설명 |
|-------|---------|-------------|
| `src` | (필수) | 이미지 URL |
| `alt` | `""` | 대체 텍스트 |
| `caption` | (없음) | 이미지 아래 캡션 |
| `width` | (없음) | 이미지 너비 |
| `height` | (없음) | 이미지 높이 |

### tweet

트윗을 삽입합니다.

```markdown
{{ tweet(user="jack", id="20") }}
```

| 파라미터 | 기본값 | 설명 |
|-------|---------|-------------|
| `user` | (필수) | Twitter 사용자 이름 |
| `id` | (필수) | 트윗 ID |

### codepen

CodePen을 삽입합니다.

```markdown
{{ codepen(user="chriscoyier", id="gfdDu") }}
{{ codepen(user="chriscoyier", id="gfdDu", tab="css,result", height="400") }}
```

| 파라미터 | 기본값 | 설명 |
|-------|---------|-------------|
| `user` | (필수) | CodePen 사용자 이름 |
| `id` | (필수) | Pen ID |
| `tab` | `result` | 기본으로 열릴 탭 |
| `height` | `300` | 삽입 높이 |
| `title` | `CodePen Embed` | 접근성용 제목 |

위에서 **(필수)** 로 표시된 매개변수는 모두 URL이나 `src`에 그대로 들어갑니다.
빠뜨려도 렌더링은 성공하지만 아무 데도 가리키지 않는 임베드
(`https://codepen.io//embed/gfdDu`)가 나오므로, 배포된 페이지에서 깨진 임베드를
직접 찾는 대신 빌드가 경고합니다.

```
[WARN] Shortcode `codepen` is missing required argument `user` — it renders a broken embed. Usage: `{{ codepen(user="…", id="…") }}`.
```

> 내장 숏코드를 덮어쓰려면 `templates/shortcodes/`에 같은 이름의 파일을 만들면 됩니다(예: `templates/shortcodes/youtube.html`). 사용자 템플릿이 항상 우선하며, 자기 계약을 스스로 정의하므로 위 경고는 적용되지 않습니다.

## 커스텀 숏코드 작성

숏코드 템플릿은 `templates/shortcodes/`에 둡니다.

### 예시: 알림 상자

`templates/shortcodes/alert.html`을 만듭니다:

```jinja
{% if type and message %}
<div class="alert alert-{{ type }}">
  {{ message | safe }}
</div>
{% endif %}
```

콘텐츠에서 사용:

```markdown
{{ alert(type="warning", message="This is important!") }}
```

출력:

```html
<div class="alert alert-warning">
  This is important!
</div>
```

### 예시: YouTube 삽입

`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 %}
```

콘텐츠에서 사용:

```markdown
{{ youtube(id="dQw4w9WgXcQ") }}
```

### 예시: 캡션 있는 figure

`templates/shortcodes/figure.html`을 만듭니다:

```jinja
<figure>
  <img src="{{ src }}" alt="{{ alt | default(value='') }}">
  {% if caption %}
  <figcaption>{{ caption }}</figcaption>
  {% endif %}
</figure>
```

콘텐츠에서 사용:

```markdown
{{ figure(src="/images/photo.jpg", alt="A photo", caption="My caption") }}
```

### 예시: 이미지 갤러리(에셋 코로케이션)

페이지와 같은 디렉터리(페이지 번들)에 있는 이미지를 자동으로 나열하는 갤러리를 만들 수 있습니다.

`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>
```

콘텐츠에서 사용(페이지 번들 디렉터리 안에서):

```markdown
{{ gallery() }}
```

마크다운 파일 옆에 있는 모든 JPG/PNG 이미지가 그리드로 렌더링됩니다.

## 블록 숏코드

블록 숏코드는 여는 태그와 닫는 태그 사이의 콘텐츠를 감쌉니다:

```markdown
{% note() %}
This is the **body** content of the shortcode.
{% end %}
```

본문은 `body` 변수로 숏코드 템플릿에 전달됩니다. 마크다운 변환은 자동으로 적용되지 **않으므로**, 필요하면 템플릿에서 `markdownify` 필터를 사용합니다:

```jinja
<div class="note">
  {{ body | markdownify | safe }}
</div>
```

원문 그대로 쓰려면 `body`를 그대로 출력합니다:

```jinja
<div class="note">{{ body }}</div>
```

### 중첩 숏코드

블록 숏코드는 최대 5단계까지 중첩할 수 있습니다:

```markdown
{% outer() %}
  Some text with {{ inner(type="info") }} inside.
{% end %}
```

## 인자 문법

### 이름 있는 인자

인자는 여러 따옴표 스타일을 지원합니다:

```markdown
{{ alert(type="warning", message="Double quotes") }}
{{ alert(type='info', message='Single quotes') }}
{{ alert(type=danger, message=No quotes for simple values) }}
```

### 위치 인자

`key=value` 문법을 쓰지 않으면 인자가 `_0`, `_1`, … 로 할당됩니다:

```markdown
{{ youtube("dQw4w9WgXcQ") }}
```

숏코드 템플릿에서는 `{{ _0 }}`으로 접근합니다:

```jinja
<iframe src="https://www.youtube.com/embed/{{ _0 }}"></iframe>
```

## 내장 변수

숏코드에서 접근할 수 있는 값:

- 전달된 모든 인자
- `site` 객체
- `page` 객체
- 표준 필터와 함수

```jinja
{# In shortcode template #}
<a href="{{ site.base_url }}/{{ url }}">{{ text }}</a>
```

## 팁

### 인자 검증

필수 인자는 항상 확인합니다:

```jinja
{% if not url %}
<p class="error">Missing url parameter</p>
{% else %}
<a href="{{ url }}">{{ text | default(value="Link") }}</a>
{% endif %}
```

### HTML에는 safe 필터 사용

HTML 콘텐츠를 전달할 때:

```jinja
{{ content | safe }}
```

### 숏코드 정리

관련 숏코드를 묶어서 관리합니다:

```
templates/shortcodes/
├── alert.html
├── youtube.html
├── figure.html
├── code/
│   ├── tabs.html
│   └── snippet.html
└── social/
    ├── twitter.html
    └── github.html
```

## 함께 보기

- [문법](/ko/templates/syntax/) — 커스텀 숏코드를 위한 Jinja2 레퍼런스
- [함수](/ko/templates/functions/) — 내장 템플릿 함수

---

Title: 택소노미
URL: https://hwaro.hahwul.com/ko/writing/taxonomies/
Source: content/writing/taxonomies.ko.md
Language: ko

택소노미는 태그, 카테고리, 작성자 같은 그룹으로 콘텐츠를 구성합니다.

## 설정

`config.toml`에서 택소노미를 정의합니다:

```toml
[[taxonomies]]
name = "tags"
feed = true
paginate_by = 10

[[taxonomies]]
name = "categories"
feed = true

[[taxonomies]]
name = "authors"
```

| 키 | 타입 | 기본값 | 설명 |
|-----|------|---------|-------------|
| `name` | string | — | 택소노미 이름(프론트 매터에서 사용) |
| `feed` | bool | false | 항목별 RSS 피드 생성 |
| `sitemap` | bool | true | 택소노미 페이지를 사이트맵에 포함 |
| `paginate_by` | int | — | 항목 페이지의 페이지당 항목 수 |
| `sort_by` | string | "date" | 항목 안 페이지의 정렬 기준: `"date"`, `"title"`, `"weight"` ([정렬](#정렬) 참고) |
| `reverse` | bool | false | `sort_by`가 만든 순서 뒤집기 |
| `terms_sort_by` | string | "name" | 항목 목록의 정렬 기준: `"name"` 또는 `"count"` ([정렬](#정렬) 참고) |

## 정렬

`sort_by`는 각 택소노미 항목에 속한 페이지의 순서를 결정하며, 생성되는 항목 페이지, `get_taxonomy()`의 `term.pages`, 항목별 페이지네이션 모두에 적용됩니다. 의미는 섹션 정렬과 정확히 같습니다:

- `"date"`(기본값): 최신순. `reverse = true`면 오래된 순.
- `"title"` — 알파벳 오름차순. `reverse = true`면 내림차순.
- `"weight"` — 낮은 weight 우선. `reverse = true`면 내림차순.

`sort_by` 값이 잘못되면 경고를 남기고 기본값 `"date"`를 유지합니다.

`terms_sort_by`는 항목 목록의 순서를 결정하며, 택소노미 인덱스 페이지와 `get_taxonomy().items`에 적용됩니다:

- `"name"`(기본값): 알파벳 오름차순.
- `"count"` — 페이지 수 내림차순, 동률이면 이름 오름차순. 다국어 사이트에서는 각 언어의 인덱스가 해당 언어 자체의 페이지 수를 사용합니다.

**항목 피드는 예외입니다.** `feed = true`일 때 각 항목의 RSS 피드는 `sort_by`와 무관하게 항상 역시간순(최신 우선)을 유지합니다. RSS 소비자는 최신 항목이 먼저 온다고 가정하기 때문입니다.

```toml
[[taxonomies]]
name = "tags"
sort_by = "title"
terms_sort_by = "count"
```

## 택소노미 사용

프론트 매터에서 항목을 지정합니다:

```markdown
+++
title = "My Post"
tags = ["crystal", "tutorial"]
categories = ["Programming"]
authors = ["Alice"]
+++
```

Zola 스타일의 `[taxonomies]` 테이블도 동작합니다(두 표기는 동등하며, 둘 다 있으면 명시적인 최상위 키가 우선합니다):

```markdown
+++
title = "My Post"
[taxonomies]
tags = ["crystal", "tutorial"]
tech = ["crystal", "security"]
+++
```

템플릿에서 페이지 자신의 항목은 `page.taxonomies.<name>`으로 접근합니다(예: `{% for t in page.taxonomies.tech %}`). `section.pages`, `site.pages`, 항목 페이지 목록 안의 페이지 객체에서도 동일하게 쓸 수 있습니다.

## 생성되는 URL

`tags` 택소노미에 `crystal` 항목이 있을 때:

| URL | 내용 |
|-----|---------|
| `/tags/` | 전체 태그 목록 |
| `/tags/crystal/` | "crystal" 태그가 붙은 페이지 |

`paginate_by`를 설정하면 항목 페이지가 `/tags/crystal/page/2/`, `/tags/crystal/page/3/`, … 로 페이지네이션됩니다(1페이지는 `/tags/crystal/`에 그대로 있습니다). 페이저 객체는 [데이터 모델 › Paginator](/ko/templates/data-model/#paginator)에 설명되어 있습니다.

## 템플릿

두 템플릿 모두 완성된 목록을 `{{ content }}`로 받습니다. `taxonomy.html`에는 항목 목록이, `taxonomy_term.html`에는 페이지 목록이 들어갑니다. 커스텀 마크업이 필요하면 `content` 대신 [`get_taxonomy()`](#get-taxonomy-함수)를 사용합니다.

### 택소노미 인덱스

`templates/taxonomy.html` — 전체 항목 목록:

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

{% block content %}
<h1>{{ page.title }}</h1>
{{ content }}
{% endblock %}
```

커스텀 항목 목록:

```jinja
{% set tax = get_taxonomy(kind=taxonomy_name) %}
<ul>
{% for term in tax.items %}
  <li>
    <a href="{{ get_taxonomy_url(kind=taxonomy_name, term=term.name) }}">
      {{ term.name }} ({{ term.count }})
    </a>
  </li>
{% endfor %}
</ul>
```

### 택소노미 항목

`templates/taxonomy_term.html` — 특정 항목의 페이지 목록:

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

{% block content %}
<h1>{{ taxonomy_name }}: {{ taxonomy_term }}</h1>
{{ content }}
{% endblock %}
```

커스텀 페이지 목록으로, 현재 항목의 페이지를 `get_taxonomy()`로 조회합니다:

```jinja
{% set tax = get_taxonomy(kind=taxonomy_name) %}
{% for term in tax.items if term.name == taxonomy_term %}
<ul>
{% for p in term.pages %}
  <li><a href="{{ p.url }}">{{ p.title }}</a></li>
{% endfor %}
</ul>
{% endfor %}
```

## 템플릿 변수

`taxonomy.html`과 `taxonomy_term.html` 모두에서 사용 가능:

| 변수 | 타입 | 설명 |
|----------|------|-------------|
| taxonomy_name | String | 택소노미 이름("tags") |
| taxonomy_term | String | 현재 항목 이름(인덱스 페이지에서는 빈 문자열) |
| content | String | 미리 렌더링된 목록 HTML(항목 또는 페이지) |

### 항목 객체

| 속성 | 타입 | 설명 |
|----------|------|-------------|
| name | String | 항목 이름 |
| slug | String | URL에 안전한 이름 |
| pages | Array<Page> | 이 항목이 붙은 페이지 |
| count | Int | 페이지 수 |

## get_taxonomy() 함수

어디서든 택소노미 데이터에 접근합니다:

```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() 함수

택소노미 항목의 URL을 생성합니다:

```jinja
<a href="{{ get_taxonomy_url(kind='tags', term='crystal') }}">
  Crystal articles
</a>
```

## 자주 쓰는 패턴

### 태그 클라우드

```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>
```

### 페이지 태그 표시

```jinja
{% if page.tags %}
<div class="post-tags">
{% for tag in page.tags %}
  <a href="{{ get_taxonomy_url(kind="tags", term=tag) }}">{{ tag }}</a>
{% endfor %}
</div>
{% endif %}
```

`{{ tag | slugify }}` 대신 `get_taxonomy_url()`(또는 `get_taxonomy()`의 `term.slug`)을 사용하세요. 두 용어가 같은 슬러그로 충돌하면(`Crystal`과 `crystal`) 생성기는 `/tags/crystal/`과 `/tags/crystal-2/`를 만드는데, 어느 쪽이 어느 용어인지는 함수만 알고 있습니다.

### 카테고리 내비게이션

```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>
```

## 함께 보기

- [섹션](/ko/writing/sections/) — 디렉터리로 콘텐츠 묶기
- [설정](/ko/start/config/) — 택소노미 설정 레퍼런스
- [데이터 모델](/ko/templates/data-model/) — 템플릿의 택소노미 변수

---

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

## 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, YAML, or JSON 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 hahwul/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**, and the same name Minecraft uses in its Korean localization. In the game, the Furnace is an essential tool that transforms raw materials into useful items. Hwaro plays the same role for static sites: feed in your content, and it turns out a complete website.

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

---

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

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

## Global flags

These flags work with every top-level command and control how the CLI
writes to the terminal. They are especially useful for scripts, CI logs,
and AI agents that want clean output.

| Flag / Env var | Description |
|----------------|-------------|
| `-q`, `--quiet` | Suppress informational output and the startup banner. Warnings and errors still appear on stderr. |
| `NO_COLOR` (env) | When set to any non-empty value, suppresses ANSI color codes from every command's output. Follows the [no-color.org](https://no-color.org) cross-tool convention. |
| `GC_MARKERS` (env) | GC marker-thread count. For `hwaro build` only, Hwaro defaults this to `1` (measured 3-5x faster on allocation-heavy sites); export it to override. Other commands keep the garbage collector's stock behavior. |
| `GC_INITIAL_HEAP_SIZE` (env) | Initial GC heap size. For `hwaro build` only, Hwaro defaults this to `256M` to avoid repeated grow-collect cycles; export it to override. Skipped automatically when `--memory-limit` / `HWARO_MEMORYLIMIT` is set. |

Colors are also disabled automatically when stdout is not a TTY (for
example when piping to `cat`, redirecting to a file, or running inside
most CI systems). Set `NO_COLOR=1` to force-disable color everywhere;
no extra flag is needed.

```bash
# Silent build for scripts and CI — only warnings/errors surface.
hwaro build --quiet

# Plain ASCII (no ANSI escapes) even when stdout is a TTY.
NO_COLOR=1 hwaro doctor
```

### Error taxonomy

Classified failure paths emit a stable error code plus a matching
process exit code so scripts, CI, and agents can branch reliably
without parsing human messages.

In text mode the error line is prefixed with the code:

```
Error [HWARO_E_USAGE]: missing <path> argument
```

Under `--json` the classified error is emitted as a structured payload
on stdout instead. (`--quiet` only silences info output. Errors keep
the human `Error [CODE]: …` form on stderr, so pair it with `--json`
when you want machine-readable failures.)

```json
{
  "status": "error",
  "error": {
    "code": "HWARO_E_USAGE",
    "category": "usage",
    "message": "missing <path> argument",
    "hint": "Usage: hwaro new <path> [options] — run 'hwaro new --help' for details."
  }
}
```

Unclassified failures keep the legacy `Error: <message>` format and
exit code `1`, so this is a strictly additive contract.

| Code | Category | Exit | Description |
|------|----------|------|-------------|
| `HWARO_E_USAGE` | usage | 2 | Bad/missing flag, missing required argument, unknown command |
| `HWARO_E_CONFIG` | config | 3 | `config.toml` missing, unparseable, or invalid |
| `HWARO_E_TEMPLATE` | template | 4 | Crinja template render error |
| `HWARO_E_CONTENT` | content | 5 | Content file parse error, invalid frontmatter |
| `HWARO_E_IO` | io | 6 | Filesystem access error (missing dir, permission denied) |
| `HWARO_E_NETWORK` | network | 7 | Deploy upload, remote scaffold fetch failure |
| `HWARO_E_INTERNAL` | internal | 70 | Unrecoverable bug or unexpected state |
| *(unclassified)* | — | 1 | Legacy/generic failure path |
| *(success)* | — | 0 | Command completed normally |

## Commands

### init

Create a new site:

```bash
hwaro init                    # initialize immediately with defaults
hwaro init my-site            # initialize in my-site/
hwaro init --wizard           # interactive wizard (TTY): scaffold, title
hwaro init my-site --wizard   # wizard; directory prompt skipped (path taken from arg)
hwaro init my-site --scaffold blog
hwaro init my-site --scaffold docs
hwaro init my-site --scaffold book
```

**Interactive mode:**

Pass `--wizard` in an interactive terminal to open a guided flow: it asks for
the directory, a scaffold, and the site title, then shows a
summary and asks to confirm before writing anything. When a path argument is
given (`hwaro init my-site --wizard`), the wizard skips the directory prompt
and uses that path directly.

Without `--wizard`, `hwaro init` initializes immediately with defaults, the
same behaviour scripts and CI already relied on.

Every scaffold follows the reader's OS color scheme automatically (the shared
token system uses CSS `light-dark()` pairs), and the styled scaffolds ship a
header theme switcher that cycles auto → light → dark and remembers the choice
in `localStorage`. To force one scheme permanently instead, add
`:root { color-scheme: dark; }` (or `light`) at the end of `css/style.css`.

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`, `docs`, `book`) or remote source (`github:user/repo[/path]`, URL) |
| --wizard | Run the interactive wizard (TTY only) |
| --agents MODE | AGENTS.md content mode: `remote` (lightweight, default) or `local` (full embedded reference) |
| -f, --force | Force creation even if directory is not empty (keeps existing files) |
| --clean | Remove existing files in the target before scaffolding (implies `--force`; refuses if the target contains `.git/`) |
| --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`). Repeated codes are dropped with a warning |
| --minimal-config | Generate minimal `config.toml` without comments or optional sections |
| --full-config | Generate full `config.toml` with every comment and optional section (maximum discoverability) |
| --list-scaffolds | List available built-in scaffolds and exit |
| -q, --quiet | Suppress info output and the banner (errors still go to stderr) |
| -j, --json | Emit machine-readable JSON output: the scaffold list with `--list-scaffolds`, otherwise a `{"status","path","scaffold","files_created"}` result |

### new

Create a new content file:

```bash
hwaro new                                     # interactive wizard (TTY): prompts for everything
hwaro new content/about.md
hwaro new content/blog/my-post.md
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.

**Interactive mode:**

Running `hwaro new` without a `<path>` in an interactive terminal opens a guided wizard.
It prompts for the title, description, a **recommended path** (derived from the title and
section), tags, date, draft flag, and archetype, then shows a summary and asks to confirm
before writing. Any flags you already passed pre-fill the matching prompt, so
`hwaro new -t "My Post"` only asks for the rest. Press `Ctrl-D` or answer `n` at the final
prompt to cancel without creating anything.

The wizard never runs in non-interactive contexts (pipes, CI, agents, `--json`, or
`--quiet`), which instead print the classified `HWARO_E_USAGE` error, so scripted callers
stay predictable. Pass a `<path>` (and any flags) to skip the prompts entirely.

**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 |
| --bundle | Create a leaf-bundle directory (`foo/index.md`) instead of a single file |
| --no-bundle | Force a single file (`foo.md`); overrides `[content.new].bundle = true` |
| --list-archetypes | List archetypes in the current project and exit |
| --json | Emit machine-readable JSON output (archetypes listing and classified errors) |

**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 }}`, `{{ description }}`

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` |
| -e, --env ENV | Environment name (loads `config.<env>.toml` override) |
| -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 |
| --jobs N | Concurrent render workers. Default: auto, derived from the site listing fan-out (see below) |
| --cache | Enable incremental build caching (see below) |
| --full | Force a complete rebuild, clearing the cache |
| --skip-highlighting | Disable syntax highlighting |
| --skip-og-image | Skip auto OG image generation |
| --skip-image-processing | Skip image resizing and LQIP generation |
| --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 the output directory:** a full build starts from an empty output
directory, but hwaro only clears a directory it can vouch for: the
conventional `public/` next to the project, `hwaro serve`'s own `.hwaro/serve`,
and any directory hwaro created (or found empty) on an earlier build. Pointing
`-o` at a directory that already holds other files (`-o ~/Documents/site`, a
`dist/` shared with a bundler) keeps those files: the site is written into it
and the build warns that files from an earlier build there may be stale. Empty
the directory once to hand it over. The filesystem root, your home directory,
the project itself and its input directories (`content/`, `templates/`,
`static/`, …) are refused outright.

**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 500 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=500 |
| - | 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 shrinks generated files while keeping them visually identical to the un-minified output:

- **HTML**: Removes comments (preserves conditional comments, SSI directives, `<!-- more -->`), strips trailing whitespace, collapses intra-tag whitespace (runs between attributes shrink to one space, quoted attribute values stay untouched), and collapses inter-tag whitespace by neighbour classification. If either neighbour is a block-level element the whitespace is stripped entirely (browsers collapse whitespace at the start, end, or between block siblings anyway); only when *both* neighbours are inline is a single space kept so the visible gap of `<a>x</a> <a>y</a>` is preserved.
- **JSON**: Removes whitespace and newlines for compact output.
- **XML**: Removes whitespace between tags for smaller file sizes.

Whitespace-sensitive elements (`<pre>`, `<code>`, `<textarea>`, `<script>`, `<style>`, `<svg>`, `<math>`, `<noscript>`) are extracted before any whitespace pass and restored verbatim, so their contents are never touched.

For more aggressive output shrinking (attribute quoting, entity collapsing, etc.) post-process `public/` with a dedicated tool such as `html-minifier-terser` or `minify-html`.

**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 `--jobs` (render concurrency):**

By default Hwaro picks the number of concurrent render workers from your site's **listing fan-out**, the number of page objects a single page render materializes from a site-wide collection. `--jobs N` overrides that. It never changes the generated output, only how many pages render at once.

Fan-out is what caps useful parallelism, not the core count. Every `{% for p in site.pages %}` or `{% for p in section.pages %}` iteration allocates one object per item, and past a small worker count the garbage collector's global allocation lock serializes that work while extra workers add only contention. So the automatic count is:

| Items materialized per page render | Workers |
|---|---|
| 500 or more (e.g. a `page` template listing every page on a large site) | 1 |
| 100–499 | 2 |
| Under 100 (most sites) | up to 4 |

A homepage that lists every page does not count against this. The estimate is the mean across rendered pages, so one expensive listing page among thousands of cheap ones leaves the site on the fast path.

```bash
hwaro build --jobs 4   # override the automatic count
```

Leave it unset unless you are benchmarking; the automatic count is within a few percent of the best fixed value on every corpus we measure. `--jobs` has no effect together with `--no-parallel`.

**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 and the current directory is used.

### serve

Start a development server with live reload (enabled by default):

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

> **Serve output is a dev artifact. Never deploy it.** `hwaro serve` builds into its own directory, `.hwaro/serve/`, and leaves the configured `output_dir` (`public/` by default) completely untouched, so a serve session can never overwrite a deployable build. The pages under `.hwaro/serve/` carry the dev server's `base_url` (e.g. `http://127.0.0.1:3000`) in every link, and the directory is stamped with a `.hwaro-dev` marker that `hwaro deploy` refuses. Run `hwaro build` to produce a deployable site. `.hwaro/` keeps itself out of version control: hwaro writes a self-ignoring `.hwaro/.gitignore` when it creates the directory, and `hwaro init` also scaffolds a project `.gitignore` covering the output dir, `.hwaro/`, and `.hwaro_cache.json`.

**Options:**

| Flag | Description |
|------|-------------|
| -i, --input DIR | Project directory to serve (default: current directory) |
| -b, --bind HOST | Bind address (default: 127.0.0.1). IPv6 literals are supported and appear bracketed in every generated URL (`-b ::1` → `http://[::1]:3000`) |
| -p, --port PORT | Port number (default: 3000) |
| --base-url URL | Temporarily override `base_url` from `config.toml`. If the URL carries a path, the dev server mounts the site under that prefix (see below) |
| -e, --env ENV | Environment name (loads `config.<env>.toml` override) |
| --minify | Serve minified output |
| --jobs N | Concurrent render workers. Default: auto, derived from the site listing fan-out |
| --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). Each line reports the path the browser requested (`/`, not the `/index.html` the dev server resolves it to) |
| --no-error-overlay | Disable in-browser error overlay (default: enabled) |
| --live-reload | Enable browser live reload on file changes (default: enabled; kept for backwards compatibility) |
| --no-live-reload | Disable browser live reload on file changes |
| --header "NAME: VALUE" | Add custom response header (repeatable). Merged with `[serve.headers]` from `config.toml` (CLI wins). Only affects `hwaro serve`. |
| --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`) |
| --fast-start | Render homepage + latest N pages first, then background-render the rest |
| --fast-start-count N | Number of recent pages to render up front with `--fast-start` (default: 20) |
| --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 |

> **Fast dev server on large sites:** Set `[og.auto_image] lazy_generate = true` in `config.toml` to skip bulk OG generation during `hwaro serve`. Images are created on first request instead. See the [Faster Dev Server section](/features/og-images/#faster-dev-server) for the full explanation and recommended workflow with `--fast-start`.

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:**

Live reload is **enabled by default**. The server injects a small WebSocket client script into every HTML response, and after each successful rebuild, connected browsers automatically refresh the page, so no manual reload is needed. The client uses exponential backoff (1s to 30s) for reconnection, so restarting the server won't break the connection permanently.

Pass `--no-live-reload` to disable this behaviour (useful for testing production-like delivery locally). The `--live-reload` flag is kept as a no-op alias for backwards compatibility with existing invocations.

When `-i` is specified, the server operates as if you had `cd`-ed into the given directory, watching and serving from that project root.

**Subpath preview (`--base-url` with a path):**

```bash
hwaro serve --base-url http://localhost:3000/myblog/
```

The site is built with `/myblog/`-prefixed links and served under that same prefix, so a project-page deployment (GitHub Pages, GitLab Pages) can be previewed exactly as it will be published, instead of a homepage whose every link 404s locally.

- `/` redirects to `/myblog/`.
- Unprefixed requests still resolve, so hand-typed asset paths keep working.
- Live reload, the file watcher, and the WebSocket endpoint all work under the prefix.

**Request handling:**

- The server answers `GET`, `HEAD`, and `OPTIONS`. Any other method returns `405 Method Not Allowed` with an `Allow: GET, HEAD, OPTIONS` header, rather than the 404 page.
- Malformed request paths (for example a percent-encoded NUL byte) return `400 Bad Request`.
- `HEAD` returns exactly the same headers as the matching `GET`, including the `Content-Length` of the live-reload-injected HTML, with no body.
- Text responses (`.txt`, `.json`, `.xml`, `.js`, `.css`, `.svg`, …) always carry `; charset=utf-8`, regardless of file size.
- Directory redirects emit a percent-encoded `Location` (`/my%20page/`, `/%ED%95%9C%EA%B8%80/`). Paths containing a backslash or an encoded separator (`%2F`, `%5C`) are not served, matching static-host behaviour.

**Custom response headers (`--header` / `[serve.headers]`):**

Use this to reproduce headers that your production reverse-proxy, CDN, or static hosting sets (security headers, `Cache-Control`, custom CORS, etc.) so you can test locally before deploying the static output.

```toml
[serve.headers]
X-Frame-Options = "SAMEORIGIN"
X-Content-Type-Options = "nosniff"
Referrer-Policy = "strict-origin-when-cross-origin"
# Cache-Control = "public, max-age=3600"
```

```bash
hwaro serve --header "X-Custom: foo" --header "Cache-Control: no-store"
```

- CLI `--header` values win over the same key in `config.toml`.
- Headers are injected on **every** dev-server response (HTML, assets, 404s, redirects, live-reload injected pages, CORS preflight (`OPTIONS`) responses).
- This feature only affects `hwaro serve`. The files the build writes to disk are untouched.

### deploy

Deploy the generated site to configured targets.

```bash
hwaro deploy [target ...]
hwaro deploy --target prod
hwaro deploy --dry-run
```

**Options:**

| Flag | Description |
|------|-------------|
| -s, --source DIR | Source directory to deploy (default: deployment.source_dir or public) |
| -t, --target NAME | Deploy target name (repeatable; equivalent to a positional target) |
| --dry-run | Show planned changes without writing |
| --confirm | Ask for confirmation before deploying |
| --force | Force upload/copy (ignore file comparisons), and allow clearing a destination from an empty source |
| --max-deletes N | Maximum number of deletes (default: deployment.maxDeletes or 256, -1 disables) |
| --list-targets | List configured deployment targets and exit |
| --json | Emit machine-readable JSON output (plan with `--dry-run`, per-target summary otherwise, target list with `--list-targets`) |
| -e, --env NAME | Config environment to load (also `HWARO_ENV`) |
| -q, --quiet | Suppress human log output |

**Safety rules.** `deploy` refuses rather than destroying a destination it
cannot reconcile:

- An empty source directory (or one where `include`/`exclude` selected
  nothing) aborts instead of deleting the destination. Run `hwaro build`
  first, or pass `--force` to clear it deliberately. A `command` target that
  never interpolates `{source}` is exempt, since it does not read the
  source at all.
- `--max-deletes` caps the delete pass (256 by default; any negative value
  disables it). It applies to the built-in `file://` sync only; a command
  target's own `--delete` flag is not bounded by it.
- Symlinks at the destination are never written or deleted *through*. A link
  standing where a file or directory belongs is replaced; a stale one is
  unlinked without touching what it points at.
- `--json` is non-interactive: combining it with `--confirm` fails instead of
  writing a prompt into the JSON document.

### doctor

Diagnose config, template, and structure issues (top-level shortcut):

```bash
hwaro doctor               # Diagnose config, template, and structure issues
hwaro doctor --fix         # Normalize config values (base_url trailing slash, sitemap priority…)
hwaro doctor --approve     # Add recommended config sections to config.toml
hwaro doctor --full        # Both (equivalent to --fix --approve)
```

**Exit codes.** `doctor` returns a classified exit code based on the most
severe issue reported, so CI pipelines can gate on it directly:

| Outcome | Exit |
|---|---|
| No issues, warnings only, or info-level findings | `0` |
| Config errors (missing/broken `config.toml`) | `3` (`HWARO_E_CONFIG`) |
| Template errors (missing required file, unclosed tags) | `4` (`HWARO_E_TEMPLATE`) |
| Content errors (malformed front matter, when the check lands) | `5` (`HWARO_E_CONTENT`) |
| Other error-level issues | `1` |

Warnings (empty `base_url`, trailing slash, duplicate taxonomy names, etc.)
are advisory and never change the exit code.

For content validation, use `hwaro tool validate`. See [doctor](/start/tools/doctor/) for details.

### tool

Utility tools for content management:

```bash
# Content tools
hwaro tool list all             # List all content files
hwaro tool list drafts          # List draft files
hwaro tool convert to-yaml      # Convert frontmatter to YAML
hwaro tool convert to-toml      # Convert frontmatter to TOML
hwaro tool convert to-json      # Convert frontmatter to JSON
hwaro tool check-links          # Check for dead external links
hwaro tool stats                # Show content statistics
hwaro tool validate             # Validate content frontmatter and markup
hwaro tool unused-assets        # Find unreferenced static files

# Site tools
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 platform codeberg-pages # Generate Codeberg Pages (Forgejo Actions) workflow
hwaro tool doctor                 # Diagnose config/template/structure issues
hwaro tool import hugo /path      # Import from Hugo
hwaro tool import jekyll /path    # Import from Jekyll
hwaro tool export hugo            # Export to Hugo format
hwaro tool export jekyll          # Export to Jekyll format
hwaro tool agents-md --write      # Write AGENTS.md to file

# JSON output
hwaro tool list all --json
hwaro tool convert to-yaml --json
hwaro tool stats --json
hwaro tool validate --json
hwaro tool unused-assets --json
hwaro tool doctor --json
hwaro tool check-links --json
hwaro tool import jekyll /path --json
hwaro tool export hugo --json

# Preview destructive/bulk operations without writing
hwaro tool convert to-yaml --dry-run
hwaro tool import jekyll /path --dry-run
hwaro tool export hugo --dry-run
```

The `list` and `convert` commands accept only the positional arguments shown in
their usage. `check-links`, `stats`, `validate`, and `unused-assets` accept no
positional arguments. Extra positional arguments, including arguments after
`--`, are rejected with a usage error; use the documented flags for additional
paths and options.

**Subcommands:**

| Category | Subcommand | Description |
|----------|------------|-------------|
| Content | [list](/start/tools/list/) | List content files by status (all, drafts, published) |
| Content | [convert](/start/tools/convert/) | Convert frontmatter between TOML, YAML, and JSON formats |
| Content | [check-links](/start/tools/check-links/) | Check for dead links in content files |
| Content | [stats](/start/tools/stats/) | Show content statistics |
| Content | [validate](/start/tools/validate/) | Validate content frontmatter and markup |
| Content | [unused-assets](/start/tools/unused-assets/) | Find unreferenced static files |
| Site | [platform](/start/tools/platform/) | Generate platform config and CI/CD workflow files |
| Site | [doctor](/start/tools/doctor/) | Diagnose config, template, and structure issues |
| Site | import | Import content from WordPress, Jekyll, Hugo, Notion, Obsidian, Hexo, Astro, or Eleventy |
| Site | [export](/start/tools/export/) | Export content to Hugo or Jekyll |
| Site | [agents-md](/start/tools/agents-md/) | Generate or update AGENTS.md file |

**Common Options:**

| Flag | Description |
|------|-------------|
| -c, --content-dir 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 without live reload (production-like serving)
hwaro serve --no-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
Language: en

All site configuration lives in `config.toml` at the project root.

Unknown top-level keys are reported instead of silently ignored. A typo'd
`[markdonw]` or `titel = "…"` would otherwise disable a feature with no
feedback. Hwaro warns with a suggestion when one is close to a real key:

```
Unknown key 'markdonw' in config.toml — hwaro does not read it. Did you mean 'markdown'?
```

The check covers top-level keys only; keys nested inside a section are
validated by that section's own loader.

## 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 |
| template_deps | bool | true | Track template dependencies so a template edit only rebuilds the pages that render it |
| hooks.pre | array | [] | Commands to run before build |
| hooks.post | array | [] | Commands to run after build |

`output_dir`, `drafts`, `parallel` and `cache` each back a `hwaro build` flag, and the flag wins:

```
command-line flag  >  config.toml  >  built-in default
```

So `hwaro build -o dist` overrides `output_dir` in config, and `hwaro build --drafts` still includes drafts when `drafts = false`. The reverse does not exist: there is no `--no-drafts` or `--no-cache` to turn a config value back off, so set those keys only when you want them on for every build. `--no-parallel` is the one exception, and it overrides `parallel = true`.

These apply to `hwaro serve` as well, which builds into (and serves from) `output_dir`. `hwaro deploy` follows it too: when `[deployment] source_dir` is not set, it deploys `output_dir` rather than assuming `public`.

`output_dir` may be relative to the project or absolute. A path that escapes the project (`../out`) is refused, because the dev server will not serve from outside the project and the build would otherwise write somewhere serve never reads.

See [Build Hooks](/features/build-hooks/) for error handling and use cases.

## Markdown

```toml
[markdown]
safe = false
lazy_loading = false
emoji = false
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]`) |
| task_list_classes | bool | false | Add GFM classes (`task-list-item`, `contains-task-list`) to task-list markup |
| 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"`) |
| smart_punctuation | bool | false | Typographic quotes/dashes/ellipses (`"x"` → “x”, `--` → –, `...` → …) |
| containers | bool | false | `:::note Title` … `:::` custom containers (admonition markup) |
| insert_anchor_links | string | "none" | Site-wide heading anchor links: `"none"`, `"left"`, or `"right"` (page front matter overrides) |
| external_links_target_blank | bool | false | Add `target="_blank" rel="noopener"` to absolute http(s) links |
| external_links_no_follow | bool | false | Add `rel="nofollow"` to absolute http(s) links |
| external_links_no_referrer | bool | false | Add `rel="noreferrer"` to absolute http(s) links |

See [Markdown Extensions](/features/markdown-extensions/) for syntax details and examples.

## Content

```toml
[content]
summary_length = 70
summary_ellipsis = "…"
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| summary_length | int | 70 | Automatic summary length for pages without `<!-- more -->` or `description`: words for space-delimited text, characters ×2 for CJK-dominant text. `0` disables the automatic summary |
| summary_ellipsis | string | "…" | Appended to an automatic summary only when text was cut |

See [Content Summary](/writing/pages/#content-summary) for how `page.summary` is chosen. `[content.files]`, `[content.new]` and `[[content.generate]]` are documented in the feature reference below.

## 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/` |

Rules are evaluated in declaration order and the **first** source that matches the page's directory (exactly or as a parent prefix) wins. Later rules are never consulted for that page. Declare specific prefixes before broad ones (`"posts/tech"` before `"posts"`), or the broad rule shadows the specific one. This applies to token patterns too, and especially to the `""` catch-all: put it **last**, after every other rule.

### Token patterns

A target containing `:token` segments is a Hugo-style pattern that rebuilds the whole URL instead of remapping the directory:

```toml
[permalinks]
"posts" = "/:year/:month/:day/:slug/"
```

With `content/posts/hello.md` dated `2026-03-05`, the page is published at `/2026/03/05/hello/`.

| Token | Expands to |
|-------|------------|
| `:year` | Page date year (`2026`) |
| `:month` | Page date month, zero-padded (`03`) |
| `:day` | Page date day, zero-padded (`05`) |
| `:slug` | Front-matter `slug`, or the filename stem when unset |
| `:title` | Slugified front-matter `title` (falls back to `:slug` when it slugifies to nothing) |
| `:section` | The page's section path (`posts/tech`); empty for root pages, collapsing the segment |
| `:filename` | The filename stem, ignoring any `slug` override |

Notes:

- Tokens must be whole path segments; unknown tokens fail the config load.
- Patterns apply to leaf pages only. Section `_index` and bundle `index` pages skip pattern rules (they keep their directory URL, or a later plain remap rule).
- A page without a `date` that matches a pattern using `:year`/`:month`/`:day` fails the build. Add a date, set an explicit `path` in front matter, or drop the date tokens. Pages that never publish are exempt: drafts (without `--drafts`), expired/future-dated pages, and headless `render: false` pages don't block the build.
- An explicit `path` in front matter always wins over any permalink rule.
- An empty source key (`""` or `"/"`) makes a pattern rule a catch-all for every page. Declare it last, since first-match ordering means it would shadow any rule after it.
- For non-default languages the `/lang/` prefix comes first: `/ko/2026/03/05/hello/`.

## Links

Control how unresolved `@/path.md` internal links are treated during the build.

```toml
[links]
broken_internal = "error"
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| broken_internal | string | "warn" | `"warn"` logs each unresolved `@/` link and keeps the raw markup; `"error"` fails the build (exit code 5) with one aggregated list of every offender |

See [Internal Links](/writing/pages/#internal-links) for the `@/` link syntax and the `--cache` caveat in strict mode.

## Taxonomies

```toml
[[taxonomies]]
name = "tags"
feed = true
paginate_by = 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_by | int | — | Items per page on term pages |
| sort_by | string | "date" | Order of pages within a term: `"date"` (newest first), `"title"`, or `"weight"` |
| reverse | bool | false | Flip whichever order `sort_by` produced |
| terms_sort_by | string | "name" | Order of the terms list on the taxonomy index: `"name"` or `"count"` |

Term feeds stay reverse-chronological regardless of `sort_by`. See
[Taxonomies](/writing/taxonomies/#sorting) for the full sorting rules.

## Menus

Named navigation menus, rendered in templates via `site.menus` / `get_menu()`.

```toml
[[menus.main]]
name = "Posts"
url = "/posts/"
weight = 1

[[menus.main]]
name = "About"
url = "/about/"
weight = 2
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| name | string | — | **Required.** Entry skipped (with a warning) if missing. |
| url | string | "" | Root-relative or absolute `http(s)://`/`//` URL. |
| weight | int | 0 | Sort order within the menu. |
| identifier | string | `name` | Unique key other entries reference via `parent`. |
| parent | string | none | Nest this entry under another entry's `identifier`. |

Pages/sections can also join a menu from their own front matter (`menus = ["main"]`) without touching this file. A `[languages.<code>]` block with no menus table inherits this global set; declaring `[[languages.<code>.menus.<name>]]` replaces it for that language. See [Menus](/features/menus/) for the full reference (hierarchy, per-language behavior, `active_path` styling).

## Static Files

Everything under `static/` is copied verbatim into the site root, preserving its directory structure, so `static/css/app.css` is served at `/css/app.css`. Hidden entries are included too, so `static/.well-known/security.txt` is published at `/.well-known/security.txt`. By default Hwaro filters out common OS, editor, and VCS cruft so it never ships to production.

```toml
[static]
use_default_excludes = true              # filter built-in cruft (default)
exclude = ["*.bak", "drafts/**"]         # extra patterns to skip
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| use_default_excludes | bool | true | Filter the built-in cruft denylist (`.DS_Store`, `Thumbs.db`, `desktop.ini`, `.git`, vim swap files, …) |
| exclude | array | [] | Extra patterns to skip. A glob like `*.bak` matches at any depth, `drafts/**` scopes a subtree, and a literal name is anchored to an exact file or directory (`drafts` drops `drafts/…`) |

The built-in denylist only removes cruft. Legitimate dot-paths such as `.well-known/` and `.domains` are **never** filtered and are always published, identically for cold and `--cache`/incremental builds. Set `use_default_excludes = false` to disable the built-in filtering entirely.

## Development Server

Options for `hwaro serve` only. They never affect `hwaro build` output.

```toml
[serve]
fast = true                          # always serve in fast dev mode

[serve.headers]
X-Frame-Options = "SAMEORIGIN"
Cache-Control = "no-store"
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| fast | bool | false | Serve as if `--fast` was passed (skips OG image generation and image processing); explicit CLI skip flags still apply |
| headers | table | {} | Custom HTTP response headers added to every dev-server response; CLI `--header` values win on duplicate keys |

See the [serve command](/start/cli/#serve) for the matching CLI flags.

## 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 (including `lazy_generate` for fast dev server) |
| `[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 |
| `[sass]` | [Sass/SCSS](/features/sass/) | Built-in SCSS compilation (pure Crystal) |
| `[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 |
| `[[content.generate]]` | [Content Generation](/features/content-generation/) | Materialize `site.data` records into pages |
| `[[data.remote]]` | [Remote Data Sources](/features/remote-data/) | Fetch remote data into `site.data` at build time |
| `[static]` | [Static Files](#static-files) | Filter cruft / exclude paths from the `static/` copy |
| `[serve]` | [Development Server](#development-server) | Dev-server response headers & fast mode |
| `[links]` | [Links](#links) | Broken internal `@/` link handling (warn or fail the build) |
| `[series]` | [Series](/features/series/) | Group posts into ordered series |
| `[related]` | [Related Posts](/features/related-posts/) | Related content recommendations |
| `[git]` | [Git Metadata](/features/git-info/) | `page.git` commit info and `updated`/`date` fallbacks from history |
| `[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 |
| `[doctor]` | [Doctor](/start/tools/doctor/) | Suppress known diagnostic issues |
| `languages.*` | [Multilingual](/features/multilingual/) | Multi-language support |
| `[versions]` / `[[versions.list]]` | [Versioned Docs](/features/versioned-docs/) | Several documentation versions side by side |
| `[[menus.*]]` | [Menus](/features/menus/) | Named navigation menus |

## 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"
"posts" = "/:year/:month/:day/:slug/"

[plugins]
processors = ["markdown"]

[[taxonomies]]
name = "tags"
feed = true

[[taxonomies]]
name = "categories"

[[menus.main]]
name = "Posts"
url = "/posts/"

# Feature sections — see Feature Configuration Reference above
# [feeds], [sitemap], [robots], [og], [search], [highlight],
# [pagination], [auto_includes], [assets], [sass], [image_processing],
# [series], [related], [git], [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
Language: en

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, reading time, and older/newer post navigation |
| `docs` | Documentation with sidebar and prev/next page navigation |
| `book` | Book with chapters, prev/next navigation, keyboard shortcuts |

Every scaffold shares one design-token system built on CSS `light-dark()` pairs,
so each site automatically follows the reader's OS color scheme, light or dark, with no extra setup. The styled scaffolds also ship a
theme switcher in the header: it cycles auto → light → dark, persists the
choice in `localStorage`, and applies it before first paint so there is no
flash. To force one scheme permanently (a dark-only site), add
`:root { color-scheme: dark; }` at the end of the generated `css/style.css`.

The scaffolds also include a few modern touches: a sticky glass header, native
cross-document view transitions between pages, and (on blog posts and book
pages) a CSS-only reading-progress thread. All of it degrades gracefully on
older browsers and every animation respects `prefers-reduced-motion`.

{% preview_gallery() %}
<a class="preview-item" href="/images/scaffolds/scaffold-simple.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-simple.png" alt="simple scaffold" width="1280" height="800" loading="lazy"><div class="preview-label"><code>simple</code> — Landing pages, small sites</div></a>
<a class="preview-item" href="/images/scaffolds/scaffold-bare.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-bare.png" alt="bare scaffold" width="1280" height="800" loading="lazy"><div class="preview-label"><code>bare</code> — Minimal structure, semantic HTML only</div></a>
<a class="preview-item" href="/images/scaffolds/scaffold-blog.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-blog.png" alt="blog scaffold" width="1280" height="800" loading="lazy"><div class="preview-label"><code>blog</code> — Posts with tags and categories</div></a>
<a class="preview-item" href="/images/scaffolds/scaffold-docs.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-docs.png" alt="docs scaffold" width="1280" height="800" loading="lazy"><div class="preview-label"><code>docs</code> — Documentation with sidebar</div></a>
<a class="preview-item" href="/images/scaffolds/scaffold-book.png" target="_blank" rel="noopener"><img src="/images/scaffolds/scaffold-book.png" alt="book scaffold" width="1280" height="800" loading="lazy"><div class="preview-label"><code>book</code> — Book with chapters</div></a>
{% end %}

> **Tip:** Looking for a more complete starting point? Check out the [Hwaro Examples](https://examples.hwaro.hahwul.com/) for ready-made boilerplates you can use right away.

## 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)
├── data/            # Optional: JSON/YAML/TOML/CSV exposed as site.data
└── public/          # Generated output
```

### Where files go

Two rules cover most of it.

**`data/` sits at the project root**, next to `config.toml`, not under `content/`. Every file in it is loaded automatically and keyed by its filename, so `data/team.json` is available in any template as `site.data.team`:

```jinja
{% for member in site.data.team %}
  <li>{{ member.name }}</li>
{% endfor %}
```

Subdirectories nest (`data/users/alice.yml` → `site.data.users.alice`). `hwaro init` does not create this directory; add it when you need it. See [Data Model](/templates/data-model/) for the full rules.

**Assets go in `static/`.** `static/images/photo.jpg` is copied to the output as `/images/photo.jpg`, so you reference it with a leading slash:

```
{{ figure(src="/images/photo.jpg", caption="A photo") }}
```

Keep the leading `/` even when you deploy to a sub-path such as `example.com/my-site/`. Hwaro rewrites root-relative `src` and `href` values to include the `base_url` sub-path at build time, so the same content works in both places.

You can also keep an asset next to the page that uses it, inside `content/`, but that is opt-in. Enable [Content Files](/features/content-files/) first:

```toml
[content.files]
allow_extensions = ["jpg", "png", "svg", "pdf"]
```

## 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
```

> **Tip:** run `hwaro new` with no arguments to open an interactive wizard that
> suggests a path and collects the title, description, tags, and more for you.

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.

## Optional: Build with an AI Agent

If you work with Claude Code, Cursor, Codex, or another skill-aware agent, Hwaro
ships two [Agent Skills](/integrations/skills/) that teach it how to drive the
project you just created:

| Skill | What it does |
|-------|--------------|
| `hwaro` | Runs the CLI properly (`init`, `new`, `serve`, `build`, `doctor`, and the content tools) using the `--json` output contract and `HWARO_E_*` exit codes instead of guessing from text. |
| `hwaro-design` | Designs and rethemes the site inside Hwaro's Crinja templates and `light-dark()` design tokens, under an anti-slop discipline that avoids generic AI-looking layouts. |

Install both with one command:

```bash
npx skills add hahwul/hwaro
```

Then ask the agent something like *"add a projects section to this Hwaro site"*
or *"retheme this blog to a warm dark palette"*, and it loads the matching skill on
its own. See [Agent Skills](/integrations/skills/) for manual install paths and
per-agent directories, and [AGENTS.md](/start/tools/agents-md/) to record
project-specific conventions the agent should follow first.

## Next Steps

- [CLI Commands](/start/cli/) — All available commands
- [Configuration](/start/config/) — Full config reference
- [Writing Content](/writing/) — Pages, sections, taxonomies
- [Agent Skills](/integrations/skills/) — Let an AI agent build and design the site
- [Deploy](/deploy/) — Hosting and deployment guides

---

Title: Installation
URL: https://hwaro.hahwul.com/start/installation/
Source: content/start/installation.md
Language: en

Hwaro is written in Crystal. You can install it from source or use a pre-built binary.

## Homebrew

```bash
brew tap hahwul/hwaro
brew install hwaro
```

## Snapcraft

```bash
sudo snap install hwaro
```

## APK (Alpine Linux)

Download the `.apk` package from the [latest release](https://github.com/hahwul/hwaro/releases/latest) and install it:

```bash
apk add --allow-untrusted hwaro-*.apk
```

## DEB (Debian/Ubuntu)

Download the `.deb` package from the [latest release](https://github.com/hahwul/hwaro/releases/latest) and install it:

```bash
sudo dpkg -i hwaro_*_amd64.deb
```

## RPM (Fedora/RHEL/CentOS)

Download the `.rpm` package from the [latest release](https://github.com/hahwul/hwaro/releases/latest) and install it:

```bash
sudo rpm -i hwaro-*.x86_64.rpm
```

## AUR (Arch Linux)

```bash
yay -S hwaro
```

## Nix

### Install

```bash
nix profile install github:hahwul/hwaro
```

### Run without installing

```bash
nix run github:hahwul/hwaro -- --version
```

### Development shell

```bash
nix develop github:hahwul/hwaro
```

The dev shell brings its own Crystal, `shards`, `just`, and `crystal2nix`, so
`just build` and `just test` work with nothing else installed.

### As a flake input

```nix
{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  inputs.hwaro.url = "github:hahwul/hwaro";

  outputs = { nixpkgs, hwaro, ... }: {
    # `hwaro.packages.<system>.hwaro`, or add `hwaro.overlays.default` to your
    # nixpkgs overlays and use `pkgs.hwaro`.
  };
}
```

Supported systems are `x86_64-linux`, `aarch64-linux`, and `aarch64-darwin`
(nixpkgs-unstable no longer supports Intel macOS). The flake pins the official
Crystal toolchain, so no compiler has to be built from source.

## 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 binary for your platform from the [latest release](https://github.com/hahwul/hwaro/releases/latest).
2. Move the binary to a directory in your PATH. **On macOS the download is a
   tarball, not a bare binary. See [macOS](#macos) below before moving
   anything.**

```bash
# Example for Linux (amd64)
chmod +x hwaro-v*-linux-x86_64
sudo mv hwaro-v*-linux-x86_64 /usr/local/bin/hwaro
```

### macOS

The macOS download is a tarball, not a bare binary. It extracts to `hwaro`
plus a `lib/` directory holding the bundled OpenSSL, and the binary loads
those through `@executable_path/lib`, so **`lib/` has to travel with it**.
Move the whole extracted directory, not just the binary:

```bash
tar -xzf hwaro-v*-osx-arm64.tar.gz
sudo mkdir -p /usr/local/libexec/hwaro
sudo cp -R hwaro lib /usr/local/libexec/hwaro/
sudo ln -sf /usr/local/libexec/hwaro/hwaro /usr/local/bin/hwaro
```

The symlink is safe: macOS resolves it before computing `@executable_path`,
so the dylibs are still found. Homebrew installs the tarball the same way.

> **v0.20.0 only.** That release's macOS tarball shipped with an invalid code
> signature on its bundled dylibs, and Apple Silicon kills the process at
> launch with `zsh: killed hwaro` and no other diagnostic. Clearing quarantine
> on its own does not fix it, because the signature is stale as well; re-signing
> on its own can also leave you stuck, because re-signing a quarantined file
> resets its approval. Do both, in this order, from the extracted directory:
>
> ```bash
> xattr -dr com.apple.quarantine hwaro lib
> codesign --force --sign - lib/*.dylib hwaro
> ```
>
> A patch release will carry the fix, after which no manual step is needed.

## From Source

### Prerequisites

- [Crystal](https://crystal-lang.org/install/) 1.21+
- Git

### Build

```bash
git clone https://github.com/hahwul/hwaro
cd hwaro
shards install
shards build --release --no-debug
```

The binary is created at `./bin/hwaro`.

> Requires Crystal **1.21 or newer**. Parallel page rendering is enabled in
> `src/main.cr`, which resizes Crystal's default execution context, so no build
> flag is needed. Set `CRYSTAL_WORKERS=N` to override the worker count (it
> defaults to the CPU count). Do not pass the old `-Dpreview_mt` flag:
> Crystal 1.21 deprecated it and its scheduler can hang at process exit.
>
> For `hwaro build` (any install method, not just source builds), Hwaro
> tunes the Boehm GC at startup (`GC_MARKERS=1` and
> `GC_INITIAL_HEAP_SIZE=256M`). We measured 3-5x faster builds on
> allocation-heavy sites, at the cost of a higher peak memory floor during
> the build. Exporting either variable overrides the built-in default, and
> the heap presize is skipped when `--memory-limit` is used. See the
> [global flags table](@/start/cli.md) for details.

### 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
Language: en

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 |
| [stats](/start/tools/stats/) | Show content statistics |
| [validate](/start/tools/validate/) | Validate content frontmatter and markup |
| [unused-assets](/start/tools/unused-assets/) | Find unreferenced static files |
| [doctor](/start/tools/doctor/) | Diagnose config, template, and structure issues |
| [platform](/start/tools/platform/) | Generate hosting platform config files |
| [import](/start/tools/import/) | Import content from various platforms |
| [export](/start/tools/export/) | Export content to other platforms |
| [agents-md](/start/tools/agents-md/) | Generate or update AGENTS.md file |

> **Deprecated:** [ci](/start/tools/ci/) is hidden from help and superseded by [platform](/start/tools/platform/) (e.g. `hwaro tool platform github-pages`).

---

## 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`, `stats`, `validate`, `export`, etc.
- **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
Language: en

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. Regenerating with `--write` preserves that section from the existing file. The generated parts are refreshed (or switched between modes) while whatever you wrote under `## Site-Specific Instructions` is carried over unchanged. Preservation keys on that exact heading: an existing file without a `## Site-Specific Instructions` heading is replaced entirely (the prompt, or a warning under `--force`, says so before it happens).

## 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 | Regenerate an existing file without confirmation (Site-Specific Instructions still preserved) |
| -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. Either way, your **Site-Specific Instructions** section is preserved across the rewrite.

## 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: check-links
URL: https://hwaro.hahwul.com/start/tools/check-links/
Source: content/start/tools/check-links.md
Language: en

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

# Silence a known-flaky host, and accept bot-blocking status codes
hwaro tool check-links --ignore-url twitter.com --allow-status 403,429
```

## 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 |
| --ignore-url PATTERN | Skip links whose URL matches PATTERN (repeatable) |
| --allow-status CODES | Treat these HTTP status codes as healthy (comma-separated) |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

`--ignore-url` matches the URL as written in the source, as a
case-insensitive substring. `--ignore-url twitter.com` skips every link
containing `twitter.com` (or `Twitter.com`), and `*` matches any run of
characters (`--ignore-url 'https://example.com/*'`). The flag can be passed
multiple times; matching links are never contacted at all, the scan line
reports how many were ignored, and the JSON payload carries the same number
as `ignored_count`, so a machine consumer can tell "all healthy" from "an
over-broad pattern checked nothing".

`--allow-status` is for hosts that answer link checkers with `403`/`429`
while serving browsers fine: a listed status counts as healthy instead of
failing CI.

## 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 (falling back to GET when a
   host rejects HEAD with 405/403/501, following up to 5 redirects)
4. Verifies internal link targets exist on disk (checks `.md`, `_index.md`, `index.md`)
5. Accepts routes the build generates rather than reads from disk
6. Accepts pipeline-emitted assets found in the last build's output (see
   [Build output as evidence](#build-output-as-evidence))
7. Reports broken or unreachable links

External links that resolve to private or internal addresses (localhost,
RFC 1918 ranges, `.local`/`.internal` hosts) are never contacted. They are
reported as skipped instead, both in the human output and under
`skipped_external` in the JSON payload.

### Generated routes

Some URLs have no source file at all, because the build writes them. Those are
resolved from `config.toml`, so `check-links` can run **before** the first
build (the order a lint-then-build CI pipeline uses):

- `/sitemap.xml`, `/robots.txt`, `/llms.txt`, the search index, and `404.html`,
  each honouring its configured `filename`
- Feeds (`/rss.xml`, `/atom.xml`), including the per-language copies
  (`/ko/rss.xml`) and the per-section ones (`/posts/rss.xml`). A section feed
  only counts when the section's `_index.md` sets `generate_feeds = true`,
  since that is what makes the build write it
- Taxonomy listing and term pages (`/tags/`, `/categories/rust/`)
- Paginated listings (`/posts/page/2/`), only for a section that actually
  declares `paginate_by`, so a `/page/N/` link under a non-paginated section
  is still reported

## 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

```
hwaro: check-links content
scan: 30 external, 20 internal

    [err] content/blog/post.md
      -> https://old-site.com/page  404
    [err] content/blog/post.md
      -> ../missing-page  Internal link target not found
    [err] content/about.md
      -> /images/photo.png  Image not found
checked: 50 links, 3 dead
```

In a color terminal each dead link renders as a `✗ file` item with a `→ url
status` detail line under an `hwaro check-links` heading, closed by a `✦ checked`
outcome (`checked: 50 links · all healthy` when everything resolves). The
command exits non-zero when dead links are found, so it can gate CI.

## JSON Output

```json
{
  "dead_internal": [
    {
      "link": {
        "file": "content/about.md",
        "url": "/images/photo.png",
        "kind": "image"
      },
      "status": -1,
      "error": "Image not found"
    }
  ],
  "dead_external": [
    {
      "link": {
        "file": "content/blog/post.md",
        "url": "https://old-site.com/page",
        "kind": "external"
      },
      "status": 404,
      "error": null
    }
  ],
  "skipped_external": [
    {
      "link": {
        "file": "content/notes/intranet.md",
        "url": "http://wiki.internal/page",
        "kind": "external"
      },
      "status": -1,
      "error": "Skipped: private/internal address"
    }
  ],
  "ignored_count": 0,
  "output_hint": null
}
```

`output_hint` is `null` unless the build output changed how the result should
be read (see below). The human report prints the same sentence; `--json`
carries it so a CI run that never sees the terminal output still gets it.

## Build Output as Evidence

Some links point at files no source explains: a compiled stylesheet, a
resized image variant, anything published through `[content.files]` or the
asset pipeline. `check-links` accepts those when it finds them in the last
build's `[build] output_dir` (`public/` by default), the only evidence
available to a command that runs outside the build.

That tree has to come from `hwaro build`. Since Hwaro 0.19, `hwaro serve`
builds into `.hwaro/serve/` and leaves `output_dir` alone, so a serve-only
workflow has nothing there. `check-links` now says so instead of reporting a
pile of dead links with no explanation:

```
checked: 4 links, 1 dead
  [info] public/ holds no build output — run `hwaro build` first; check-links
         validates build output, not `hwaro serve` output (.hwaro/serve/)
```

- **Absent or empty** — the note is printed alongside the dead links it
  explains.
- **`hwaro serve` output** (a leftover `.hwaro-dev` marker) — never used as
  evidence, the same rule `hwaro deploy` applies. `hwaro build` clears the
  marker.
- **Older than your newest source file** — noted under an otherwise healthy
  report, because a page you deleted still has its `index.html` standing in
  that tree and its links still resolve against it.

Run `hwaro build` before `check-links` in CI to check against real output;
source-only routes (`/about/`, `/tags/`, feeds, the sitemap) never need it.

---

Title: ci (deprecated)
URL: https://hwaro.hahwul.com/start/tools/ci/
Source: content/start/tools/ci.md
Language: en

> **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
Language: en

Convert frontmatter between TOML, YAML, and JSON 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 all frontmatter to JSON
hwaro tool convert to-json

# Convert only in a specific directory
hwaro tool convert to-yaml -c posts

# Preview which files would change without touching anything
hwaro tool convert to-yaml --dry-run

# Output result as JSON
hwaro tool convert to-yaml --json
```

The command accepts one format argument (`to-yaml`, `to-toml`, or `to-json`).
Extra positional arguments are rejected; use flags such as `--content-dir` for
additional options.

## Options

| Flag | Description |
|------|-------------|
| -c, --content-dir DIR | Limit conversion to a specific content directory |
| --dry-run | Preview what would be converted without changing any file |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

Conversion rewrites files in place and cannot preserve front-matter comments,
so run `--dry-run` first on a tree you care about: it runs the full
detection/conversion pipeline, including the per-file "dropping N comment
line(s)" warnings, without writing anything back.

## JSON Output

```json
{
  "success": true,
  "message": "Converted 5 files to YAML",
  "converted_count": 5,
  "skipped_count": 2,
  "error_count": 0,
  "dry_run": false
}
```

## Skipped Files

The human summary breaks the skip count down by reason: `already TOML`,
`without front matter`, and `not front matter`:

```
converted: 5 files · 2 skipped (1 already TOML, 1 not front matter)
```

`not front matter` is the one worth reading. It means the file opens with a
`---`/`+++` pair whose contents are prose, not a key/value mapping (a thematic
rule, say). Rewriting it would delete the author's text, so the file is left
untouched and named on stderr.

## 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.
```

After `hwaro tool convert to-json`:

```markdown
{
  "title": "My Post",
  "date": "2024-01-15",
  "tags": [
    "crystal",
    "tutorial"
  ]
}

Content here.
```

---

Title: doctor
URL: https://hwaro.hahwul.com/start/tools/doctor/
Source: content/start/tools/doctor.md
Language: en

Diagnose configuration, template, and structure issues in your Hwaro site.

> For content validation (frontmatter, alt text, internal links), use [`hwaro tool validate`](/start/tools/validate/).

```bash
hwaro doctor

# Check only a specific content directory
hwaro doctor -c posts

# Normalize config values (base_url trailing slash, sitemap priority, …)
hwaro doctor --fix

# Add recommended config sections to config.toml
hwaro doctor --approve

# Do both (equivalent to --fix --approve)
hwaro doctor --full

# Preview changes without writing config.toml
hwaro doctor --full --dry-run

# Output result as JSON
hwaro doctor --json
```

> `hwaro tool doctor` also works as a backward-compatible alias.

## Options

| Flag | Description |
|------|-------------|
| -c, --content-dir DIR | Content directory to check (default: content) |
| --fix | Perform real fixes — normalize values (base_url trailing slash, sitemap priority, …) |
| --approve | Approve and add recommended optional config sections |
| --full | Both `--fix` and `--approve` |
| --dry-run | Preview changes without writing `config.toml` |
| --strict | Treat warnings as errors when computing the exit code |
| --max-warnings N | Exit non-zero when warning count exceeds N |
| -j, --json | Output result as JSON |
| -q, --quiet | Suppress info output and banner |
| -h, --help | Show help |

## What It Checks

**Config diagnostics:**

- `base_url` is not set, or has a trailing slash
- `title` is still a placeholder (`Hwaro Site`, `My Hwaro Site`)
- `sitemap.changefreq` has an invalid value
- `sitemap.priority` is out of range (0.0 to 1.0)
- Duplicate taxonomy names or language codes
- Invalid `search.format`, `markdown.math_engine` or `pwa.cache_strategy` value
- `default_language` with no matching `[languages.<code>]` block
- `deployment.target` / `[related] taxonomies` referencing something undefined
- `[[menus.*]]` entries whose `parent` names no identifier in the same menu
- Referenced files and directories that don't exist (`[og] default_image`,
  `[pwa] icons`, `[auto_includes] dirs`, `[[assets.bundles]] files`, …).
  Values that carry their own origin (`https://…`, `//cdn…`, `data:…`) are
  left alone, since doctor can't validate a remote URL.
- Build output that cannot back a route check (see
  [Build output as evidence](#build-output-as-evidence))

**Template diagnostics:**

- Templates directory not found
- Required templates missing (`page.html`, `section.html`)
- Template syntax errors, reported by the same Crinja parser the build uses
  (unknown project shortcodes are tolerated)

**Content diagnostics:**

- Content directory not found (the build would produce no pages)
- Front matter that fails to parse (TOML/YAML)
- Front matter registering a menu name no `[[menus.*]]` declares

**Structure diagnostics:**

- Section directories missing `_index.md`

## Example Output

```
hwaro: doctor

  config.toml
    [ok]   file present & parseable
    [warn] base_url, title
    [ok]   sitemap (changefreq, priority)
    [ok]   taxonomies (duplicates)
    [ok]   search (format)
    [ok]   languages (default_language resolves)
    [ok]   markdown / pwa (valid enums)
    [ok]   image processing (widths set)
    [ok]   deployment / related (refs resolve)
    [ok]   menus (parent references)
    [ok]   referenced files & dirs
    [ok]   build output (route evidence)
    [ok]   sass (sources & enablement)

  templates/
    [ok]   required files (page.html, section.html)
    [ok]   template syntax

  content/
    [ok]   directory present
    [ok]   front matter (TOML/YAML parse)
    [ok]   front matter menus (declared in config)
    [info] section index files (_index.md)

Config:
  [warn] config.toml: base_url is not set

Structure:
  [info] content/docs: Section directory missing _index.md: docs/

checked: 0 errors, 1 warning, 1 info

Tip: Use 'hwaro tool validate' for content checks
```

A check whose scan never ran renders as `[--] … (skipped)` rather than as a
passing check, for example `template syntax` when `templates/` is missing.

In a color terminal the check lines use `✓`/`⚠`/`✗`/`ℹ` glyphs under an
`hwaro doctor` heading, and the summary is a severity-colored `✦ checked` outcome
line. A clean run ends with `checked: no issues found — your site looks great`.

## Build Output as Evidence

`[pwa] offline_page` and `[pwa] precache_urls` are routes, not files. Doctor
resolves them against `content/` first and, for values that carry an
extension such as a compiled stylesheet or a resized image variant, against
the last build in `[build] output_dir` (`public/` by default).

That tree has to come from `hwaro build`. Since Hwaro 0.19, `hwaro serve`
builds into `.hwaro/serve/` and leaves `output_dir` alone, so in a serve-only
workflow it is either absent or frozen at an old build. Doctor now says so
instead of leaving you to guess:

- **Absent or empty** — reported as `build-output-unusable`, alongside the
  route it could not validate: *"public/ holds no build output — run `hwaro
  build` first"*.
- **`hwaro serve` output** (a leftover `.hwaro-dev` marker) — never used as
  evidence, the same rule `hwaro deploy` applies. `hwaro build` clears the
  marker.
- **Older than your newest source file** — reported as `build-output-stale`
  when a route was accepted from it, because a page you deleted still has its
  `index.html` standing in that tree.

Both are `info` level and appear only when the tree actually mattered: a site
that references no build-generated path never hears about `public/`.

## Ignoring Known Issues

If doctor reports issues you are aware of and want to suppress, add their rule IDs to the `[doctor]` section in `config.toml`:

```toml
[doctor]
ignore = [
  "title-default",
  "structure-missing-index",
]
```

Use `hwaro doctor --json` to find rule IDs in the output. Ignored issues are completely excluded from both human-readable and JSON output.

> `ignore` only silences **warning** and **info** issues. Error-level rules
> (marked ✗ below) report problems that will fail `hwaro build` anyway, so
> listing one cannot disable the CI gate. Doctor keeps reporting it and warns
> that the entry has no effect.

### Available Rule IDs

Rows marked ✗ are error level and **cannot** be ignored.

| ID | Category | Description |
|----|----------|-------------|
| `config-not-found` | config | Config file not found ✗ |
| `config-parse-error` | config | Failed to parse config ✗ |
| `base-url-missing` | config | base_url is not set |
| `base-url-trailing-slash` | config | base_url has trailing slash |
| `title-default` | config | Title is still a scaffold placeholder |
| `sitemap-changefreq-invalid` | config | Invalid sitemap.changefreq |
| `sitemap-priority-range` | config | sitemap.priority out of range |
| `taxonomy-duplicate` | config | Duplicate taxonomy name |
| `language-duplicate` | config | Duplicate language code |
| `search-format-invalid` | config | Unsupported search.format |
| `default-language-undefined` | config | default_language has no `[languages.<code>]` block |
| `markdown-math-engine-invalid` | config | Unsupported markdown.math_engine |
| `pwa-cache-strategy-invalid` | config | Unsupported pwa.cache_strategy |
| `pwa-display-invalid` | config | Unsupported pwa.display |
| `image-processing-widths-empty` | config | image_processing enabled but widths is empty (silent no-op) |
| `deployment-target-undefined` | config | deployment.target names no `[[deployment.targets]]` |
| `related-taxonomy-undefined` | config | `[related]` references an undefined taxonomy |
| `menu-parent-undefined` | config | Menu entry's `parent` matches no identifier in that menu |
| `config-path-missing` | config | Referenced file does not exist |
| `config-dir-missing` | config | Referenced directory does not exist |
| `build-output-unusable` | config | `[build] output_dir` could not validate a route (absent, or `hwaro serve` output) |
| `build-output-stale` | config | A route was accepted from build output older than the sources |
| `missing-config-*` | config_missing | Missing config section (e.g. `missing-config-pwa`) |
| `template-dir-missing` | template | Templates directory not found ✗ |
| `template-required-missing` | template | Required template missing ✗ |
| `template-syntax-error` | template | Template fails to parse ✗ |
| `template-read-error` | template | Failed to read template ✗ |
| `content-dir-missing` | content | Content directory not found |
| `content-frontmatter-invalid` | content | Front matter fails to parse ✗ |
| `content-read-error` | content | Failed to read content file ✗ |
| `menu-undeclared` | content | Front matter menu name not declared in config |
| `structure-missing-index` | structure | Section missing _index.md |

An entry that matches no rule id is reported as having no effect, so a typo
in this list never passes silently.

## JSON Output

```json
{
  "schema_version": 1,
  "issues": [
    {
      "id": "base-url-missing",
      "level": "warning",
      "category": "config",
      "file": "config.toml",
      "message": "base_url is not set"
    }
  ],
  "summary": {
    "errors": 0,
    "warnings": 1,
    "infos": 0,
    "total": 1
  },
  "exit_code": 0
}
```

---

Title: export
URL: https://hwaro.hahwul.com/start/tools/export/
Source: content/start/tools/export.md
Language: en

Export hwaro content to other static site generator formats. This is the reverse of `hwaro tool import`.

Source files can use TOML (`+++`), YAML (`---`), or JSON (`{...}`) front matter.
All three formats use the same field mappings and draft filtering. Invalid JSON
front matter is reported as an export error instead of being copied into the body.

```bash
# Export to Hugo
hwaro tool export hugo

# Export to Jekyll
hwaro tool export jekyll

# Specify output and content directories
hwaro tool export hugo -o ~/hugo-site -c posts

# Include draft content
hwaro tool export jekyll --drafts

# Verbose output
hwaro tool export hugo --verbose
```

## Supported Targets

| Target | Description |
|--------|-------------|
| hugo | Export to Hugo format (TOML frontmatter, content/ structure) |
| jekyll | Export to Jekyll format (YAML frontmatter, _posts/ naming convention) |

## Options

| Flag | Description |
|------|-------------|
| -o, --output DIR | Output directory (default: export) |
| -c, --content-dir DIR | Content directory (default: content) |
| -d, --drafts | Include draft content |
| --dry-run | Preview every destination without writing anything |
| -v, --verbose | Show detailed output |
| -j, --json | Output a per-file manifest as JSON |
| -h, --help | Show help |

Re-exporting into the same directory **replaces** the previous output. That
is the normal refresh workflow. When a run replaces pre-existing files, the
summary warns with the count, and the JSON manifest marks those rows
`overwritten` (fresh destinations are `exported`). Use `--dry-run` to see the
full manifest before writing.

## JSON Output

```json
{
  "success": true,
  "dry_run": false,
  "exported_count": 2,
  "skipped_count": 0,
  "error_count": 0,
  "files": [
    { "path": "export/_posts/2024-01-01-hello.md", "action": "exported" },
    { "path": "export/about.md", "action": "overwritten" }
  ]
}
```

`files` lists every destination written, page-bundle assets included,
while the counts cover content documents only.

## Field Mappings

### Hugo

| Hwaro | Hugo |
|-------|------|
| title | title |
| date | date |
| description | description |
| draft | draft |
| updated | lastmod |
| tags | tags |
| series | series |
| aliases | aliases |
| image | images (array) |
| expires | expiryDate |
| weight | weight |
| [taxonomies] table | flattened to top-level `tags` / `categories` / … |

Every other front-matter key is passed through as a Hugo page param.

Output structure preserves the original directory layout under `export/content/`.

### Jekyll

| Hwaro | Jekyll |
|-------|--------|
| title | title |
| date | date |
| description | description |
| draft = true | published: false |
| tags | tags |
| categories | categories |
| image | image |
| template | layout |
| [taxonomies] table | flattened to top-level `tags` / `categories` / … |

Output conventions:
- Regular posts go to `_posts/` with `YYYY-MM-DD-slug.md` filename
- Draft posts go to `_drafts/` without date prefix
- Section index files (`_index.md`) become `index.md` pages
- Frontmatter is converted from TOML, YAML, or JSON to YAML (`---`)
- A `[taxonomies]` table is hoisted to top-level keys, since neither Hugo nor
  Jekyll reads taxonomy membership from a nested table. An explicit top-level
  key of the same name wins, matching how the build resolves the two

## Internal Links

Internal links using the `@/` prefix are automatically converted to absolute paths:

```markdown
<!-- Hwaro -->
[About](@/about/_index.md)

<!-- Exported -->
[About](/about)
```

## Example Output

```
hwaro: export hugo
source: content
output: export
exported: 38 files, 4 skipped
```

An `errors` count is appended only when errors occurred. In a color terminal
the same report renders as an `hwaro export` heading with aligned rows and a
`✦ exported` outcome line.

---

Title: import
URL: https://hwaro.hahwul.com/start/tools/import/
Source: content/start/tools/import.md
Language: en

Import content from other static site generators or platforms into hwaro. This is the reverse of [`hwaro tool export`](/start/tools/export/).

```bash
# Import a WordPress WXR file
hwaro tool import wordpress path/to/export.xml

# Import a Jekyll site directory
hwaro tool import jekyll path/to/jekyll-site

# Import a Hugo site
hwaro tool import hugo path/to/hugo-site

# Import a Notion export
hwaro tool import notion path/to/notion-export

# Import an Obsidian vault
hwaro tool import obsidian path/to/vault

# Specify output directory and include drafts
hwaro tool import jekyll path/to/site -o content/blog --drafts

# Verbose output
hwaro tool import hugo path/to/site --verbose
```

## Supported Sources

| Source | Input | Notes |
|--------|-------|-------|
| wordpress | WXR XML file | Imports posts and pages from a WordPress export file |
| jekyll | Site directory | Reads `_posts/` and (with `--drafts`) `_drafts/` |
| hugo | Site directory | Reads `content/` preserving section layout |
| notion | Export directory | Recursively imports `.md` files from a Notion export |
| obsidian | Vault directory | Recursively imports notes (skips dot-prefixed folders) |
| hexo | Site directory | Reads `source/_posts/` and `source/_drafts/` |
| astro | Site directory | Reads `src/content/` collections |
| eleventy | Site directory | Reads Markdown files with Eleventy front matter |

## Options

| Flag | Description |
|------|-------------|
| -o, --output DIR | Output content directory (default: `content`) |
| -d, --drafts | Include draft content |
| --force | Overwrite existing files instead of skipping |
| --dry-run | Preview every destination without writing anything |
| -v, --verbose | Show detailed output |
| -j, --json | Output a per-file manifest as JSON |
| -h, --help | Show help |

`--dry-run` resolves every destination, collision renames and skip decisions
included, and reports the counts and manifest without touching disk, so you
can inspect exactly what a large import will do before running it for real.

## JSON Output

```json
{
  "success": true,
  "dry_run": false,
  "imported_count": 2,
  "skipped_count": 1,
  "error_count": 0,
  "files": [
    { "path": "content/posts/hello.md", "action": "imported" },
    { "path": "content/posts/second.md", "action": "imported" },
    { "path": "content/posts/existing.md", "action": "skipped" }
  ]
}
```

`action` is `imported`, `skipped` (destination already exists and `--force`
was not passed), or `overwritten` (`--force` replaced an existing file).
`files` lists every destination the run resolved, page-bundle assets
included, while the counts cover content documents only; sources skipped
before a destination was resolved (drafts without `--drafts`, unsafe slugs)
appear in the counts but have no row.

## Behavior

- Front matter is converted to hwaro's default TOML format (`+++`). Hwaro also supports YAML front matter (`---`): run `hwaro tool convert to-yaml` afterwards, or set `[content.new].front_matter_format = "yaml"` in `config.toml` to change what `hwaro new` scaffolds from then on. Note that `front_matter_format` only applies to the built-in template. An archetype supplies its own front matter verbatim, and every scaffold ships `archetypes/default.md`, so delete it (or the matching archetype) if you want the config setting to take effect. See [Archetypes](/writing/archetypes/).
- HTML content (e.g. WordPress) is converted to Markdown.
- Existing files at the destination path are **skipped**, not overwritten. Remove or rename them first if you want to re-import, or pass `--force`.
- When two source files resolve to the **same** destination (a duplicate slug, two same-titled notes, a stripped `YYYY-MM-DD-` date prefix, two collection subfolders flattened into one section), the second and later ones are written alongside the first as `slug-1.md`, `slug-2.md`, … instead of one silently overwriting the other. The number of renamed destinations is reported once at the end of the run rather than one line per file.
- `--force` means "overwrite files that pre-dated this import". It never lets one imported file clobber another that the *same run* just wrote; those still get the `-1` / `-2` suffix above. Re-running an import is therefore idempotent: every source resolves to the destination it picked the first time and is skipped (or overwritten with `--force`), instead of accumulating `-1` copies on each run.
- Only known post types are imported (e.g. WordPress `post` and `page`).

## Example Output

```
hwaro: import jekyll
source: ./old-blog
output: content
imported: 42 files, 3 skipped
```

An `errors` count is appended only when errors occurred, and a warning reminds
you about `--force` when files were skipped. In a color terminal the same
report renders as an `hwaro import` heading with aligned rows and a `✦ imported`
outcome line.

## See Also

- [`hwaro tool export`](/start/tools/export/) — Export hwaro content to other formats
- [Writing Pages](/writing/pages/) — Front matter reference

---

Title: list
URL: https://hwaro.hahwul.com/start/tools/list/
Source: content/start/tools/list.md
Language: en

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

# The 5 newest published files
hwaro tool list published --limit 5

# Sort by title (A→Z), or reverse any ordering
hwaro tool list all --sort title
hwaro tool list all --sort path --reverse

# Output result as JSON
hwaro tool list all --json
```

The command accepts one filter argument (`all`, `drafts`, or `published`).
Extra positional arguments are rejected; use flags such as `--content-dir` for
additional options.

## Options

| Flag | Description |
|------|-------------|
| -c, --content-dir DIR | Limit listing to a specific content directory |
| --sort KEY | Sort key: `date` (newest first, default), `title`, or `path` |
| -r, --reverse | Reverse the sort order |
| -n, --limit N | Show at most N files (applied after sorting) |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

`--limit` caps the result after sorting, so `--sort date --limit 5` means
"the 5 newest files", and `--sort date --reverse --limit 5` the 5 oldest.
`--sort title` uses the same case-sensitive ordering as the template
engine's `sort_by="title"`, so the CLI listing matches a rendered section
index.

The filter argument also accepts the shorthands `draft` (for `drafts`) and
`pub` (for `published`).

## Filters

| Filter | Description |
|--------|-------------|
| all | Show all content files |
| drafts | Show only drafts — `draft = true`, or a `draft` cascaded from a parent section |
| published | Show only the files a default `hwaro build` actually publishes |

`published` means what the build ships, not merely "not flagged draft". A
default build also drops future-dated pages (`date` in the future) and expired
ones (`expires` in the past), so those are reported separately:

| Status | Meaning |
|--------|---------|
| `[pub]` | Published by a default build |
| `[draft]` | `draft = true`, own or cascaded |
| `[future]` | `date` is in the future (build it with `--include-future`) |
| `[expired]` | `expires` has passed (build it with `--include-expired`) |

## JSON Output

```json
[
  {
    "path": "content/blog/my-post.md",
    "title": "My Post",
    "draft": false,
    "date": "2024-06-15T00:00:00+00:00",
    "status": "published",
    "expires": null
  },
  {
    "path": "content/blog/draft-post.md",
    "title": "Draft Post",
    "draft": true,
    "date": "2024-06-10T00:00:00+00:00",
    "status": "draft",
    "expires": null
  }
]
```

`status` is `published`, `draft`, `future` or `expired`. `draft` is kept for
existing consumers and is true only for actual drafts.

---

Title: platform
URL: https://hwaro.hahwul.com/start/tools/platform/
Source: content/start/tools/platform.md
Language: en

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
hwaro tool platform codeberg-pages

# 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 |
| codeberg-pages | `.forgejo/workflows/deploy.yml` | Codeberg Pages (Forgejo Actions) deploy workflow |

## 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**: your `[build] output_dir` (`public/` by default).
  A customized value is carried into every generated config, so the host
  publishes the directory `hwaro build` actually writes. For `gitlab-ci` a
  non-default directory also adds `publish:` to the `pages` job.
- **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/) | [Codeberg Pages](/deploy/codeberg-pages/) — Platform deploy guides
- [CLI Reference](/start/cli/#tool) — All tool commands

---

Title: stats
URL: https://hwaro.hahwul.com/start/tools/stats/
Source: content/start/tools/stats.md
Language: en

Show content statistics including post counts, word count metrics, tag distribution, and monthly publishing frequency.

`published` counts what a default `hwaro build` actually ships, so files it
drops are reported under their own reason: `drafts` (own or cascaded from a
parent section), `future` (`date` in the future) and `expired` (`expires` in
the past). Word counts, the tag distribution and the monthly chart cover the
published set only. Tags are read from a top-level `tags` list or, when that is
absent, from the `[taxonomies] tags` table, the same fallback the build uses.

```bash
# Show statistics for content directory
hwaro tool stats

# Use a custom content directory
hwaro tool stats -c posts

# Chart the top 30 tags instead of the default 15
hwaro tool stats --top 30

# Output as JSON
hwaro tool stats --json
```

## Options

| Flag | Description |
|------|-------------|
| -c, --content-dir DIR | Content directory (default: content) |
| --top N | Show the top N tags in the chart (default: 15) |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

## Example Output

```
hwaro: stats content
total: 42 files, 4 drafts · 1 future
words: 28,500 total, 678 avg
range: 120 min, 3,200 max

tags:
      crystal     12  ####################
      web          8  #############
      tutorial     5  ########

monthly:
      2024-01      3  ############
      2024-02      5  ####################
      2024-03      2  ########

counted: 42 files, 37 published, 4 drafts · 1 future
```

In a color terminal the same report renders as an `hwaro stats` heading, aligned
receipt rows, proportional bar charts, and a `✦ counted` outcome line. When
there are more tags than the chart budget, only the top N are charted
(`tags: top 15` by default; raise or lower it with `--top N`). The JSON
output always contains every tag regardless of `--top`.

## JSON Output

```json
{
  "total": 42,
  "published": 37,
  "drafts": 4,
  "future": 1,
  "expired": 0,
  "word_count": {
    "total": 28500,
    "average": 678,
    "min": 120,
    "max": 3200
  },
  "tags": {
    "crystal": 12,
    "web": 8,
    "tutorial": 5
  },
  "monthly": {
    "2024-01": 3,
    "2024-02": 5,
    "2024-03": 2
  }
}
```

---

Title: unused-assets
URL: https://hwaro.hahwul.com/start/tools/unused-assets/
Source: content/start/tools/unused-assets.md
Language: en

Scan static files and co-located content assets, then report files not referenced by any content or template.

```bash
# Find unused assets
hwaro tool unused-assets

# Specify directories
hwaro tool unused-assets -c posts -s assets

# Delete unused files (with confirmation prompt)
hwaro tool unused-assets --delete

# Delete without the prompt (scripts/CI)
hwaro tool unused-assets --delete --force

# Output as JSON
hwaro tool unused-assets --json

# Delete in JSON mode (requires --force, since there is no prompt)
hwaro tool unused-assets --delete --force --json
```

## Options

| Flag | Description |
|------|-------------|
| -c, --content-dir DIR | Content directory (default: content) |
| -s, --static-dir DIR | Static files directory (default: static) |
| -t, --templates-dir DIR | Templates directory scanned for references (default: templates) |
| --delete | Delete unused files (prompts for confirmation) |
| -f, --force | Skip the confirmation prompt when deleting (required for deletion under `--json`) |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

## What It Scans

**Asset sources:**
- Files in the `static/` directory (images, CSS, JS, fonts, media, etc.)
- Co-located assets in content directories (non-markdown files alongside `.md` files)

**Reference sources:**
- All content files (`.md`, `.markdown`)
- Template files (`.html`, `.j2`, `.jinja`, `.jinja2`, `.ecr`, plus `.css`, `.js`, `.xml`, `.json`, `.webmanifest`, `.svg`, `.txt`)
- Static sources that can reference other static files (`.css`, `.scss`, `.sass`, `.js`, `.json`, `.webmanifest`, `.xml`, `.svg`, `.txt`, `.html`, `.htm`)
- Data and translation files (`.yml`, `.yaml`, `.json`, `.toml` under `data/` and `i18n/`)
- `config.toml` values that name files

If your templates live outside `templates/`, point the scan at them with
`--templates-dir` — otherwise their asset references are invisible and the
assets they use are reported (and can be deleted) as unused. An explicitly
passed `--templates-dir` must exist (the path is resolved relative to the
current directory); the command refuses to run against a missing one rather
than silently scanning zero templates.

**Supported asset extensions:**
Images (png, jpg, jpeg, gif, svg, webp, avif, ico, bmp, tiff, tif), stylesheets (css), scripts (js), fonts (woff, woff2, ttf, eot, otf), media (mp4, webm, ogg, mp3, wav), documents (pdf, zip).

## Example Output

```
hwaro: unused-assets static
total: 24
referenced: 20
unused: 4
unused files:
    - static/old-logo.png
    - static/unused-banner.jpg
    - content/blog/my-post/draft-image.png
    - static/deprecated.css
    [info] dynamic references (e.g. template variables) may cause false positives
found: 4 unused assets
```

In a color terminal this renders as an `hwaro unused-assets` receipt with aligned
rows and a `✦ found` outcome line (`found: no unused assets` when everything is
referenced). With `--delete` the outcome becomes `deleted: N files` after
confirmation, or `cancelled: no files deleted`.

## JSON Output

```json
{
  "unused_files": [
    "static/old-logo.png",
    "static/unused-banner.jpg"
  ],
  "total_assets": 24,
  "referenced_count": 22,
  "unused_count": 2
}
```

## Limitations

- Asset filenames referenced dynamically via template variables (e.g., `{{ page.image }}`) may not be detected, resulting in false positives.
- The detection is based on filename matching. If two files in different directories share the same name, both may be considered referenced even if only one is actually used.

---

Title: validate
URL: https://hwaro.hahwul.com/start/tools/validate/
Source: content/start/tools/validate.md
Language: en

Validate content files for frontmatter completeness, accessibility, and structural correctness.

```bash
# Validate all content files
hwaro tool validate

# Validate a specific content directory
hwaro tool validate -c posts

# Fail CI on any warning, or cap the allowed warning count
hwaro tool validate --strict
hwaro tool validate --max-warnings 5

# Output as JSON
hwaro tool validate --json
```

## Options

| Flag | Description |
|------|-------------|
| -c, --content-dir DIR | Content directory (default: content) |
| --strict | Treat warnings as errors when computing the exit code |
| --max-warnings N | Exit non-zero when warning count exceeds N (default: unlimited) |
| -j, --json | Output result as JSON |
| -h, --help | Show help |

## What It Checks

- 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/JSON)
- Invalid date formats
- Mixed-case tags (e.g., `Crystal` instead of `crystal`)
- Draft files (reported as info)

## Example Output

```
hwaro: validate content

content/blog/draft.md:
      [warn] Missing description in frontmatter
      [info] File is marked as draft

content/about.md:
      [warn] Image missing alt text: ![](photo.jpg)
      [info] Tag has mixed case: "Crystal" (consider lowercase)

checked: 0 errors, 2 warnings, 2 info
```

In a color terminal the findings use `⚠`/`✗`/`ℹ` glyphs under an `hwaro validate`
heading, and the closing line is a severity-colored `✦ checked` outcome. The
command exits non-zero when error-level issues are found, so it can gate CI.

Exit codes mirror `hwaro doctor`: error-level findings exit with the content
error code (5), while warning-driven failures from `--strict` or
`--max-warnings` exit with the generic code (1), so a consumer can still tell a
broken file from a tightened gate. Both flags apply to `--json` runs too.

## Rule IDs

| ID | Level | Description |
|----|-------|-------------|
| `content-title-missing` | warning | Missing or "Untitled" title |
| `content-description-missing` | warning | Missing description |
| `content-alt-text-missing` | warning | Image without alt text |
| `content-internal-link-broken` | warning | Broken `@/` internal link |
| `content-date-invalid` | warning | Unrecognized date format |
| `content-frontmatter-toml-error` | error | TOML frontmatter parse error |
| `content-frontmatter-yaml-error` | error | YAML frontmatter parse error |
| `content-frontmatter-json-error` | error | JSON frontmatter parse error |
| `content-read-error` | error | Failed to read content file |
| `content-tag-mixed-case` | info | Tag has mixed case |
| `content-draft` | info | File marked as draft |

## JSON Output

```json
{
  "findings": [
    {
      "file": "content/blog/draft.md",
      "line": null,
      "rule": "content-description-missing",
      "severity": "warning",
      "message": "Missing description in frontmatter"
    }
  ]
}
```

---

Title: Templates
URL: https://hwaro.hahwul.com/templates/
Source: content/templates/_index.md
Language: en

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
└── hooks/              # Markdown render-element overrides (link/image/heading/codeblock)
```

The `shortcodes/` directory contains reusable components you can embed in Markdown. See [Writing: Shortcodes](/writing/shortcodes/) for usage and how to create custom shortcodes.

Beyond HTML, a page/section can additionally render sibling `templates/page.<fmt>.jinja` / `templates/section.<fmt>.jinja` files (JSON, XML, TXT, CSV) enabled via `[outputs]`. See [Output Formats](/features/output-formats/).

The `hooks/` directory overrides how individual Markdown elements render. See [Render Hooks](/templates/render-hooks/).

## 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
Language: en

Hwaro's template system centers on three core types: **Site**, **Section**, and **Page**. This page is a **template-side reference** for 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 |
| site.menus | Object | Named menus for the **default language** (see [Menus](#menus)) |

### 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
└── users/
    ├── alice.yml
    ├── bob.yml
    └── cho.yml
```

#### 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 %}
```

#### Subdirectories

Subdirectories under `data/` become nested maps. Each file becomes a child keyed by its filename (without extension), and the parent directory itself is iterable.

Given the layout above, `data/users/alice.yml`, `data/users/bob.yml`, and `data/users/cho.yml` are exposed as:

- `site.data.users.alice`, `site.data.users.bob`, `site.data.users.cho` — individual file contents
- `site.data.users` — a map you can iterate to list every user

```jinja
{% for name, user in site.data.users %}
  <h3>{{ name }}</h3>
  <p>{{ user.bio }}</p>
{% endfor %}
```

Directories nest arbitrarily: `data/users/admins/root.yml` → `site.data.users.admins.root`.

**Conflicts.** If a directory and a file share the same stem (e.g. `data/users.yml` alongside `data/users/`), the **directory wins** and the file is ignored. Hwaro emits a warning during the build so the shadowed file is not silently dropped.

### Remote Data Sources

`site.data` can also be fed from HTTP(S) endpoints, declared in `config.toml`. Each source is fetched **once per build, before anything renders**. Templates never trigger network requests, and every endpoint the build talks to is visible in one place.

For the standalone configuration guide, including cache behavior, offline error
policies, timeouts, and security boundaries, see [Remote Data Sources](/features/remote-data/).

```toml
[[data.remote]]
key = "team"                # exposed as site.data.team
url = "https://api.example.com/team"
format = "json"             # json | toml | yaml | csv (optional, see inference below)
headers = { Authorization = "Bearer ${API_TOKEN}" }
cache = "1h"                # skip the request while the cached copy is younger than this
on_error = "fail"           # fail | warn-and-use-cache | warn-and-skip
```

Templates consume the result exactly like a local data file (`site.data.team`), so a key can move between `data/team.json` and a remote source without touching any template. To turn the records themselves into pages instead of feeding templates, see [Content Generation](/features/content-generation/).

| Field | Required | Meaning |
|-------|----------|---------|
| `key` | yes | Name under `site.data`. Letters, digits, `_`, `-` only; each key may be declared once. Keys are compared case-insensitively, because `Team` and `team` would share one cache file on macOS and Windows, so they are rejected as duplicates. |
| `url` | yes | Absolute `http://` or `https://` URL. Other schemes are rejected at config load. |
| `format` | no | `json`, `toml`, `yaml`, or `csv`. When omitted, inferred from the response `Content-Type`, then from the file extension of the URL the request finally landed on (after any redirects). If neither identifies a format, the fetch fails with a hint to set `format` explicitly. |
| `headers` | no | Extra request headers. Treated as credentials: never logged, and dropped when a redirect leaves the original origin. |
| `cache` | no | Disk-cache TTL such as `"90s"`, `"30m"`, `"1h"`, `"7d"` (units combine: `"1h30m"`). While the cached copy is fresh, the build skips the request entirely. Without `cache`, every build refetches, but the last payload is still saved for `warn-and-use-cache`. |
| `on_error` | no | What to do when the fetch or parse fails. `fail` (default) aborts the build; `warn-and-use-cache` warns and builds from the last successfully fetched payload (any age); `warn-and-skip` warns and leaves `site.data.<key>` unset for this build. |

CSV payloads parse to an array of rows, each an array of stripped string cells, the same shape `load_data()` produces for `.csv` files.

**Environment variables.** `${VAR}` in `url` and `headers` values is replaced from the environment. A referenced variable that is not set fails the build with an error naming the variable (elsewhere in `config.toml` this is only a warning); write `${VAR:-default}` to provide a fallback instead. The error is raised when the source is actually fetched, so commands that never fetch (`hwaro deploy`, `hwaro new`, `hwaro tool ...`) keep working without the variable exported.

**Caching.** Payloads are cached under `.hwaro/remote_data/`, outside `data/` and every other directory `hwaro serve` watches, so serve rebuilds within the TTL reuse the cache instead of re-hitting the API, and cache writes never trigger a rebuild. The cache also survives `hwaro build --full` (only the page cache is cleared), and it is what lets an offline build succeed with `on_error = "warn-and-use-cache"`. `.hwaro/` is self-ignoring (hwaro writes `.hwaro/.gitignore` when creating it), so the cache never appears in `git status`. During a long `hwaro serve` session each source is fetched once and then reused in memory: an entry with a `cache` TTL is re-fetched on the first full rebuild after that TTL expires, and an entry without one is fetched once for the whole session rather than on every save. If a re-fetch fails while the session already holds a payload, serve warns and keeps using it, whatever `on_error` says, so an editor keeps working offline. `hwaro build` is unaffected: it is one process per build and always follows `cache`/`on_error` exactly. A changed payload invalidates cached pages the same way an edited `data/` file does.

**Timeouts.** Each source gets 10s to connect, 30s per read, and 120s overall. The last one spans every redirect hop and the whole body, so a source that trickles bytes just inside the read timeout can't stall the build. Exceeding any of them is a fetch failure, handled by `on_error` like any other.

**Collisions.** A remote `key` that also exists on disk (`data/team.json` next to `key = "team"`) is a config error naming both sources, since a key must have exactly one source, so `site.data.team` never silently depends on which one wins.

Remote sources are deliberately config-only: `load_data()` and shortcodes cannot take a URL. If you need more than a GET request per source (pagination, POST bodies, reshaping), fetch with a [pre-build hook](/features/build-hooks/#fetching-data-from-an-api) into `data/` instead.

### 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 (newest first), weight (lowest first), title (A→Z) |
| reverse | Bool? | false | Flip the natural sort order — see [Writing › Sections › Sort direction](/writing/sections/#sort-direction) |
| 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 |
| page.version | Object? | Documentation version (`nil` when unversioned) — see [page.version](#pageversion) |
| page.version_links | Array<VersionLink> | Version switcher rows (empty when unversioned) |

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.taxonomies | Object | This page's taxonomy terms (`page.taxonomies.tags`, `page.taxonomies.<name>`) |
| 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? | Summary HTML: the chunk before `<!-- more -->`, else `page.description`, else an automatic excerpt of the rendered body (`[content] summary_length`, one escaped `<p>`). Use with `\| safe` to embed (e.g. `{{ page.summary \| safe }}`); for `<meta name="description">` use `page.description` directly. |
| page.summary_truncated | Bool | `true` only when `page.summary` is an automatic excerpt that was cut short (useful for a "Read more" link). |
| page.assets | Array<String> | Static files in page bundle |
| page.series | String | Series name from front matter (empty if none) |
| page.series_index | Int | 1-based position within the series (requires `[series]` enabled) |
| page.series_pages | Array<Page> | All pages in the same series, sorted by `series_weight` |
| page.related_posts | Array<Page> | Pages sharing taxonomy terms (requires `[related]` enabled) |
| page.git | Object? | Commit metadata for the source file (requires `[git]` enabled; `nil` for uncommitted or generated pages). Fields: `hash`, `short_hash`, `lastmod` (Time), `first_commit` (Time), `author_name`, `author_email` — see [Git Metadata](/features/git-info/) |

### 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 reading order |
| page.higher | Page? | Next page in reading order |
| 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

Navigation follows the flat reading order across the entire site, similar to mdBook or Docusaurus. Pages are ordered depth-first through the section tree: **section index → section pages → subsections (recursive)**. Within each section, pages are sorted by the section's `sort_by` setting (weight, date, or title).

| 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.version

Only on sites with `[[versions.list]]` (see [Versioned Docs](/features/versioned-docs/)). `nil` for pages outside every version directory.

| Property | Type | Description |
|----------|------|-------------|
| .name | String | Version name (URL segment, e.g. "v2") |
| .label | String | Display label |
| .latest | Bool | Is the latest version |
| .url | String | Root URL of the version in the page's language |

### page.version_links

One row per configured version, in config order.

| Property | Type | Description |
|----------|------|-------------|
| .name | String | Version name |
| .label | String | Display label |
| .latest | Bool | Is the latest version |
| .url | String | Same page in that version if it exists, else that version's root |
| .exists | Bool | Counterpart page exists |
| .current | Bool | Row is the page's own version |

```jinja
{% for v in page.version_links %}
<a href="{{ base_url }}{{ v.url }}"{% if v.current %} aria-current="page"{% endif %}>{{ v.label }}</a>
{% endfor %}
```

The global `versions` list (`{% for v in versions %}`, `versions.latest`, `versions.all`) exposes every version's root URL in the current page's language.

### 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>
```

A top-level `outputs = ["json"]` in front matter is likewise an ordinary
unknown key that lands in `page.extra.outputs`, and it overrides the
`[outputs]` config default for that one page/section. See
[Output Formats](/features/output-formats/).

---

### 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 |
| pwa_tags | PWA manifest link, theme-color meta, and service-worker registration (empty unless `[pwa]` is enabled) |

```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 %}
```

---

### Paginator

Available in section and taxonomy term templates when pagination is enabled (`paginate` in [section front matter](/writing/sections/#front-matter), `paginate_by` for taxonomies). Page 1 lives at the section URL; later pages at `{url}/{paginate_path}/{n}/`.

| Property | Type | Description |
|----------|------|-------------|
| paginator.paginate_by | Int | Items per page |
| paginator.base_url | String | Pager base URL (`{url}/{paginate_path}/`) |
| paginator.number_pagers | Int | Total number of pages |
| paginator.first | String | First page URL |
| paginator.last | String | Last page URL |
| paginator.previous | String? | Previous page URL (nil on first page) |
| paginator.next | String? | Next page URL (nil on last page) |
| paginator.pages | Array<Page> | Pages on the current pager |
| paginator.current_index | Int | Current page number (1-based) |
| paginator.total_pages | Int | Same as `number_pagers` |

A `pagination_obj` variant exposes the same data as `previous_url`, `next_url`, `first_url`, `last_url`, `current_page`, `total_pages`, `total_items`, `per_page`, `has_previous`, `has_next`, and `html` (the pre-rendered nav, also available as the flat `pagination` variable).

```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 %}
```

---

### Taxonomy Variables

Available in taxonomy templates:

| Variable | Type | Description |
|----------|------|-------------|
| taxonomy_name | String | Taxonomy name (e.g., "tags") |
| taxonomy_term | String | Current term name (empty on the index page) |
| content | String | Pre-rendered listing HTML (terms or pages) |

For custom listings, use `get_taxonomy()`. See [Taxonomies](/writing/taxonomies/).

---

## Menus

`site.menus` exposes the **default language's** named menus (config `[[menus.*]]` + front-matter `menus`/`menu` registrations). Inside a template, prefer `get_menu(name="...")` over `site.menus.<name>`, since it resolves against the **current page's** language instead, falling back to the default language:

```jinja
{% for item in get_menu(name="main") %}
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
{% endfor %}
```

### Entry Properties

| Property | Type | Description |
|----------|------|--------------|
| name | String | Display label |
| url | String | Bare root-relative path, or untouched external URL — comparable to `page.url` |
| href | String | `url` with the site's `base_path` applied (internal) or unchanged (external) — use this in `<a href>` |
| identifier | String | Unique key within the menu |
| weight | Int | Sort order |
| external | Bool | `true` for `http://`, `https://`, or `//` URLs |
| children | Array\<Entry\> | Nested entries whose `parent` matches this entry's `identifier` |
| page | Page? | The registering page's data (front-matter-registered entries only; nil for config-only entries and for entries registered on a section) |

See [Menus](/features/menus/) for the full config/front-matter reference, hierarchy, and per-language behavior.

---

## 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
Language: en

Filters transform values in templates. Apply with the pipe `|` operator.

Hwaro ships its own filters on top of the standard Crinja (Jinja2) built-ins (`upper`, `lower`, `join`, `map`, `select`, `batch`, and friends), so both kinds work anywhere below.

## 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; `end` sets the suffix (default `...`) | {{ text \| truncate_words(20, end="…") }} |

## 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 }} |

`markdownify` follows the site's [`[markdown]`](/features/markdown-extensions/)
settings for safe mode and `smart_punctuation`, so its output matches how the
same text renders in page bodies. The rest of the extension pipeline
(footnotes, definition lists, containers, …) is not applied.

## Array Filters

| Filter | Description | Example |
|--------|-------------|---------|
| length | Get length | {{ items \| length }} |
| first | First element (empty on an empty collection) | {{ items \| first }} |
| last | Last element (empty on an empty collection) | {{ 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 }} |
| active_path | Is this URL the current page (or an ancestor of it)? | {{ item.url \| active_path }} |

`active_path` compares a URL (typically a [menu](/features/menus/) entry's `item.url`) against the current page. It's an exact match by default; pass `ancestor=true` to also match descendant pages:

```jinja
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
<a href="{{ item.href }}"{% if item.url | active_path(ancestor=true) %} class="open"{% endif %}>{{ item.name }}</a>
```

Both sides are normalized to one trailing slash before comparing, so `/posts` and `/posts/` are equal. The root path (`/`) only ever matches exactly, even with `ancestor=true`. An external `item.url` (`http://`, `https://`, `//`) never matches.

## 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 }}">
```

### Strings and Chaining

```jinja
{{ page.title | lower | slugify }}
{{ content | strip_html | truncate_words(100) }}
{{ description | default(value="No description") | upper }}

{% set tags = "a,b,c" | split(pat=",") %}
{% for tag in tags %}
  <span>{{ tag | trim }}</span>
{% endfor %}
```

### 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 %}

{# Unique tags across all pages #}
{% set all_tags = site.pages | map(attribute="tags") | flatten | unique %}
```

### 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>
```

---

## 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
Language: en

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). Exposes the standard [Page properties](/templates/data-model/#page), minus per-render computed fields (`permalink`, `lower`/`higher`, `ancestors`, `series_index`, `series_pages`, `related_posts`).

**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> |

`items` is ordered by the taxonomy's
[`terms_sort_by`](/writing/taxonomies/#sorting): `"name"` (the default,
alphabetical) or `"count"` (page count descending, name-ascending
tiebreak). Counts are site-wide across every language, matching the root
taxonomy index page.

**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)

---

### get_menu()

Access a named menu's resolved entry tree ([Menus](/features/menus/)):

```jinja
{% for item in get_menu(name="main") %}
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
{% endfor %}
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| name | String | Menu name (e.g., "main", "footer") |

**Returns:** Array\<Entry\>. Resolved against the **current page's** language, falling back to the default language when that language has no entries for `name`. An unknown/unregistered menu name returns an empty array (never nil), so a `{% for %}` loop never errors.

**Entry Properties:**

| Property | Type | Description |
|----------|------|--------------|
| name | String | Display label |
| url | String | Bare root-relative path, or untouched external URL |
| href | String | `url` with `base_path` applied (internal) or unchanged (external) — use this in `<a href>` |
| identifier | String | Unique key within the menu |
| weight | Int | Sort order |
| external | Bool | `true` for `http://`, `https://`, or `//` URLs |
| children | Array\<Entry\> | Nested entries |
| page | Page? | The registering page's data (front-matter-registered entries only) |

Prefer `site.menus.<name>` only when you specifically need the **default language's** menu regardless of the current page. `get_menu()` is almost always the right choice inside a shared nav partial.

---

## 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

`load_data()` reads from the local filesystem only, and paths are resolved inside the project directory. It cannot read a file outside the project, and it cannot fetch a URL. For a single HTTP(S) GET payload, use [`[[data.remote]]`](/features/remote-data/) to expose it as `site.data`; use a [pre-build hook](/features/build-hooks/) when the fetch needs multiple requests or transformation. Everything under `data/` is also exposed as `site.data` without a `load_data()` call.

**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>
```

---

### asset()

Resolve a bundled or fingerprinted asset to its final URL. When the [asset pipeline](/features/asset-pipeline/) is enabled, the input name is looked up in the build manifest so you always get the hashed filename.

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

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| name | String | Bundle or asset name (e.g. `main.css`, `app.js`) |

**Returns:** String. Absolute URL under `base_url`. When no manifest entry is found, the name is returned as a path under `base_url` unchanged, so templates keep working before you turn the pipeline on.

---

### asset_url()

Alias for `asset()`. Use whichever reads better in your templates.

---

### 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 | The variant's actual width — falls back to the requested width when no variant exists |
| height | Int | Requested height (0 when not passed) |
| 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.

Variants are never upscaled, so a 900px source asked for `width=1024` resolves
to a 900px file — and `img.width` reports `900`, so
`<img width="{{ img.width }}">` matches the file the browser loads. `height`
is only ever the value you passed (`0` when you passed none): the variant map
is rebuilt from filenames on incremental builds, so a real height is not
available without decoding every image.

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
- [Data Model › Paginator](/templates/data-model/#paginator) — pagination object in section templates
- [Filters](/templates/filters/) — Value transformation

---

Title: Render Hooks
URL: https://hwaro.hahwul.com/templates/render-hooks/
Source: content/templates/render-hooks.md
Language: en

Render hooks let you override how individual Markdown elements (links, images, headings, fenced code blocks, blockquotes, and tables) turn into HTML, without touching hwaro's Markdown parser. Drop a template in `templates/hooks/`, and every matching element on every page renders through it instead of the built-in markup.

If you don't create any `templates/hooks/render-*` template, nothing changes: hwaro renders exactly as it always has.

## File Layout

```
templates/
└── hooks/
    ├── render-link.html        # [text](url "title")
    ├── render-image.html       # ![alt](url "title")
    ├── render-heading.html     # ## Heading
    ├── render-codeblock.html   # ```lang ... ```
    ├── render-blockquote.html  # > quoted
    └── render-table.html       # | GFM | tables |
```

Each file is independent, so add only the ones you want to override. A site with just `render-image.html` gets a custom image wrapper and stock rendering for everything else.

Any other `hooks/render-*` name is unrecognized and logs a warning at build time.

## Context Variables

All values are Crinja `Value`s and, like every other hwaro template, **already HTML-escaped where that matters**. See [Rule 1](#rules) below before reaching for an `| e` filter.

### `render-link.html`

| Variable | Description |
|----------|--------------|
| `destination` | The link target, escaped. Empty string when `markdown.safe = true` and the destination uses an unsafe protocol (`javascript:`, etc.) |
| `title` | The link's `"title"` text, escaped. Empty string when absent |
| `text` | The already-rendered inner HTML of the link (may itself contain nested markup, or a hook-rendered `<img>` if the link wraps an image) |

### `render-image.html`

| Variable | Description |
|----------|--------------|
| `destination` | The image `src`, escaped (same unsafe-protocol rule as links) |
| `alt` | The image's alt text. Plain text only, even if the Markdown source nested inline markup in the alt (matches CommonMark: an image's "children" never produce tags) |
| `title` | The image's `"title"` text, escaped. Empty string when absent |

### `render-heading.html`

| Variable | Description |
|----------|--------------|
| `level` | Heading level as an integer (`1`–`6`) |
| `text` | The already-rendered inner HTML of the heading |
| `id` | The heading's id. Either a custom `{#id}` from the Markdown source, or an auto-generated, deduplicated slug (`heading`, `heading-1`, `heading-2`, …) |

### `render-codeblock.html`

| Variable | Description |
|----------|--------------|
| `lang` | The fence's language token, escaped (`python` in `` ```python ``). Empty string for a fence with no language |
| `options` | The raw Zola/Pandoc-style `{...}` options block after the language (see [Syntax Highlighting](/features/syntax-highlighting/)), or any trailing info-string text when there's no `{...}` block. Escaped |
| `code` | The fence body, HTML-escaped |
| `highlighted` | The server-mode syntax-highlighted body (hljs-class spans), or an empty string when `[highlight] mode` isn't `"server"`, highlighting is off, or the language has no lexer. A `{hide_lines=…}` fence option is already applied, so hidden lines never reach the template (nor `code`) in server mode |
| `name` | The parsed `{name=...}`/`{title=...}` filename label, escaped. Empty string when absent |
| `copy` | `"true"` when the copy button applies to this block (`[highlight] copy` / per-fence `{copy=...}`, never for mermaid), empty string otherwise. The template decides what markup to emit for it |

### `render-blockquote.html`

| Variable | Description |
|----------|--------------|
| `text` | The already-rendered inner HTML of the blockquote. Block-level content (paragraphs, lists, nested quotes), usually ending with a newline |

### `render-table.html`

| Variable | Description |
|----------|--------------|
| `html` | The complete stock `<table>...</table>` markup |
| `header_html` | The table's `<thead>...</thead>` section |
| `body_html` | The table's `<tbody>...</tbody>` section. Empty string for a header-only table |

All hook templates additionally see the standard `page` (`url`, `title`, `path`, `language`) and `config` (`base_url`, `title`) variables.

## Default-Equivalent Templates

These templates reproduce hwaro's stock output exactly, so they are a useful starting point to modify from:

```jinja
{# templates/hooks/render-link.html #}
<a href="{{ destination }}"{% if title is present %} title="{{ title }}"{% endif %}>{{ text }}</a>
```

```jinja
{# templates/hooks/render-image.html #}
<img src="{{ destination }}" alt="{{ alt }}"{% if title is present %} title="{{ title }}"{% endif %} />
```

```jinja
{# templates/hooks/render-heading.html #}
<h{{ level }} id="{{ id }}">{{ text }}</h{{ level }}>
```

```jinja
{# templates/hooks/render-codeblock.html #}
<pre><code{% if lang is present %} class="language-{{ lang }} hljs"{% endif %}>{% if highlighted is present %}{{ highlighted }}{% else %}{{ code }}{% endif %}</code></pre>
```

```jinja
{# templates/hooks/render-blockquote.html #}
<blockquote>
{{ text }}</blockquote>
```

```jinja
{# templates/hooks/render-table.html #}
{{ html }}
```

Note `{% if title is present %}`, not a bare `{% if title %}`. Crinja's truthiness only treats `false`/`0`/nil as falsy, so a bare `{% if title %}` would render `title=""` even when there's no title. The custom `is present`/`is empty` tests (also used throughout hwaro's own templates) check for that correctly.

The codeblock template's ` hljs` class matches stock output under the
default config (`[highlight] enabled = true`; most Highlight.js themes key
their base styling off that class). If you've disabled highlighting
entirely, stock output emits `class="language-{{ lang }}"` with no ` hljs`;
drop it from your hook to stay byte-identical.

## Example: Figure-Wrapped Images

```jinja
{# templates/hooks/render-image.html #}
<figure>
  <img src="{{ destination }}" alt="{{ alt }}" loading="lazy" />
  {% if title is present %}<figcaption>{{ title }}</figcaption>{% endif %}
</figure>
```

Every `![alt](src "caption")` in your Markdown now renders as a captioned `<figure>`, with no per-image markup needed in content files.

## Rules

1. **Values are pre-escaped, so emit them verbatim.** Autoescape is off in hwaro templates (the same as everywhere else), and `destination`/`title`/`alt`/`lang`/`options`/`code` are already HTML-escaped by the renderer. Piping any of them through `| e` double-escapes; piping `text` or `highlighted` through it corrupts already-rendered HTML.
2. **Keep conventional double-quoted `href`/`src` attributes.** Everything downstream (`@/internal-page.md` link resolution, subpath (`base_path`) prefixing of root-relative links, responsive-image `srcset`/`sizes` injection, and `loading="lazy"`) runs as a plain-text pass over the *final* HTML, matching on `href="..."` / `src="..."`. A hook that emits an unquoted or single-quoted attribute, or restructures the destination into something other than a normal attribute value, opts that element out of all of it. An `@/`-prefixed `destination` must land inside `href="..."` for `InternalLinkResolver` to find and resolve it.
3. **`render-heading.html` must emit an `<hN id="{{ id }}">` element.** The TOC (`{{ toc }}` / `page.toc`) and `insert_anchor_links` both post-process the final HTML looking for `<h1>` to `<h6>` tags with an `id` attribute; a hook that renders something other than a heading tag, or drops `id`, silently falls out of both.
4. **Don't transform `{{ text }}`.** It's already-rendered HTML, and on pages using shortcodes it may contain an internal placeholder comment (`<!--HWARO-SHORTCODE-PLACEHOLDER-N-->`) that gets swapped for the shortcode's output in a later pass. Filtering, truncating, or re-escaping `text` can corrupt or strand that placeholder.
5. **Mermaid owns its own fence.** With `[markdown] mermaid = true`, a `` ```mermaid `` fence always renders through the existing Mermaid pipeline (`<div class="mermaid">…</div>`), never through `render-codeblock.html`. This is a config-decided exception to "every hook always applies to every matching element." Set `mermaid = false` to have your codeblock hook render mermaid fences like any other language instead.
6. **Admonitions own their blockquotes.** With `[markdown] admonitions = true` (the default), a `> [!NOTE]`-style blockquote keeps rendering through the admonition pipeline (`<div class="admonition admonition-note">…</div>`), never through `render-blockquote.html`, the same config-decided pattern as Mermaid. Set `admonitions = false` to route those quotes through your hook like any other blockquote.
7. **No blank lines in `render-table.html` output.** Table hook output is spliced into the Markdown *before* the main parse, and an HTML block ends at the first blank line, so anything after it would be re-parsed as Markdown. hwaro collapses blank lines out of the output as a safety net, so multi-line templates work, but don't rely on blank-line-sensitive markup.
8. **Hooks don't apply inside table cells, footnote bodies, definition lists, or the front-matter `description`/summary text.** Those render through a separate, simpler inline-markdown path that never touches the main Markd parser hooks attach to (table *cells* keep that path even when `render-table.html` wraps the table itself). This is a known limitation, not a bug.

## Incremental Builds

Editing a file under `templates/hooks/` is tracked like any other template edit for `hwaro build --cache` and `hwaro serve`. But because a hook isn't reached via `{% include %}`/`{% extends %}` from any specific page template, hwaro can't narrow down which pages it affects. An edit to any `templates/hooks/render-*.html` file re-renders **every** page, regardless of `[build] template_deps`. See [Incremental Build](/features/incremental-build/).

## See Also

- [Syntax Highlighting](/features/syntax-highlighting/) — fence language/options parsing that feeds `render-codeblock.html`
- [Markdown Extensions](/features/markdown-extensions/) — `{#custom-id}` headings and Mermaid diagrams
- [Templates Overview](/templates/) — template directory layout and selection rules

---

Title: Syntax
URL: https://hwaro.hahwul.com/templates/syntax/
Source: content/templates/syntax.md
Language: en

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 %}
```

Tests are not filters, but they are documented on the same page. See [Filters › Tests](/templates/filters/#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
Language: en

Content lives in the `content/` directory. Write Markdown with TOML (`+++`), YAML (`---`), or JSON (`{...}`) front matter. TOML is the default; YAML is widely recommended; JSON is supported for users who prefer it.

## 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
Language: en

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.

`hwaro init` ships a starter `archetypes/default.md` (and scaffold-specific archetypes like `posts.md` for the blog scaffold) so `hwaro new` picks up front matter (TOML by default, with YAML and JSON also supported) with a `description` field out of the box. Edit or extend them to match your site's conventions.

## 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 local date as `YYYY-MM-DD`, or the `--date` value verbatim |
| `{{ tags }}` | Tags from `--tags` as a TOML array (`[]` if none) |
| `{{ draft }}` | `true` if `--draft` is passed, or the target path contains a `drafts` directory; `false` otherwise |
| `{{ description }}` | Description collected by the interactive `hwaro new` wizard; empty string when none is given |

### 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. The format and
default fields of that template are controlled by `[content.new]` in
`config.toml`:

```toml
[content.new]
front_matter_format = "toml"         # "toml" (default), "yaml", or "json"
default_fields = ["description"]      # extra keys to scaffold with empty values
bundle = false                        # true: scaffold foo/index.md instead of foo.md
```

Fields that overlap with the built-ins (`title`, `date`, `draft`, `tags`)
are ignored so they aren't duplicated with empty values.

### Leaf-bundle (directory) layout

When you plan to add multilingual siblings (`index.ko.md`) or colocated
images next to a page, you want the directory-per-page layout:

```
content/abcd/
└── index.md
```

Pick the layout per invocation, per archetype, or per site:

- **CLI:** `hwaro new posts/hello.md --bundle` (or `--no-bundle` to force
  the single-file form).
- **Archetype:** put `<!-- hwaro: bundle -->` as the first line of the
  archetype so any `hwaro new` using it defaults to bundle mode. The
  directive is stripped from the generated content.
- **Config:** `bundle = true` under `[content.new]` sets the house style.

Priority is CLI > archetype > config > single-file (the default).

## 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 = "{{ 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 }}
description = "{{ description }}"
tags = {{ tags }}
+++

# {{ title }}
```

This mirrors the `archetypes/default.md` that `hwaro init` ships. The
`{{ description }}` placeholder substitutes to an empty string for the flag
form and to the value you type in the interactive `hwaro new` wizard.

## 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**: `{{ draft }}` is `true` when `--draft` is passed, when you enable the draft toggle in the interactive wizard, or when the target path contains a `drafts/` segment

## 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
Language: en

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. YAML (`---` delimiters) and JSON (a top-level `{...}` object at the start of the file) are also supported. Content below becomes HTML.

```markdown
---
title: "My Page"
date: "2024-01-15"
---

Your content in **Markdown**.
```

```markdown
{
  "title": "My Page",
  "date": "2024-01-15"
}

Your content in **Markdown**.
```

For JSON, the first balanced `{...}` at the very start of the file is the front matter, and no fence is needed. The file must begin with `{` (no leading whitespace).

## Front Matter

### Required

| Field | Type | Description |
|-------|------|-------------|
| title | string | Page title |

### Common Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| date | string | — | Publication date: `YYYY-MM-DD`, optionally with time (`YYYY-MM-DD HH:MM:SS` or RFC 3339 datetime); unquoted TOML/YAML dates also work |
| 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.
```

With `[series]` enabled in `config.toml`, `page.series_index` (1-based position) and `page.series_pages` (all pages in the series) are computed at build time. They are template-only values, not front matter fields. See [Data Model](/templates/data-model/#computed-properties).

### 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.
```

Each alias is a path **on this site**, and the build writes a redirect stub at it.
An absolute (`https://example.com/old/`) or protocol-relative (`//example.com/old/`)
value is not something this build can publish, so it is skipped with a warning.

### 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

`page.summary` is what list pages, feeds and social cards show for a post. It is filled from the first of these sources that exists:

1. The content before a `<!-- more -->` marker (rendered as HTML)
2. The `description` front matter field
3. An automatic excerpt cut from the rendered body

Use `<!-- more -->` to define a summary explicitly:

```markdown
+++
title = "Long Article"
+++

This is the summary shown in listings.

<!-- more -->

The full article continues here...
```

### Automatic summaries

A page with neither a marker nor a `description` gets an automatic summary: the first 70 words of its rendered body, wrapped in a single `<p>` and followed by an ellipsis (`…`) when text was cut. The excerpt is built from the rendered HTML, so shortcodes are expanded and code blocks, headings, images and figures are skipped, so it reads as prose.

For CJK-dominant text (Chinese, Japanese, Korean), where words are not space-delimited, the limit counts characters at twice the configured number: `summary_length = 70` yields up to 140 characters. Cuts land on word boundaries (character boundaries for CJK) and never split an entity or a multibyte character.

Tune or disable it in `config.toml`:

```toml
[content]
summary_length = 70      # words (CJK: characters ×2); 0 disables the automatic summary
summary_ellipsis = "…"   # appended only when text was actually cut
```

`page.summary_truncated` is `true` only when the automatic excerpt was cut, so a template can show a "Read more" link only where it makes sense. Automatic summaries never replace a marker or a `description`; pages that have one keep their existing output.

## 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, because 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` |

#### Strict mode

To fail the build instead of just warning, opt in via `config.toml`:

```toml
[links]
broken_internal = "error"  # default: "warn"
```

In error mode the build collects every unresolved `@/` link across all pages and fails with a single aggregated list (`source.md → @/target (reason)`), mapping to exit code 5 for CI. During `hwaro serve` the failure appears in the error overlay and the server keeps running.

Caveat with `--cache`: only re-rendered pages are re-checked on warm builds, so a broken link inside an unchanged page won't resurface until that page renders again. CI should run a cold build (no `--cache`) for a complete check.

### Blockquotes

```markdown
> Quote text
```

### Admonitions

GitHub-style alert blocks render as styled callouts. Recognised types: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`.

```markdown
> [!NOTE]
> Pay attention to this paragraph.

> [!WARNING]
>
> Body can also live in its own paragraph.

> [!TIP] Custom title
> Text after the marker on the same line becomes the title (Obsidian / Hugo syntax).
```

The output is a `<div class="admonition admonition-{type}">` with a title paragraph (`<p class="admonition-title">`) followed by the body. Without a custom title the type name is used (`Note`, `Tip`, …). Style it from your CSS, since Hwaro emits semantic markup only.

Tables work inside admonitions and plain blockquotes: prefix every row with `>` as usual (`> | a | b |`, `> |---|---|`).

Disable by setting `admonitions = false` under `[markdown]` in `config.toml`.

Limitations: matching is type-case-sensitive (`[!NOTE]` only, not `[!note]`), and a nested blockquote inside an admonition body closes the outer admonition early. There is no inline escape. Backslash-escaping (`\[!NOTE\]`) renders the same characters and still triggers the admonition, so disable the feature if you need to render the literal token.

### Custom Heading IDs

Append `{#custom-id}` to a heading line to override the auto-generated slug. Useful when you want stable anchor URLs that don't break on title edits.

```markdown
## Installation Guide {#install}
```

Renders as `<h2 id="install">Installation Guide</h2>`. The TOC and any `[link](#install)` will use the custom id.

Allowed id characters: letters (any script), digits, `_`, `-`, `:`. The id may start with a digit — `{#1-create-a-project}` is valid, which matters for translated numbered headings that need to keep the original anchor — but not with `-` or `:`. CommonMark allows up to 3 leading spaces before an ATX heading; deeper indentation makes the line a code block, in which case `{#id}` is not applied.

Disable by setting `heading_ids = false` under `[markdown]` in `config.toml`.

Custom heading IDs require `markdown.safe = false`. Under safe mode the `{#id}` syntax is stripped from the rendered output and no id is applied, so use raw HTML headings if you need both safe mode and explicit ids. Writing the same `{#id}` twice in one page produces duplicate id attributes; the first anchor wins.

This `{#id}` shorthand is a special case of the more general `{#id .class key=val}` attribute block (`[markdown] attributes = true`), which also applies to inline images. See [Markdown Extensions](/features/markdown-extensions/).

### Definition Lists

```markdown
Term
: Definition body

Another term
: Definition with **bold**, *italic*, `code`, [a link](https://example.com), and ~~strikethrough~~
: A second definition for the same term
```

Inline Markdown works inside both terms and definitions. Raw HTML is escaped for safety.

## 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
Language: en

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 (see [Sort direction](#sort-direction)) |
| reverse | bool | false | Flip the natural sort order (see [Sort direction](#sort-direction)) |
| paginate | int | — | Pages per page |
| paginate_path | string | "page" | Path segment for pager URLs (default produces `/blog/page/2/`) |
| transparent | bool | false | Pass pages to parent |
| generate_feeds | bool | false | Generate RSS feed |
| redirect_to | string | — | Write an HTML redirect page to this URL instead of rendering the section |
| draft | bool | false | Exclude from production |
| weight | int | 0 | Section sort order |
| cascade | table | — | Defaults inherited by descendants (see [Cascade](#cascade)) |

## Cascade

A section's `[cascade]` table sets front matter defaults for every page and
section below it. A page's own front matter always wins, and deeper cascades
override shallower ones. The section declaring the cascade is not affected.

```toml
+++
title = "Blog"

[cascade]
template = "post"
tags = ["blog"]

[cascade.extra]
banner = "default-banner.png"
+++
```

Every page under the section now renders with the `post` template, carries the
`blog` tag, and exposes `page.extra.banner`, unless it sets those fields
itself. `extra` and `taxonomies` merge per key: the page's own keys win,
cascaded keys fill the gaps.

Cascadable keys: `template`, `draft`, `render`, `toc`, `insert_anchor_links`,
`in_sitemap`, `in_search_index`, `tags`, `taxonomies`, `authors`, `extra`.
URL-affecting keys (`slug`, `path`, `aliases`) cannot cascade and are ignored
with a warning.

On multilingual sites, a cascade only applies within its own language tree:
`_index.ko.md` cascades to `.ko` pages, `_index.md` to default-language pages.

## Sort direction

Each `sort_by` value has a different natural direction, chosen to match what authors usually want:

| `sort_by` | Default order | With `reverse = true` |
|-----------|---------------|------------------------|
| `date`    | Newest first (descending) | Oldest first |
| `weight`  | Lowest weight first (ascending) | Highest weight first |
| `title`   | A → Z (ascending) | Z → A |

`reverse` flips whichever direction is natural for the chosen `sort_by`. For example, a blog index sorted by `date` is newest-first by default; setting `reverse = true` switches it to oldest-first.

```toml
+++
title = "Blog"
sort_by = "date"
# reverse = false (default) → newest first
# reverse = true            → oldest first
+++
```

## Examples

### Blog with Pagination

```toml
+++
title = "Blog"
sort_by = "date"
paginate = 10
paginate_path = "p"
+++
```

Generates: `/blog/`, `/blog/p/2/`, `/blog/p/3/`

With the default `paginate_path = "page"`, the URLs are `/blog/page/2/`, `/blog/page/3/`, and so on, while page 1 always stays at the section URL.

### 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 — see [Data Model › Paginator](/templates/data-model/#paginator) |

Use `page.url` for the current section URL.

### `section.list` / `section_list`

```jinja
<ul class="auto-list">
  {{ section.list | safe }}
</ul>
```

For building a custom pagination UI with `paginator`, see [Data Model › Paginator](/templates/data-model/#paginator).

## 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
Language: en

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
{{ shortcode_name(arg1="value", arg2="value") }}
```

Or explicitly:

```markdown
{{ shortcode("shortcode_name", arg1="value") }}
```

### Block Shortcode Closers

Block shortcodes support two closer styles:

- **Bare closer** (simple):
  ```jinja
  {% note %}...{% end %}
  ```

- **Named closer** (recommended):
  ```jinja
  {% note %}...{% endnote %}
  {% alert(type="info") %}...{% endalert %}
  ```

**We strongly recommend named closers** (`{% endNAME %}`) for any non-trivial content. They make your Markdown much easier to read and maintain, especially when mixing multiple shortcodes or using deep nesting.

## Built-in Shortcodes

Hwaro ships with built-in shortcodes that work out of the box, with no template files needed.

### youtube

Embed a YouTube video.

```markdown
{{ youtube(id="dQw4w9WgXcQ") }}
{{ youtube(id="dQw4w9WgXcQ", width="800", height="450") }}
```

| 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
{{ vimeo(id="123456789") }}
```

| 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
{{ gist(user="octocat", id="abc123") }}
{{ gist(user="octocat", id="abc123", file="hello.rb") }}
```

| 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.

Both bare and named closers are supported (named closers are recommended for complex pages):

```markdown
{% alert(type="warning", title="Caution") %}Be careful with this!{% end %}
{% alert(type="tip") %}Using named closer also works{% endalert %}
```

(We recommend the named closer style for clarity.)

| Param | Default | Description |
|-------|---------|-------------|
| `type` | `info` | `info`, `warning`, `danger`, `tip`, `success` |
| `title` | (none) | Optional title |

### figure

Image with optional caption.

```markdown
{{ figure(src="/img/photo.jpg", alt="A photo", caption="My caption") }}
```

| 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
{{ tweet(user="jack", id="20") }}
```

| Param | Default | Description |
|-------|---------|-------------|
| `user` | (required) | Twitter username |
| `id` | (required) | Tweet ID |

### codepen

Embed a CodePen.

```markdown
{{ codepen(user="chriscoyier", id="gfdDu") }}
{{ codepen(user="chriscoyier", id="gfdDu", tab="css,result", height="400") }}
```

| 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 |

Every parameter marked **(required)** above lands directly in a URL or an
`src`. Omitting one still renders — into an embed that points nowhere
(`https://codepen.io//embed/gfdDu`) — so the build warns instead of leaving you
to find the dead embed on the published page:

```
[WARN] Shortcode `codepen` is missing required argument `user` — it renders a broken embed. Usage: `{{ codepen(user="…", id="…") }}`.
```

> 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 — and define their own contract, so the warning above does not apply to them.

## 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
{{ alert(type="warning", message="This is important!") }}
```

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
{{ youtube(id="dQw4w9WgXcQ") }}
```

### 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
{{ figure(src="/images/photo.jpg", alt="A photo", caption="My caption") }}
```

### 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
{{ gallery() }}
```

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
{% note() %}
This is the **body** content of the shortcode.
{% end %}
```

The body is passed to the shortcode template as the `body` variable. Markdown conversion is **not** applied automatically, so 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
{% outer() %}
  Some text with {{ inner(type="info") }} inside.
{% end %}
```

## Argument Syntax

### Named Arguments

Arguments support multiple quote styles:

```markdown
{{ alert(type="warning", message="Double quotes") }}
{{ alert(type='info', message='Single quotes') }}
{{ alert(type=danger, message=No quotes for simple values) }}
```

### Positional Arguments

When no `key=value` syntax is used, arguments are assigned as `_0`, `_1`, etc.:

```markdown
{{ youtube("dQw4w9WgXcQ") }}
```

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
Language: en

Taxonomies organize content into groups like tags, categories, or authors.

## Configuration

Define taxonomies in `config.toml`:

```toml
[[taxonomies]]
name = "tags"
feed = true
paginate_by = 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_by` | int | — | Items per page on term pages |
| `sort_by` | string | "date" | Order of pages within a term: `"date"`, `"title"`, or `"weight"` (see [Sorting](#sorting)) |
| `reverse` | bool | false | Flip whichever order `sort_by` produced |
| `terms_sort_by` | string | "name" | Order of the terms list: `"name"` or `"count"` (see [Sorting](#sorting)) |

## Sorting

`sort_by` controls the order of pages within each term: on the written
term pages, in `term.pages` from `get_taxonomy()`, and in per-term
pagination. The semantics match section sorting exactly:

- `"date"` (default): newest first; `reverse = true` gives oldest first.
- `"title"` — alphabetical ascending; `reverse = true` descends.
- `"weight"` — lowest weight first; `reverse = true` descends.

An invalid `sort_by` value logs a warning and keeps the `"date"` default.

`terms_sort_by` controls the order of the terms list, on the taxonomy
index page and in `get_taxonomy().items`:

- `"name"` (default): alphabetical ascending.
- `"count"` — page count descending, name-ascending tiebreak. On a
  multilingual site, each language's index uses that language's own page
  counts.

**Term feeds are exempt.** With `feed = true`, each term's RSS feed stays
reverse-chronological regardless of `sort_by`, because RSS consumers assume
newest-first entries.

```toml
[[taxonomies]]
name = "tags"
sort_by = "title"
terms_sort_by = "count"
```

## Using Taxonomies

Assign terms in front matter:

```markdown
+++
title = "My Post"
tags = ["crystal", "tutorial"]
categories = ["Programming"]
authors = ["Alice"]
+++
```

A Zola-style `[taxonomies]` table works too (both spellings are equivalent;
an explicit top-level key wins if both are present):

```markdown
+++
title = "My Post"
[taxonomies]
tags = ["crystal", "tutorial"]
tech = ["crystal", "security"]
+++
```

In templates, a page's own terms are available as `page.taxonomies.<name>`
(e.g. `{% for t in page.taxonomies.tech %}`), and also on the page objects
inside `section.pages`, `site.pages`, and term page lists.

## Generated URLs

For a taxonomy named `tags` with term `crystal`:

| URL | Content |
|-----|---------|
| `/tags/` | List of all tags |
| `/tags/crystal/` | Pages tagged "crystal" |

With `paginate_by` set, term pages paginate at `/tags/crystal/page/2/`, `/tags/crystal/page/3/`, … (page 1 stays at `/tags/crystal/`). The pager object is described in [Data Model › Paginator](/templates/data-model/#paginator).

## Templates

Both templates receive a ready-made listing as `{{ content }}`: the term list in `taxonomy.html`, the page list in `taxonomy_term.html`. For custom markup, use [`get_taxonomy()`](#get-taxonomy-function) instead of `content`.

### Taxonomy Index

`templates/taxonomy.html` — List of all terms:

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

{% block content %}
<h1>{{ page.title }}</h1>
{{ content }}
{% endblock %}
```

Custom term list:

```jinja
{% set tax = get_taxonomy(kind=taxonomy_name) %}
<ul>
{% for term in tax.items %}
  <li>
    <a href="{{ get_taxonomy_url(kind=taxonomy_name, term=term.name) }}">
      {{ term.name }} ({{ term.count }})
    </a>
  </li>
{% endfor %}
</ul>
```

### Taxonomy Term

`templates/taxonomy_term.html` — Pages for a specific term:

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

{% block content %}
<h1>{{ taxonomy_name }}: {{ taxonomy_term }}</h1>
{{ content }}
{% endblock %}
```

Custom page list, looking up the current term's pages via `get_taxonomy()`:

```jinja
{% set tax = get_taxonomy(kind=taxonomy_name) %}
{% for term in tax.items if term.name == taxonomy_term %}
<ul>
{% for p in term.pages %}
  <li><a href="{{ p.url }}">{{ p.title }}</a></li>
{% endfor %}
</ul>
{% endfor %}
```

## Template Variables

Available in both `taxonomy.html` and `taxonomy_term.html`:

| Variable | Type | Description |
|----------|------|-------------|
| taxonomy_name | String | Taxonomy name ("tags") |
| taxonomy_term | String | Current term name (empty on the index page) |
| content | String | Pre-rendered listing HTML (terms or pages) |

### Term Object

| Property | Type | Description |
|----------|------|-------------|
| name | String | Term name |
| slug | String | URL-safe name |
| pages | Array<Page> | Pages with this term |
| 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="{{ get_taxonomy_url(kind="tags", term=tag) }}">{{ tag }}</a>
{% endfor %}
</div>
{% endif %}
```

Use `get_taxonomy_url()` (or `term.slug` from `get_taxonomy()`) rather than `{{ tag | slugify }}`: when two terms collide on a slug (`Crystal` and `crystal`), the generator writes `/tags/crystal/` and `/tags/crystal-2/`, and only the function knows which is which.

### 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