Pandoc template support

[OliverBalfour]

Requested by @eleanorkonik on the Discord's #creative channel

Basically, you can write template files for most output formats which use a templating language to include bits of the input document. Using the Pandoc CLI the command will have a --template=file.tex if you've got a template called file.tex in the working directory or ~/.pandoc/templates.

My idea for the UX is to have a setting where you list files anywhere in your vault that you'd like to be templates (or specify a template directory?). Then, when you export, if there are any custom templates for that export type you should be prompted for the template you want, including the default one.

Related links:

• Official docs
• Default LaTeX template
• Simpler example

[eleanorkonik]

For what it's worth, I'm pretty sure that the templates I personally need are here:

https://github.com/prosegrinder/pandoc-templates

Of course I have no idea how to get them to work because the windows directions are under revision :P but I thought maybe his might help?

[OliverBalfour]

Thanks, I'll use that to test the feature when I'm done. Hopefully you'll be able to just copy the files from that repo into your vault to use them as templates when I'm done

[OliverBalfour]

This is now possible, using the Extra Pandoc arguments setting. Here's a quick tutorial: https://github.com/OliverBalfour/obsidian-pandoc/wiki/Pandoc-Templates
It's not very detailed at this stage, so apologies if it's confusing.

As for the writing templates you've posted @eleanorkonik, it looks like they're scripts that wrap around Pandoc so you can't use them directly as Pandoc templates. I think they need to be invoked in the terminal directly.

---

Any issues/confusions about templates in this plugin should be appended to this issue for now

[gpl34]

What about having a template: in the YAML front matter. For example, saying:

---
template: local.latex
---

would be the same as --template=local.latex. That would allow to choose a different template per note. No need therefore to change the settings or to ask the user to choose a template each time one exports a note.

[JCalinawan]

Hello,
I'm not a programmer so I apologize for this very basic question. I have a docx template file, but where do I place it? How do I create or navigate to the template path ~/.pandoc/templates? Thanks so much for your work and help.

Regards,
Jonah

PS. For now, I entered extra pandoc commands to output citations using the mla format and to specifically use a template. I'm sharing it here to help others who might be in the same boat.

--metadata bibliography=/Users/username/Dropbox/library.json
--citeproc
--csl=/Users/username/Dropbox/mla.csl
--reference-doc=/Users/username/Dropbox/template.docx

[kelleyskovron]

I can't seem to get a custom template to work. If I run pandoc vanilla, it's just fine, but as soon as I enter "--template ms-template" into the settings, I get an encoding error (attached screen).

It looks like there is something wrong in the document (also attached)

ms-template.docx

But it was generated by Obsidian pandoc. All I did was tweak a few paragraph styles (font color, size, alignment, spacing, and page breaks) in Libreoffice, created the directory in my home folder ~/.pandoc/templates, and put the file there. So I'm not sure how I can be messing this up. And the template works in Typora--which is a work around for now of course, but why leave Obsidian if I don't have to?

[bl4ckr00t]

Hey Guys,
i am working on Windows for Work and Mac for privat.
I sync all my notes etc. via Obsidian.
On Mac, its all fine with the --reference-doc but on Windows, i have no chance...
Via Commandline there is no problem to convert the md in docx.
pandoc -o test.docx test.md --reference-doc C:\Users......\MyWordVorlage.docx
Mac Settings:
--reference-doc Users/lars/Documents/myref.docx
WinSettings (tryed more):
--reference-doc C:\Users......\MyWordVorlage.docx
--reference-doc C:\Users\...\...\MyWordVorlage.docx
--reference-doc C:/Users/.../.../MyWordVorlage.docx

any Ideas?

[Karmanoid]

Hey Guys, i am working on Windows for Work and Mac for privat. I sync all my notes etc. via Obsidian. On Mac, its all fine with the --reference-doc but on Windows, i have no chance... Via Commandline there is no problem to convert the md in docx. pandoc -o test.docx test.md --reference-doc C:\Users......\MyWordVorlage.docx Mac Settings: --reference-doc Users/lars/Documents/myref.docx WinSettings (tryed more): --reference-doc C:\Users......\MyWordVorlage.docx --reference-doc C:\Users......\MyWordVorlage.docx --reference-doc C:/Users/.../.../MyWordVorlage.docx

any Ideas?

the same problem, in extra Pandoc arguments added something like: --reference-doc Users/lars/Documents/myref.docx
but export on start failed because of error: file doesn't exist

[adamP-B]

I can define a new template for latex documents, but if I create a PDF using Latex this template is not used. It seems to find some default template which is different to that in ~/.pandoc/templates/

I am very confused. Any ideas

[turnwrite]

