Using heading attributes in Pandoc's Markdown in custom LaTeX templates

[SinTrans]

Hello,

Is it possible to use key/value attributes from Pandoc's Markdown headings in custom Latex templates?

In the Latex memoir class, sectional division are of one of two forms:

\section[⟨toc-title⟩][⟨head-title⟩]{⟨title⟩}
\section*{⟨title⟩}

With the starless \section, you can set a different TOC title than title itself. Could key/value attributes of a Markdown sectional heading be used to utilize the optional inputs to memoir's \section command?

Section 6.2 of the memoir manual - pdf link.

[jgm]

See #4409 and the links there for related discussion.
It would be possible to modify pandoc to check for a short-title key or something like that. But there are some issues that would need to be resolved. (a) This goes against our general desire not to use English-language keywords. (b) Presumably we'd treat the value as plain text and escape it accordingly in LaTeX. This would make it impossible for it to contain e.g. math or italics.

[jgm]

You might get away with just using a filter that handles Header elements and generates appropriate raw LaTeX.

[SinTrans]

I'm going to give the filter a try and report back :)

[SinTrans]

I think I have somewhat of a working Lua filter that can use the key/value heading attributes toc-title and head-title to generate the raw LaTeX as you suggested.

The only problem is I can't figure out how to check if the document class is memoir. I'm not really familiar with Lua, but is there a good way of checking if the document class is memoir in the filter?

Markdown source and Lua filter are listed below.

This screenshot demos bookmark titles and head titles that can differ from the full headings:

The above was generated with the following command using the files below:

$ pandoc -o mwe.pdf --top-level-division chapter  --lua-filter short-titles.lua mwe.md

Lua filter short-titles.lua

--[[
      Pandoc Lua Filter to handle headings with toc-title and head-title
      key attributes
]]

if FORMAT ~= "latex" or
   PANDOC_WRITER_OPTIONS.top_level_division ~= "top-level-chapter" or
   PANDOC_VERSION < {2,17,0} then
  return
end

traverse = 'topdown'

-- this part where we check for memoir class doesn't work as desired
isMemoir = false
function Meta (m)
  local documentclass = pandoc.utils.stringify(m['documentclass'])
  if documentclass == 'memoir' then
    isMemoir = true
  end
end

function Header (h)
  local divisions =
  {
    [1] = "\\chapter[",
    [2] = "\\section[",
    [3] = "\\subsection[",
    [4] = "\\subsubsection[",
    [5] = "\\paragraph[",
    [6] = "\\subparagraph["
  }

  -- match to current heading level
  if (divisions[h.level]) then
    -- both toc-title and head-title are defined
    if (h.attributes["toc-title"] and h.attributes["head-title"]) then
      h = pandoc.RawBlock("latex", divisions[h.level] ..
          h.attributes["toc-title"] .. "][" ..
	  h.attributes["head-title"] .. "]{" ..
	  pandoc.utils.stringify(h.content) .. "}")
    -- if only one is defined, set as toc-title
    elseif (h.attributes["toc-title"] or h.attributes["head-title"]) then
      h = pandoc.RawBlock("latex", divisions[h.level] ..
          (h.attributes["toc-title"] or h.attributes["head-title"]) .. "]{" ..
	  pandoc.utils.stringify(h.content) .. "}")
    end
  end
  return h
end

Markdown source mwe.md

---
title: MWE
papersize: letter
documentclass: memoir
hyperrefoptions:
  - bookmarks
  - bookmarksopen
  - bookmarksdepth=6
header-includes:
  - \usepackage{lipsum}
---
# This is a very long heading, winding its way through clauses and phrases like a river seeking the sea {toc-title="Seeking" head-title="Seeking the sea"}
\lipsum[1-1]

## This long heading attempts to succinctly summarize the ideas in the following section {toc-title="Succinctly"}
paragraph text

### Sometimes, without shortcuts
paragraph text

#### A fourth-level heading that continues to carry along this document's current ideas and descriptions, never intending to end soon, instead choosing to unfold gradually {head-title="The fourth level"}
paragraph text

##### Building anticipation with each successive heading, wondering how deep the dive can get {head-title="Diving into"}
paragraph text

###### Finally reaching the deep dark depths of document divisions {toc-title="The dark depths"}
paragraph text

[SinTrans]

I modified the Lua filter to check for the memoir documentclass so you don't need to specify chapter as top_level_division in the command line. Thank you for pointing me towards using a filter!

Using the above markdown source, this can now be run with:

$ pandoc -o mwe.pdf --lua-filter memoir-short-titles.lua mwe.md

memoir-short-titles.lua

--[[
      memoir-short-titles.lua

      Pandoc Lua filter to handle headings with toc-title and head-title
      key/value attributes when using the memoir class.

      Memoir's starred heading commands have the form:
	\chapter*[<toc-title>][<head-title>]{<title>}

      toc-title and head-title can be specified when using Pandoc's markdown
      headings using key/value attributes:
	# Title {toc-title="TOC title" head-title="Head title"}
]]

if FORMAT ~= "latex" then
  return
end

local is_memoir_class = false
local warning_flag = false

-- check if documentclass is memoir
function check_memoir_class (m)
  local documentclass = pandoc.utils.stringify(m['documentclass'])
  if documentclass == 'memoir' then
    is_memoir_class = true
  end
end

-- use memoir's starred chapters and sections if using memoir class
function use_starred_heading_commands (h)
  if(is_memoir_class == true) then
    local divisions =
    {
      [1] = "\\chapter[",
      [2] = "\\section[",
      [3] = "\\subsection[",
      [4] = "\\subsubsection[",
      [5] = "\\paragraph[",
      [6] = "\\subparagraph["
    }

    if (divisions[h.level]) then
      -- both toc-title and head-title are defined
      if (h.attributes["toc-title"] and h.attributes["head-title"]) then
	h = pandoc.RawBlock("latex", divisions[h.level] ..
	    h.attributes["toc-title"] .. "][" ..
	    h.attributes["head-title"] .. "]{" ..
	    pandoc.utils.stringify(h.content) .. "}")
      -- if only one is defined, set as toc-title
      elseif (h.attributes["toc-title"] or h.attributes["head-title"]) then
	h = pandoc.RawBlock("latex", divisions[h.level] ..
	    (h.attributes["toc-title"] or h.attributes["head-title"]) .. "]{" ..
	    pandoc.utils.stringify(h.content) .. "}")
      end
    end
    return h
  else -- else not memoir class
    if warning_flag == false then
      print("WARNING: documentclass is not set to memoir, so memoir-short-titles.lua filter isn't being used.")
      warning_flag = true
    end
    return h
  end
end

return {{Meta = check_memoir_class}, {Header = use_starred_heading_commands}}