Place TOC on a different page

[zero0n3]

Hello
when i convert from markdown to docx, is it possible, using the --toc option, to make pandoc insert the index in a page other than the first? For example in the third.

thanks

[TomBener]

Yes, you can make it by moving the location of $toc$ in default.openxml, as well as inserting a page break tag, and then using the updated template for the conversion.

[Smeedy]

Hi,

So I was a bit unhappy how you can structure the TOC using https://github.com/jgm/pandoc/blob/main/data/templates/default.openxml#L50 and I decided to take a bit of a different approach.

In our workflow we use Documentation as Code as the primary source which is a Markdown file and we can use pipelines to export it to a static site (MkDocs Material) which is accessible online, or we export the markdown file of files to a PDF or Word document for distribution. For review people want to use the MS Word features and we cannot force them doing GitOps, so we generate and distribute a version when we tag the project in Git.

We need to shape the generate Word file so it more or less resembles the original online version - pictures, graphs, admonition markup, etc. We use the custom-reference.docx to style elements, and do some work to make it look nice. But with the TOC I cannot just have it prepended or placed somewhere in the openxml tree at random because it looks like an eyesore; it needs to fall into that same location in the structure of the document, which is the already present [TOC] placeholder we defined in the Markdown file to begin with and how the online version looks more or less.

I have been struggling to have that TOC generated in the correct place, and I did not want manipulate the default.openxml because that was way too limited. I also didn't want to have the Table of Contents duplicated in the beginning of the document and in the designated [TOC] placeholder. I also wanted to have a dynamic TOC defined with the openxml specification and be able to generate or regenerate when people see fit.

SoI have created a Gist with a piece of LUA code which I call toc-inject.lua which will trigger whenever it finds the Para with the content [TOC]. In your Markdown file you can just drop your table of contents anywhere you'd like:

## Executive Summary blah

Just some random text. Whatever, and going into the next section - which happens to be the TOC.

## My Table of Contents

[TOC]

## Introduction

And just truck along..

Generating the docx would be something like pandoc input.md -f markdown-smart -o output.docx --lua-filter=toc-inject.lua --reference-doc=my-custom-style-reference.docx. Mind that I do not use the --toc flag as I think it is not using intermediate AST, but is something which is triggering the writer is that default.openxml file as a template. Otherwise I would have suppressed it in the Meta when it was being used on the CLI.

The toc-inject will render in more or less the same xml code the Pandoc --toc flag would normally push into that openxml $toc$ location in the template. It will also mark it dirty so whenever you open the Word document, it will ask you to update fields and the table of content will be generated for you.

I also added two meta flags which enables you to set the header start and stop depth. See the comment in the Gist for some additional information. This is a v0.1 and I decided to create it after a day or so browsing the internet and finding nothing I was happy about. I just put together some pieces of the puzzle and put a bit of pressure on ChatGPT - Lua is not my thing and I am new to Pandoc. This is the cleanest approach I could come up with.

Cheers,
Martijn

The Lua toc-inject filter is published here:
👉 https://gist.github.com/Smeedy/f079ddc93d8f1171a27f9a15772220b4

[zero0n3]

What a wonderful and elegant solution! Thanks!

[zero0n3]

@Smeedy with your lua file, do you think it is possible to insert the title in addition to the index, retrieving the value indicated, for example, in the yaml file where I define the default values ​​for that specific conversion? thanks

[Smeedy]

Hi,

If you are referring to the meta properties of the OpenXML document, I think you can inject them using Pandoc directly. Either through the document front-matter YAML like

---
title: "My Document Title"
author:
  - "Alice Example"
  - "Bob Sample"
date: 2025-06-30
keywords: ["world domination","rodents","Pinky & the Brain"]
---

Or using the meta flags on the CLI. I think you can do something like

pandoc input.md \
  -o output.docx \
  -M title="My Document Title" \
  -M author="Alice Example" \
  --reference-doc=custom-reference.docx

but you need to double check it.

If you want to inject the Title on say the first page on the output document you might want to consider injecting it when generating your output and using a lua filter. Did not test this script, but this would be the gist of it

--[[
  inject-title.lua
  Version: v0.1
  Author: ChatGPT (OpenAI)
  Description:
    Pandoc Lua filter that takes your YAML/CLI “title” metadata and
    injects it as the first paragraph of the document body, using
    a custom Word style called “TitleStyle”.

  Usage:
    pandoc input.md \
      --lua-filter=inject-title.lua \
      --reference-doc=reference.docx \
      -o output.docx
]]

function Pandoc(doc)
  -- 1) extract the title metadata
  local t = doc.meta.title and pandoc.utils.stringify(doc.meta.title)
  if t then
    -- 2) build a Para containing the title text
    local title_para = pandoc.Para{ pandoc.Str(t) }
    -- 3) assign it the Word style "TitleStyle"
    title_para.attr = pandoc.Attr("", {}, { {"custom-style", "TitleStyle"} })

    -- 4) insert it at the very beginning of the document body
    table.insert(doc.blocks, 1, title_para)
  end

  return doc
end

The TitleStyle of the reference.docx is where you can put some fluff in. Let me know if this works for you.