I can't seem to get a custom template to work. If I run pandoc vanilla, it's just fine, but as soon as I enter "--template ms-template" into the settings, I get an encoding error (attached screen).

It looks like there is something wrong in the document (also attached)

ms-template.docx

But it was generated by Obsidian pandoc. All I did was tweak a few paragraph styles (font color, size, alignment, spacing, and page breaks) in Libreoffice, created the directory in my home folder ~/.pandoc/templates, and put the file there. So I'm not sure how I can be messing this up. And the template works in Typora--which is a work around for now of course, but why leave Obsidian if I don't have to?

@OliverBalfour @kelleyskovron Did you ever resolve this issue? I'm having the same error.

I'm using the prosegrinder .docx template that @eleanorkonik linked above

[Karmanoid]

I can't seem to get a custom template to work. If I run pandoc vanilla, it's just fine, but as soon as I enter "--template ms-template" into the settings, I get an encoding error (attached screen).

It looks like there is something wrong in the document (also attached)
ms-template.docx
But it was generated by Obsidian pandoc. All I did was tweak a few paragraph styles (font color, size, alignment, spacing, and page breaks) in Libreoffice, created the directory in my home folder ~/.pandoc/templates, and put the file there. So I'm not sure how I can be messing this up. And the template works in Typora--which is a work around for now of course, but why leave Obsidian if I don't have to?

@OliverBalfour @kelleyskovron Did you ever resolve this issue? I'm having the same error.

I'm using the prosegrinder .docx template that @eleanorkonik linked above

the same problem, discussed here https://forum.obsidian.md/t/custom-word-template-with-pandoc-pluugin/41685/11

still looking for solution

[Ellpeck]

What about having a template: in the YAML front matter. For example, saying:

---
template: local.latex
---

would be the same as --template=local.latex. That would allow to choose a different template per note. No need therefore to change the settings or to ask the user to choose a template each time one exports a note.

This would be a very simple solution that I agree would be incredibly useful.

[OliverBalfour]

@Ellpeck what happens if you do this? IIRC this should work, although you might need to do something like template: /full/absolute/path/to/template.tex.

If it doesn't work using an absolute path that's a bug, if it does then I need to add better documentation because this is pretty non-obvious.

[Ellpeck]

@Ellpeck what happens if you do this? IIRC this should work, although you might need to do something like template: /full/absolute/path/to/template.tex.

If it doesn't work using an absolute path that's a bug, if it does then I need to add better documentation because this is pretty non-obvious.

I've only tried with a URL (which works with the --template pandoc argument and, imo, should work with this plugin too), and that doesn't make a difference at all. It doesn't seem to be picked up by the plugin or by pandoc, and so the template isn't applied.

Unless you mean with an updated dev version? I've only tried with 0.4.1, which is the most recent public version.

[OliverBalfour]

@Ellpeck yeah that's very strange. The plugin doesn't treat the template: different to any other metadata CLI options like author:, so I'll look into that

[Limezy]

@Ellpeck Do you have spaces in your absolute path to the template, that you wouldn't have in your path to other metadata CLI options ?

[Ellpeck]

@Ellpeck Do you have spaces in your absolute path to the template, that you wouldn't have in your path to other metadata CLI options ?

As I said, the only time I tested this, I used a web URL (which is supported by the --template pandoc option, and also worked when i added it to the "additional arguments" section of the plugin settings), so no, no spaces!

[flengyel]

Hi. I am configuring Obsidian to reproduce some features of Zettlr that I like, including Zettlr's pandoc handling.
Zettlr has different export..yaml files for different output formats. For example, to export Markdown to LaTeX in Obsidian with your plugin exactly as I would do this in Zettlr, I have to set

--defaults=C:\Users\fleng\AppData\Roaming\Zettlr\defaults\export.latex.yaml --bibliography C:\Users\fleng\Dropbox\Zettelkasten\media\MyLibrary.json

in the Extra Pandoc arguments option, whereas to export to pdf with pdflatex, I need to change the Extra Pandoc arguments to

--defaults=C:\Users\fleng\AppData\Roaming\Zettlr\defaults\export.pdf.yaml --bibliography C:\Users\fleng\Dropbox\Zettelkasten\media\MyLibrary.json

The export files I use are in my github under flengyel/Zettel, as is the latex template, which is invoked by the export files. The point is that the plugin might include separate command line argument for each of the output formats, since the defaults may change. Maybe I will modify the plugin for these cases myself.

Many thanks for your work.

[kelleyskovron]

I can't seem to get a custom template to work. If I run pandoc vanilla, it's just fine, but as soon as I enter "--template ms-template" into the settings, I get an encoding error (attached screen).

