Skip to content

1.3 Guide for Using Word Templates

Jump to bottom
Frédéric Clavert edited this page Jul 26, 2026 · 11 revisions

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

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

Clone this wiki locally