# Guide for Using Word Templates (.dotx)

## Overview

ClioDeck supports using custom Word templates (.dotx files) for document export. This feature allows you to apply your own formatting, styles, and structure to your Word exports.

**Which export path you actually get depends on your project.** Word export
in ClioDeck goes through one of two mechanisms:

1. **Pandoc + your template as a reference document** — used only when a
   bibliography is attached to your project, Pandoc is installed, **and**
   ClioDeck's own citation engine is not explicitly requested. Your `.dotx`
   supplies Word **style names** (`Heading 1`, `Title`, `Quote`, …) that
   Pandoc's output adopts — the `{placeholder}` syntax below does **not**
   apply here; there's nothing to fill in, Pandoc converts your Markdown
   directly using your template's styles.
2. **Native docx + `docxtemplater` placeholders** — used in every other
   case: no bibliography attached, **or** a bibliography with ClioDeck's own
   citation engine requested instead of Pandoc's (so Word-native footnotes
   can be produced), **or** a bibliography present but Pandoc not found.
   Whenever a `.dotx` template exists and you're on this path, the
   `{title}` / `{author}` / `{content}` / … placeholders documented below
   get filled in — the citation engine question only affects how footnotes
   are produced, not which template mechanism applies.

If your export doesn't seem to respect your placeholders, check whether a
bibliography is attached *and* Pandoc is found *and* the citation engine is
off — only that exact combination skips placeholders in favor of named Word
styles.

## Basic Usage

### 1. Automatic Detection

To use a Word template, simply place a `.dotx` file in your ClioDeck project folder:

```
my_project/
├── .cliodeck/
├── document.md
├── bibliography.bib
└── my_template.dotx  ← Your Word template
```

ClioDeck will automatically detect the template and inform you during export.

### 2. Export with Template

When exporting to Word:
1. Open the **Project** panel
2. Click **Export to Word**
3. If a template is detected, you'll see a message: **Word template detected: my_template.dotx**
4. Fill in the information (title, author)
5. Click **Export**

The generated document will use the styles and formatting from your template.

## Creating a Template with Placeholders