It looks like there is something wrong in the document (also attached)
ms-template.docx
But it was generated by Obsidian pandoc. All I did was tweak a few paragraph styles (font color, size, alignment, spacing, and page breaks) in Libreoffice, created the directory in my home folder ~/.pandoc/templates, and put the file there. So I'm not sure how I can be messing this up. And the template works in Typora--which is a work around for now of course, but why leave Obsidian if I don't have to?

@OliverBalfour @kelleyskovron Did you ever resolve this issue? I'm having the same error.

I'm using the prosegrinder .docx template that @eleanorkonik linked above

Finally figured out what it was, and as I feared, it was just me missing something that was obvious once I took the time to drill far enough into the Pandoc user guide. Basically, you don't use the 'template' command for docx, but instead 'reference-doc'. As such, it's not looking for a file in the templates folder. If you drop the file directly in /home/.pandoc (assuming that's where your user data directory is located) and name it 'reference.docx', then it works right out of the box, no extra arguments needed in Obsidian. I generated a reference file directly from pandoc per these instructions and customized it myself based on my editor's preferences.

[acdesigns]

Finally figured out what it was, and as I feared, it was just me missing something that was obvious once I took the time to drill far enough into the Pandoc user guide. Basically, you don't use the 'template' command for docx, but instead 'reference-doc'. As such, it's not looking for a file in the templates folder. If you drop the file directly in /home/.pandoc (assuming that's where your user data directory is located) and name it 'reference.docx', then it works right out of the box, no extra arguments needed in Obsidian. I generated a reference file directly from pandoc per these instructions and customized it myself based on my editor's preferences.

I'm JUST starting to explore the use of this plugin, but am completely intimidated by all of it.
I have my memoir template in docx given by my university.

1. WHERE on Windows should I place my template file. STILL haven't figured this one out. There is no "/home/.pandoc" in windows.
2. Should it be saved as a template doc file or leave it as a docx file. (found on discord to leave as docx)
3. How do I tell the Pandoc Plugin to use the template. & 4. I do not understand where the "Extra Pandoc arguments option" or any of the other commands are written or given. This is not very clear to this very non-programmer. (per above, I don't need these, but DO need to open the command line and use template-doc instead of the Obsidian Command to export to Pandoc-docx, Is that right?)

Thanks for any help!

[kelleyskovron]

Finally figured out what it was, and as I feared, it was just me missing something that was obvious once I took the time to drill far enough into the Pandoc user guide. Basically, you don't use the 'template' command for docx, but instead 'reference-doc'. As such, it's not looking for a file in the templates folder. If you drop the file directly in /home/.pandoc (assuming that's where your user data directory is located) and name it 'reference.docx', then it works right out of the box, no extra arguments needed in Obsidian. I generated a reference file directly from pandoc per these instructions and customized it myself based on my editor's preferences.

I'm JUST starting to explore the use of this plugin, but am completely intimidated by all of it. I have my memoir template in docx given by my university.

1. WHERE on Windows should I place my template file. _STILL haven't figured this one out. There is no "/home/.pandoc" in windows._

2. Should it be saved as a template doc file or leave it as a docx file. _(found on discord to leave as docx)_

3. How do I tell the Pandoc Plugin to use the template. & 4. I do not understand where the "Extra Pandoc arguments option" or any of the other commands are written or given. This is not very clear to this very non-programmer.  _(per above, I don't need these, but DO need to open the command line and use template-doc instead of the Obsidian Command to export to Pandoc-docx, **Is that right?**)_

Thanks for any help!

I'm not a programmer, but I did spend some time as a technical writer, so I have some familiarity with it all. I will endeavor to help as best I can. The following assumes you are only looking to export a markdown file to docx. Other export formats require a different setup. This also assumes that you have already installed both Pandoc and the Pandoc plugin for Obsidian on your computer.

1. For the location, I'm not entirely certain where precisely you'll want to place the file in your directory, since I haven't used Windows in a very long time. However, my assumption is that it would not be completely different from Linux? If that is so, the folder we are looking for should be in your home directory (i.e. the one bearing the name you login with). From there, again assuming it follows the same general structure as Linux, you would look for the ".pandoc" subdirectory. Now, since the subdirectory begins with a period, it is likely hidden by default in the Windows file navigator. If you'd rather avoid dealing with terminal hijinks (which I completely understand), you will need to change the setting for Windows to show hidden files and folders (sorry, no idea where that setting is on Windows, but presumably it's an easy thing to look up).
2. As for the file itself, my earlier post talked about some light terminal usage as recommended on the official pandoc site, but I suspect that if you want to avoid terminal usage entirely (again, I get it), you could just use the default vanilla docx output of the pandoc plugin for Obsidian. Start with a text file in Obsidian. It can be an existing document you want to have outputted, or you can make a "dummy" file with text place holders like Title, Author, Header 1, Header 2, body, etc. Within Obsidian, launch the command pallet (there's a button, or you can use CTRL+P), search for "Pandoc Plugin: Export to Word document" and execute it. This puts the exported file wherever you have indicated in the plugin settings (I believe the default is the same folder as the text file, but you can alter that). Once you'd exported it, open the new file in Word, Libreoffice, or Open Office (the latter two are free), and use the style menu to customize the format for each paragraph style you intend to use. You don't need to bother with every single paragraph style listed in the panel, just the ones you think you'll actually use (Title, Author, Heading 1, Heading 2, blockquote, etc). And take care not to simply change the formatting of the text on the page. The important thing is to update the entire style in the panel for each paragraph. Once you've formatted the document to your liking (or in my case, to my editor's specifications), save it with the filename "reference.docx". Not as some weird MS Word template file format, just a normal commonplace docx file.
3. Here's where the magic comes in: You don't need to bother fiddling with anything in the Obsidian pandoc plugin settings! The Extra pandoc arguments and so forth are only relevant to people exporting to LaTex and other fancy things. The humble docx requires none of that finesse. Simply take your formatted file with the name "reference.docx" and drop it into the ".pandoc" folder. The reason no additional configuration is necessary for docx is that Pandoc, by default, looks for a reference.docx file every time it exports to docx. If it sees one, it uses it. If it doesn't see one, it uses its own.

And that's all there is to it. There are some additional things I recommend, such as create a custom hotkey for the plugin export to docx command in Obsidian, and creating a symlink/alias to your reference.docx file in your Obsidian template folder so you don't have to show hidden files every time you want to open the .pandoc folder to alter your template. But these are nonessentials that I have merely found make the workflow a little more smooth.

Good luck!

[acdesigns]

Wow! Thanks! I'm quite familiar with Windows and such, but Pandoc and LaTex is just too much programming for me.

Turns out the reason I couldn't find the Pandoc folder under AppData is because I forgot to install it. Since I was using the HTML output in Obsidian, I never went through with the actual install. Woops.

Now it's installed, I put the file my university sent me as a template (it's a docx) file and renamed it reference.docx
Wanted to see if it would work directly, but it seems not. Looks like I'll have to update everything by hand, which kind of defeats having the template already done. I'll try updating what the pandoc plugin outputs to match the university's output, but I'm skeptical it'll work.

I wish the math department would hurry up and update the LaTex template as I could possibly just use that, but that might be asking for a too big learning curve considering the time I have left...

Thank you so VERY MUCH for your very detailed input!

[acdesigns]

Ok, did all of the above, but sadly, whenever I output to docx, it uses Word's normal style template. I'm at a loss as to what else to do.

I CREATED a new folder in ROAMING (the default install is in Local) and THAT worked. It's not perfect (still have to check other styles (tables, figures, etc) but I'm on the right track.

Thank you!!

[Al-Saqib]

I can define a new template for latex documents, but if I create a PDF using Latex this template is not used. It seems to find some default template which is different to that in ~/.pandoc/templates/

I am very confused. Any ideas

Were you able to solve this issue? I am facing the same problem.

[WannabeTechWarrior]

On my windows computer, the Installation Wizard always installed the pandoc program into my User\AppData\Local\Pandoc directory and not in the said .pandoc folder.
Also I could not find the default template obsidian-pandoc is always using.
Inside of ........\Local\Pandoc\ there is no folder called template.
I searched for it a long time but I didn't find it.

What worked for me was to just copy and paste the whole path of the template, inside the settings in Obsidian:
"Extra Pandoc arguments".

--template C:\your whole path to the template you want to use\template.tex

after that it uset my wished template

Now I have to generate my wished template.
Aight I'm outta here and solving my next issue.

[xeroc]

What about having a template: in the YAML front matter. For example, saying:

---
template: local.latex
---

would be the same as --template=local.latex. That would allow to choose a different template per note. No need therefore to change the settings or to ask the user to choose a template each time one exports a note.

This would be a very simple solution that I agree would be incredibly useful.

Can we have this please?

[krzysztofwysocki]

What about having a template: in the YAML front matter. For example, saying:

---
template: local.latex
---

would be the same as --template=local.latex. That would allow to choose a different template per note. No need therefore to change the settings or to ask the user to choose a template each time one exports a note.

This would be a very simple solution that I agree would be incredibly useful.

I think this could be combined with new "autocomplete" feature of obsidian properties.
If you reuse some templates, you could select it from dropdown for property template (or better pandoc_template)