> ## Documentation Index
> Fetch the complete documentation index at: https://manual.seahorse.dnotitia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> DOCX 템플릿 태그(Jinja2 스타일) 작성법 — 자리표시자/반복/조건/표

# Template guide

# Word 템플릿 작성 가이드

**경로**: 하단 툴바 **\[7] Word** → 템플릿 가이드
프로그래밍 경험이 없어도 따라할 수 있는 Word(.docx) 템플릿 작성 가이드입니다.
일반 문서에서 **바뀌는 부분만 태그(`{{ }}`)** 로 표시해두면, AI가 데이터를 채워 완성된 문서를 만듭니다.

<Info>
  원본 가이드: `seahorse-mcp-agent-server/docs/DOCX_TEMPLATE_GUIDE.md`.
  이 페이지는 템플릿 작성자를 위한 요약입니다.
</Info>

## 템플릿이란?

```
일반 문서: "주식회사 디노티시아에 2025년 1분기 제안서를 제출합니다."
템플릿: "{{ company_name }}에 {{ quarter }} 제안서를 제출합니다."
```

같은 양식으로 값만 바꿔 여러 문서를 생성할 수 있습니다.

## 시작하기 전에

**준비물**: Microsoft Word 또는 LibreOffice

### 핵심 규칙

| 규칙        | 올바른 예                                   |
| --------- | --------------------------------------- |
| 이름은 영문+밑줄 | `company_name` (O) / `회사이름` (X)         |
| 이름에 공백 없음 | `company_name` (O) / `company name` (X) |
| 중괄호 안에 공백 | `{{ name }}` (O) / `{{name}}` (X)       |
| 태그는 한 줄에  | 두 줄에 걸쳐 쓰지 않기                           |

변수 이름은 **영문 소문자 + 밑줄** 만 사용하세요. 좋은 예: `company_name`, `report_date`, `total_amount`.

## 태그 요약표

| 태그                                                 | 용도                   | Word 입력 예시                |
| -------------------------------------------------- | -------------------- | ------------------------- |
| `{{ name }}`                                       | 텍스트 삽입               | `담당자: {{ manager_name }}` |
| `{{r name }}`                                      | 서식 있는 텍스트 (RichText) | `{{r styled_title }}`     |
| `{{h name }}`                                      | 제목 (수준 포함)           | `{{h chapter_title }}`    |
| `{{t name }}`                                      | 표 전체 삽입              | `{{t monthly_report }}`   |
| `{{i name }}`                                      | 이미지 삽입               | `{{i logo }}`             |
| `{% for x in xs %}` ... `{% endfor %}`             | 반복                   | 목록/문단 반복                  |
| `{%tr for x in xs %}` ... `{%tr endfor %}`         | 표 행 반복               | 표의 첫·마지막 셀에 각각 입력         |
| `{%p for x in xs %}` ... `{%p endfor %}`           | 문단 반복                | 문단 단위                     |
| `{% if flag %}` ... `{% else %}` ... `{% endif %}` | 조건                   | 조건부 표시                    |

## 1. 기본 텍스트 자리표시자

```
수신: {{ recipient_name }} 귀하
일자: {{ date }}
제목: {{ title }}
```

<Warning>
  **Word 자동 서식 주의** — `{{` 입력 시 Word가 스마트 따옴표로 자동 변환하는 경우가 있습니다.

  * Word: **파일 → 옵션 → 언어 교정 → 자동 고침 옵션 → "자동 서식"** 탭에서 해제
  * 또는 메모장에서 먼저 타이핑 후 복사·붙여넣기
</Warning>

## 2. 서식이 있는 텍스트 (RichText)

글꼴 색상·굵기·크기 등을 데이터에서 제어:

```
프로젝트 설명: {{r project_description }}
```

* `{{ name }}` → 주변 텍스트 서식 따름
* `{{r name }}` → 데이터에서 서식 지정 가능

## 3. 반복 (목록/표 행)

### 목록

```
{% for item in items %}
- {{ item.name }}: {{ item.price }}원
{% endfor %}
```

### 표 행 반복 (중요)

<Warning>
  `{%tr %}` 태그는 반드시 **셀 안에서 별도의 줄** 에 작성하세요. 변수와 같은 줄에 쓰면 동작하지 않습니다.
</Warning>

2행짜리 표를 만들고, 반복할 행의 **첫 번째 셀** 에 Enter로 2줄:

```
{%tr for item in items %}
{{ item.name }}
```

**마지막 셀** 에 Enter로 2줄:

