Interpolated Variables when Converting from Markdown to DOCX

[dstark]

From the manual, I see that it should be possible to specify custom variables that Pandoc will then interpolate at given locations in the text.

When I try to define one in a markdown document's YAML header like

variable: content

and then reference this variable in the text with, per the examples in the manual,

$variable$ or $ variable $ or ${variable} or ${ variable }

the first renders as math, and the last three render just as the text written in the markdown document. The information I'm passing to Pandoc to convert markdown to DOCX is below. Any suggestions for how I can set this working would be most welcome.

Thanks so much!

reader: markdown
writer: docx
self-contained: true
variables: {}
metadata-files: []
include-before-body: []
include-after-body: []
include-in-header: []
bibliography: []
filters:
- type: citeproc
top-level-division: chapter
dpi: 72
number-sections: false
number-offset:
- 0
- 0
- 0
- 0
- 0
- 0
shift-heading-level-by: 0
identifier-prefix: ''
title-prefix: ''
eol: lf
strip-comments: false
indented-code-classes: []
ascii: false
default-image-extension: .jpg
tab-stop: 4
preserve-tabs: false
fail-if-warnings: false
reference-doc: D:\GitHub\Resources\SBL Handbook of Style.docx

[fiapps]

The documentation on interpolated variables is in the Template Syntax section. Variable interpolation is done in templates, not in the text. If you want to do something like this in the text, you'll need to use a filter, like this example.

[bpj]

The filter as written takes variables from the table vars defined as empty on the first line. As I wrote getting variable values from metadata or a file is not covered by the code I posted.

Also the function as written assumes that variable values are plain strings. Just inserting metadata values into the document AST is also not robust since there is no guarantee other than the user’s diligence that they are in fact lists of Inlines.

You can of course add a check and error out if the value is unsuitable, but that may be confusing to the user since how Pandoc chooses to represent metadata values is frequently not intuitive.

Anyway here is a version which uses the value of the metadata field variables to look up variables in if it exists (in which case it must be a KEY: VALUE mapping) or the entire metadata tree if that field does not exist. It errors out if the looked up value is not a list of Inlines or a plain string.

local vars = { }

local bad_var = 'Variable `%s`{.v} is not Inlines or string'

local Meta = function(meta)
  local _vars = meta.variables
  if _vars then
    if 'table' == pandoc.utils.type(_vars) then
      vars = _vars
    else
      error('Value of metadata field "variables" is not a mapping')
    end
  else
    vars = meta
  end
  return nil
end

local Code = function(code)
  if code.classes:includes('v') then
    local var = vars[code.text]
    if var then
      local vtype = pandoc.utils.type(var)
      if 'Inlines' == vtype then
        return var
      elseif 'string' == vtype then
        return pandoc.Str(var)
      else
        error(bad_var:format(code.text))
      end
    end
  end
  return nil
end

return {
  { Meta = Meta },
  { Code = Code }
}

With this you can do either

---
variables:
  variable: value
---

`variable`{.v}

or

---
variable: value
---

`variable`{.v}

In the second case you can also use -V variable=value on the commandline.

[dstark]

That's fabulous, @bpj. Thanks so much!

[bpj]

@dstark My pleasure. BTW you might want to put your variables in a metadata file so that you can share it between multiple documents.

[dstark]

Thanks, @bpj. That's a great idea too. I have a metadata file that's working and rendering the document's styles properly. But when I try to define variables there like

variables:
  test1: "result1" [Or without the quotation marks.]
  test2: "result2"

The output renders as just "test1" and "test2". I suspect that this is the LUA filter that needs adjusting to fall back to variables in the defaults file if something isn't defined in the document header. Does that sound right?

[bpj]

Probably the problem is that like-named metadata fields in the document file override fields defined in metadata files and defaults files, and those defined in metadata files override those defined in defaults files. The order in which metadata files are given also matters. First found wins. The filter sees only a single metadata table. Which values end up there depends on the precedence rules. No smart merging or anything like that!

[dstark]

@fiapps, thank you so much. I now have a custom export in Zettlr that's doing the interpolation properly:

pandoc --lua-filter="%userprofile%\Dropbox\Apps\DesktopApps\PandocInterpolateVariables.lua" -o "$(basename -s .md).docx"

But

1. The paragraph styles in the output document for the interpolated variables are just what they would be if the text had been typed directly---not, for instance, like author variable that's automatically gotten styled with the Author style. Is there a way to tell Pandoc "whenever you interpolate a variable, style that paragraph according to the variable name" (so, e.g., text interpolated for %variable% would get the style Variable)? Or does a fence like :::{custom-style="Variable"} or <span custom-style="Variable"> need to be used also?
2. I've been trying to set the output file name to be the same as the input file name, just with the DOCX instead of the MD extension. But the file I'm getting with this command is named $(basename -s .md).docx. This may be a separate issue for a separate question, but any insight on this issue would be most helpful too.

Thanks so much!

[iandol]

1. I think you do need to add the custom-style property to the content or else the DOCX writer will not add the Style. A filter should be able to add that property, or use the correct markdown syntax...

2. you are not passing the input name so how can basename work? Doesn't it need something like:

▶︎ echo $(basename -s .md in.md).docx
in.docx

[dstark]

@iandol,

1. I think you do need to add the custom-style property

Thanks so much. I'll bear this in mind.

echo $(basename -s .md in.md).docx
in.docx

It's quite possible I was doing something amiss here, but I wasn't able to get this to work. Instead, what I was able to get working was the following:

@echo off
setlocal enabledelayedexpansion

:: Extract directory path and filename of the input Markdown file
set "input_file=%~1"
for %%A in ("%input_file%") do (
    set "directory=%%~dpA"
    set "filename=%%~nxA"
)

:: Construct the output file path with the same directory and filename but with a .docx extension
set "output_file=!directory!!filename:.md=.docx!"

:: Export the Markdown file to DOCX using Pandoc
pandoc --output="%output_file%" --from=markdown --to=docx --lua-filter="%userprofile%\Dropbox\Apps\DesktopApps\PandocInterpolateVariables.lua" "%input_file%"

:: Open the output file
start "" "%output_file%"

Thanks so much for the help!