Support yaml_metadata_block extension in more formats
#3084
Conversation
Make it possible for other readers to use the YAML block parser.
The YAML metadata parser is useful for many formats and is specific enough to warrant a separate module.
Enabling the yaml_metadata_block allows authors to include an optional YAML metadata blocks at the top of an org file.
Enabling the yaml_metadata_block allows authors to include an optional YAML metadata blocks at the top of an RST file.
Enabling the yaml_metadata_block allows authors to include an optional YAML metadata blocks at the top of an LaTeX file.
|
@jgm What do you think about the idea in general? Quite a few people asked about getting YAML blocks for org files in the past. Do you see a better way to handle this? |
|
I'm conflicted about the idea. Conceptually, there are two ways to think about YAML metadata. Either (a) it's an integral part of the format or (b) it's separate from the format. With option (b) you think of documents that start with YAML metadata as really two documents glued together, one a metadata bit and the other the document proper. With pandoc's Markdown we took option (a), so it feels somewhat inconsistent to me to take option (b) with the other formats. But of course, with them, option (b) is the only option we could take. There's also a question what to do about formats that have their own ways to specify metadata (as RST does) -- how does this interact with YAML metadata? |
|
Indeed, that conceptual view makes it look like like a bad idea. I was coming at this from the user perspective, aiming for somewhat uniform behavior, but I know see that it's less consistent than I hoped it would be. How do you feel about the alternative solutions proposed in #1960, e.g. a command-line option There are two main use-cases for this feature: One are markup-formats that allow no or only limited inclusion of metadata (basically all of them). The other are programs like hakyll which use pandoc but use YAML instead of pandoc's metadata.
I'd prefer if YAML metadata were treated as default values which can be overwritten. |
|
@jgm, do you think there is a chance to somehow use YAML blocks with arbitrary formats in pandoc 2? Otherwise I'll just close this. |
|
I'm still not decided about this; let's leave it open for now.
|
|
To contribute to this issue with another opinion I would like to say that I agree with tarlebs view. I would like to underline the user perspecitve on pandoc as a flexible and multi propose document converter. Not all languages support their own metadata blocks and somehow YAML is intended to be a universal metadata language. So there is a reason to follow both concepts: a) and b). Or let's put it in the view of usability: a user might easily expect YAML to be independent from the native file format, and it is difficult to explain why certain pandoc input formats should not support yaml... |
|
While I can see the appeal of simply prepending some yaml metadata to existing rst/org-mode/latex files to quickly get some metadata fields set, doing so would make those files unparsable for the native rst program, Not sure how often-requested this feature is, but would it be too much to ask users to save the metadata in a separate yaml file which can be supplied as an argument as proposed in #1960? |
|
The main benefit of being able to put the YAML block into the file is that both pandoc and tools like hakyll can read it. Here's one such example file: https://raw.githubusercontent.com/turboMaCk/turboMaCk.github.io/develop/posts/2016-12-21-org-mode-in-hakyll.org (rendered version). (I'm not arguing your general point, which I'm agree with, I just want to provide some context.) |
|
I wrote a pandoc-notetaking tool for organizing notes in files. It uses the YAML header to synchronize the document title and subtitle with the filenames of notes. It relies on |
|
Did this get merged? Can I use YAML metadata blocks in RST? (I tried, but it doesn't seem to be working - I'm not sure if I'm doing something wrong). The docs don't explicitly state that YAML metadata blocks work only with Markdown files (one can make an implicit assumption because all the examples are related to markdown). |
|
Not merged. You'd have to write a small wrapper around pandoc which splits the input into two temporary files, the YAML header and the content. The YAML would then be passed via |
This allows to specify metadata using yaml blocks with input formats RST, Org-mode, and LaTeX when the
yaml_metadata_blockextension is specified. Other than with Markdown, YAML blocks are not fully integrated into the language parser and may only appear at the top of a document. This should add enough flexibility to pass metadata in the form of a YAML block, yet limits the extend this feature has on language parsing.This closes #1960.