```
{{ item.price }}
{%tr endfor %}
```

### 문단 반복

```
{%p for item in items %}
{{ item.name }} - {{ item.description }}
{%p endfor %}
```

### 이름 규칙

* 목록 전체: 복수형 (`items`, `products`)
* 각 항목: 단수형 (`item`, `product`)
* 속성: 점(`.`) 뒤에 (`item.name`, `item.price`)

## 4. 조건부 표시

```
{% if show_disclaimer %}
본 문서의 내용은 대외비이며, 무단 복제를 금합니다.
{% endif %}
```

양자택일:

```
{% if is_domestic %}
국내 배송: 무료
{% else %}
해외 배송: 별도 문의
{% endif %}
```

조건 변수는 "\~인가?" 느낌으로: `show_footer`, `is_confidential`, `has_discount`.

## 5. 표 블록 `{{t }}`

AI가 **표 전체를 데이터로 만들어 삽입** 할 때:

```
아래는 분기별 매출 현황입니다.

{{t sales_table }}
```

### 반복(`{% for %}`) vs 표 블록(`{{t }}`) 차이

|       | `{% for %}` 반복 | `{{t }}` 표 블록 |
| ----- | -------------- | ------------- |
| 사용 시점 | 행만 반복, 표 구조 고정 | 표 전체를 데이터로 생성 |
| 헤더    | 템플릿에 직접 작성     | 데이터에서 제공      |
| 디자인   | 템플릿 서식 유지      | 기본 표 스타일      |

표 디자인을 꾸미려면 `{% for %}`, 구조 자체가 동적이면 `{{t }}`.

## 6. 제목 블록 `{{h }}`

제목 수준(1\~9)을 동적으로:

```
{{h chapter_title }}
```

제목 수준이 고정이면 Word에서 직접 "제목 1" 스타일을 쓰고 `{{ chapter_title }}` 만 쓰면 됩니다.

## 7. 이미지 블록 `{{i }}`

```
{{i company_logo }}
위 로고는 당사의 공식 로고입니다.
```

이미지 파일은 서버에서 접근 가능한 경로에 있어야 합니다.

## 8. 자주 하는 실수

| 증상          | 원인                  | 해결                 |
| ----------- | ------------------- | ------------------ |
| 태그가 그대로 출력  | `{{name}}` 공백 없음    | `{{ name }}`       |
| 태그가 깨져서 출력  | Word가 태그 중간에 서식 삽입  | 태그 지우고 한 번에 다시 타이핑 |
| 스마트 따옴표로 변환 | Word 자동 서식          | 자동 고침 옵션 해제        |
| 반복문 미동작     | `endfor` 누락         | `{% endfor %}` 확인  |
| 표 행 반복 안됨   | `{%tr %}` 와 변수 같은 줄 | 셀 안에서 Enter로 분리    |
| 빈 결과        | 변수 이름 불일치           | 데이터 키 확인           |

### Word가 태그 중간에 서식을 넣는 문제 (가장 흔함)

Word는 텍스트 입력 시 보이지 않는 서식 정보를 중간에 삽입합니다. 예를 들어 `{{ company_name }}` 이 내부적으로 `[서식A]{{ [서식B]company_name[서식A] }}` 로 쪼개질 수 있습니다.

**해결**:

1. 태그 부분을 전체 선택 후 삭제
2. 같은 위치에 **한 번에** 타이핑 (중간에 커서 이동 X)
3. 또는 메모장에서 먼저 입력 → 복사 → 붙여넣기

## 9. 완성 예시: 제안서 템플릿

```
{{h title }}

수신: {{ recipient_name }} 귀하
발신: {{ sender_name }} / {{ sender_department }}
일자: {{ date }}

## 1. 개요
{{ overview }}

## 2. 제안 항목
```

(표: 품목/설명/금액 — 첫 셀 `{%tr for item in items %}` + `{{ item.name }}`, 마지막 셀 `{{ item.amount }}` + `{%tr endfor %}`)

```
합계: {{ total_amount }} 원

## 3. 일정
{% for phase in schedule %}
- {{ phase.name }}: {{ phase.period }}
{% endfor %}

{% if show_disclaimer %}
본 제안서는 대외비이며, 제안 유효기간은 발행일로부터 30일입니다.
{% endif %}
```

<Tip>
  **도움이 필요하신가요?** 템플릿을 만든 후 AI에게 "이 템플릿을 분석해줘"라고 요청하면 필요한 변수를 자동으로 알려줍니다.
</Tip>