Using yaml inside a Div for custom HTML printing

[TheoWinterhalter]

Hello,

I'm pretty new to pandoc and I would like to know the best way to write say

::: paper
title: The title
authors: Authors
url: https://some.url
venue: Some place
year: 2024
:::

and then be able to print it nicely in HTML.
A bit like I can do with an HTML template for the header.

It seems the proper solution would be to go, e.g, for a lua filter like so

function Div(el)

  if el.classes[1] == "paper" then

     -- Somehow extract the data from el.content 

      local html_output = string.format(
        '<div class="paper">\n' ..
        '  <h3><a href="%s">%s</a></h3>\n' ..
        '  <p class="authors">%s</p>\n' ..
        '  <p class="venue">%s (%s)</p>\n' ..
        '</div>\n',
        url, title, authors, venue, year
      )

      return pandoc.RawBlock("html", html_output)
  end

  return el
end

But in the documentation I couldn't find anything about using yaml in there. And maybe yaml isn't the way to go, maybe I should encode the data as a table?

Any pointers about the idiomatic pandoc solution would be greatly appreciated.

Thanks!

[fiapps]

If you want to have something in a Markdown document that should be parsed as something other than Markdown, the best strategy to put it in a code block. Code blocks can have classes, so you can give the code block a paper class and look for a CodeBlock with that class in the filter. Then your filter can get the unparsed text of the code block and parse it in an appropriate way. In the filter, you can use pandoc.json to parse the text as JSON or pandoc.read() to produce an AST from any format pandoc can parse, including a Markdown document that contains only a YAML block. JSON is convenient if you just want strings to insert in your template (pandoc,json.decode(block.text, false)). A YAML block in Markdown is better if you want to allow formatting in any of the values, e.g., italics in a paper title.

For the output, you can make a raw block as in your example. Alternatively, you could use AST elements to construct the output, which would work for any output format. You could also combine the two approaches by using a template to create an HTML or Markdown string which you then parse with pandoc.read() to get a document. Then you return the document's AST elements from the filter function that handles code blocks.

[TheoWinterhalter]

Alright, thank you very much.

In the end this is what I came up with.

function CodeBlock(el)

  if el.classes[1] == "paper" then
    local data = pandoc.json.decode(el.text, false)

    if not data then
      error("Failed to decode JSON:\n" .. el.text)
    end

    local div_content = {
      pandoc.Header(3, {pandoc.Link(data.title, data.url)}),
      pandoc.Para({pandoc.Str(data.authors)}, {class = "authors"}),
      pandoc.Para({pandoc.Str(data.venue .. "(" .. data.year .. ")")}, {class = "venue"}) -- It seems the class cannot be set
    }

    local div = pandoc.Div(div_content, {class = "paper"})

    return div
  end

  return el

end

While the input looks like

``` paper
{
  "title": "Title",
  "authors": "Author",
  "venue": "Journal",
  "year": "2024",
  "url": "foo.com"
}
```

I would have liked something a bit lighter, but that's a start I guess.

Thanks!

[fiapps]

You have a comment that says, "It seems the class cannot be set": that's correct. The Para AST element does not store an Attr (which can hold a class). If you need a class in the HTML, your options are: (1) wrap the Str in a Span, (2) wrap the Para in a Div, or (3) generate raw HTML.

The line return el is unnecessary: if the function does not return a value (or, equivalently, returns nil), the element is not modified.

[TheoWinterhalter]

I see, thanks for the clarifications!