What can I control with YAML header options in pandoc?

Only by chance did I see an example document using the toc: true line in their YAML header options in a Markdown file to be processed by Pandoc. And the Pandoc docs didn't mention this option to control table of contents using the YAML header. Furthermore, I see somewhat arbitrary lines in example documents on the same Pandoc readme site.

toc: true

Main question:

Meta-question:

Note: my workflow is to use Markdown files (.md) and process them through Pandoc to get PDF files. It has hierarchically organized manuscript writing with math. Such as:

.md

pandoc --standalone --smart --from=markdown+yaml_metadata_block --filter pandoc-citeproc my_markdown_file.md -o my_pdf_file.pdf

If you can read Haskell then the answer is available at github.com/jgm/pandoc/search?utf8=%E2%9C%93&q=yaml

– xmojmr
Oct 16 '14 at 8:03

Haskell

@xmojmr I might be able to learn it. But I was hoping for a natural language explanation or overview. E.g. a description of the architecture or something. Thanks, though, I'll look at it!

– Kalin
Oct 16 '14 at 22:46

I cannot read Haskell myself (and don't want to learn it) and I don't know about credible description of internal pandoc's behavior other then its source code, so I don't know what is the answer, just tried to be helpful until pandoc's author (stackoverflow.com/users/1261777/john-macfarlane) shows up

– xmojmr
Oct 17 '14 at 6:30

3 Answers
3

Actually, it is all contained in Pandoc's MANUAL. Specifically:

Templates may contain variables.

For example in your HTML template, you could write:

<title>$title$</title>

These template variables can be set with the --variable KEY[=VAL] option.

--variable KEY[=VAL]

However, they are also set from the document metadata, which in turn can be set either by using:

--metadata KEY[=VAL]

--metadata-file

The --variable options inserts strings verbatim into the template, while --metadata escapes strings. Strings in YAML metadata (also when using --metadata-file) are interpreted as markdown, which you can circumvent by using pandoc markdown's generic raw attributes. For example for HTML output:

--variable

--metadata

--metadata-file

`<script>alert()</script>`=html

See this table for a schematic of --variable vs --metadata vs YAML metadata.

--variable

--metadata

To answer your question: the template determines what fields in the YAML metadata block have an effect. To view, for example, the latex template, use:

$ pandoc -D latex

To see some variables that are set automatically by pandoc, see the Manual. Finally, other behaviours of pandoc (such as markdown extensions, etc) can only be set as command-line options (except when using a wrapper script).

Does it say explicitly clearly anywhere, that all variables have support to have their values from a YAML metadata block? Additionally I'd like to mention, that putting the metadata block into the template is only in some cases and for some variables a good idea. Document specific variables like a title should always be defined in the respective document, so that the template may be used for other documents unchanged (since it's a template and that's what templates are for).

– Zelphir
Nov 19 '16 at 16:58

I don't understand how this answer to question. The information that seems to me to be missing is this: Which options to Pandoc can be set as "variables"? All of them? (You say that variables can be set in Yaml headers.) Can Yaml headers set only variables? Or is there options that are not variables? Can Yaml headers set those? (Can, for example, an extension be enabled in a Yaml header?)

– Lii
Aug 18 '17 at 14:15

@Lii The answer explains that variables can be assigned values with the help of YAML blocks. Whether these variables are used in the generated output depends on the template being used (by specifying the output format). The built-in default templates for HTML and latex both use the toc variable to control showing the table of contents. You may invent your own variables and extend templates accordingly.

– Wolf
Feb 13 '18 at 14:51

toc

It is a rather long list that you can browse by running man pandoc in the command line and navigating to "Variables set by pandoc" section under "TEMPLATES."

man pandoc

The top of the list includes the following among many other options:

Variables set by pandoc Some variables are set automatically by pandoc. These vary somewhat depending on the output format, but include metadata fields as well as the following: title, author, date allow identification of basic aspects of the document. Included in PDF metadata through LaTeX and ConTeXt. These can be set through a pandoc title block, which allows for multiple authors, or through a YAML metadata block: --- author: - Aristotle - Peter Abelard ... subtitle document subtitle; also used as subject in PDF metadata abstract document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx keywords list of keywords to be included in HTML, PDF, and AsciiDoc metadata; may be repeated as for author, above header-includes contents specified by -H/--include-in-header (may have multiple values) toc non-null value if --toc/--table-of-contents was specified toc-title title of table of contents (works only with EPUB and docx) include-before contents specified by -B/--include-before-body (may have multiple values) include-after contents specified by -A/--include-after-body (may have multiple values) body body of document

```

This focuses on the fact that some variables can also be set via command line switch. This indirectly makes clear that YAML blocks are just an option.

– Wolf
Feb 13 '18 at 14:55

You can see the documentation of pandoc for a clue: http://pandoc.org/getting-started.html

But to know exactly where it will be used you can look for templates sources of pandoc: https://github.com/jgm/pandoc-templates

For example, for the html5 output the file is: https://github.com/jgm/pandoc-templates/blob/master/default.html5

Here's an section of the code:

<title>$if(title-prefix)$$title-prefix$ - $endif$$pagetitle$</title>

As you can see it has title-prefix and pagetitle.

title-prefix

pagetitle

You can look the documentation, but the best solution is to look for the source code of the version you are using.

Thanks for contributing an answer to Stack Overflow!

But avoid …

To learn more, see our tips on writing great answers.

Required, but never shown

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

搜尋此網誌

Dfyjkt