**This section applies whenever you land on mechanism 2 above** — no
bibliography, *or* a bibliography with ClioDeck's own citation engine
requested, *or* a bibliography present but Pandoc not found — that's when
ClioDeck uses `docxtemplater` to merge your content with the template via
placeholders. If you're on mechanism 1 (bibliography + Pandoc + no citation
engine requested), skip to [Styles and Formatting](#styles-and-formatting)
instead: your template supplies Word style names, not placeholders.

### Available Placeholders

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `{title}` | Document title | "My Scientific Article" |
| `{author}` | Document author | "John Smith" |
| `{date}` | Export date | "01/11/2026" |
| `{content}` | Converted Markdown content | For an article, your whole `document.md`. **For a book, this is broken beyond just the template case — see the warning below.** |

> **⚠️ Book export to Word is currently broken in the most common
> configuration.** If your book has a bibliography attached, Pandoc is
> installed, and you haven't requested the citation engine — the ordinary
> setup for a historian's book — Word export takes the Pandoc route
> (mechanism 1), and that route **never runs manuscript assembly at all**.
> The exported `.docx` is generated from an empty content string: it opens
> fine, has a title page, and has **no chapter text**. This isn't specific
> to templates or to `{content}` — it affected the plain "Export → Word"
> button with no template involved. Manuscript assembly happened only on the
> native-docx fallback path, and was unreachable from the Pandoc branch.
> **Fixed in RC4**: the manuscript is assembled before the export branches,
> so a cited book exports correctly on every route. RC4 also stopped the
> native path printing `\mainmatter` as a paragraph at the top of the
> document, and made the Word export honour chapter numbering and structure
> from the book settings.
>
> **Counter-intuitive detail, mechanism 2 (native docx) only**: on this
> route, the native document is always built from the correctly-assembled
> manuscript — the bug above is specific to `{content}` inside a
> `.dotx` placeholder template. So if you're on mechanism 2 with a
> template *and the template merge fails for any reason*, the fallback it
> produces is actually **more complete** than a successful merge would
> have been, since a successful merge would have filled `{content}` with
> the unassembled value. Not something to rely on, but worth knowing if a
> "failed" export looks better than expected.
| `{abstract}` | Abstract (if abstract.md file exists) | Your summary |

### Template Example

Create a Word document and insert these placeholders:

```
═══════════════════════════════════════════════════
                    {title}

                 By {author}
                    {date}
═══════════════════════════════════════════════════

ABSTRACT

{abstract}


CONTENT

{content}
```

Save this document as `.dotx` format (File → Save As → Word Template).

## Styles and Formatting

### Automatic Styles

If your template contains named styles, ClioDeck will automatically apply them:

- **Heading 1** → `Heading1` or `Titre 1`
- **Heading 2** → `Heading2` or `Titre 2`
- **Heading 3** → `Heading3` or `Titre 3`
- **Normal** → Default paragraph style
- **Quote** → Citations and blockquotes

### Headers and Footers

Your template can include:
- Custom headers
- Custom footers
- Page numbering
- Institutional logo or image

**Note**: If your template doesn't have headers/footers, ClioDeck will use defaults (title in header, page number in footer).

## Error Handling Behavior

**This safety net only covers mechanism 2** (native docx + `docxtemplater`
placeholders). If the template cannot be loaded there (corrupted file,
incorrect placeholders, etc.), ClioDeck will:
1. Display a warning in logs
2. Automatically fall back to standard generation
3. Still create your document (without applying the template)

**Mechanism 1** (Pandoc + reference-doc) has no such fallback: if Pandoc
fails for any reason on that path, the export fails outright — there's no
automatic retry through the native-docx route. Which mechanism you're on
depends on whether a bibliography is attached (see the Overview above).

## Use Cases

### University Theses and Dissertations

Create a template with:
- Institutional title page
- Declaration of honor
- Table of contents (generated by Word)
- Heading styles conforming to requirements

### Scientific Articles

Use a template respecting:
- Specific journal format (APA, Vancouver, etc.)
- Required margins and spacing
- Header with running title

### Professional Reports

Include in your template:
- Company logo
- Brand guidelines
- Footer with legal information

## Advanced Settings

### Multiple Templates

If you have multiple `.dotx` files in your project, ClioDeck will use whichever one the filesystem lists first — this is **not guaranteed to be alphabetical**, it depends on directory-entry order, which varies by OS and filesystem.

**Recommendation**: Use only one template per project.

### Templates by Project Type

ClioDeck's own project types are **article**, **book**, and **presentation**
(presentations export to RevealJS, not Word). Nothing in the code ties a
specific `.dotx` file to a project type automatically — this is purely a
convention you can adopt yourself:

```
templates/
├── article_template.dotx
└── book_template.dotx
```

Copy the appropriate template into your project folder before export.

## Troubleshooting

### Template Not Detected

- Verify the file has `.dotx` extension (not `.docx`)
- Make sure the file is in the project **root folder** (not in `.cliodeck/`)
- Restart ClioDeck if necessary

### Content Doesn't Appear

If using placeholders:
- Check spelling: `{content}` not `{contenu}`
- Use single braces, not double
- No spaces: `{title}` not `{ title }`

### Incorrect Formatting

- Verify your Word styles are properly named (Heading 1, Heading 2, etc.)
- Test the template by manually creating a Word document
- Make sure the template isn't corrupted

## Resources

- [docxtemplater Documentation](https://docxtemplater.com/)
- [Creating a Word Template - Microsoft](https://support.microsoft.com/en-us/office/create-a-template-86a1d089-5ae2-4d53-9042-1191bce57deb)

## Support

If you encounter issues:
1. Check the console — ClioDeck does not write logs to a file, and the
   "Journal Panel" is the AI usage/research journal, not an error log; it
   never shows export warnings. Word-export failures log via
   `console.warn`/`console.error` (`word-export.ts`), visible only if you
   launch the app from a terminal (or open DevTools, `Ctrl/Cmd+Shift+I` /
   `F12`)
2. Verify your template opens correctly in Word
3. Try exporting without a template to confirm the issue is with the template

---

**Version**: 1.0.0-rc.4