Pandoc : set document title to first title

Question

I'm creating a library on github, so I'm using a Markdown file for that, with the following structure:

# My main title
## My first section
...
## My second section
...

But unfortunately, when I use pandoc to convert this document into latex:

pandoc README.md --number-sections -f markdown -t latex -s -o doc.tex

the document does not have any title, and the numbering starts from the main title:

1. My main title
1.1. My first section
...
1.2. My second section
...

While I'd like something like

My main title <=== document title
1. My first section
...
2. My second section
...

I could of course use sed to change all ## to #, and replace the main title with % Document My main title but it looks quite dirty to me. What is the good way to proceed?

Thanks!

Resolved

Answer 1

Note: this answer applies to all pandoc versions > 2.0, but see the answer by @sww1235 for a simpler method that works with later pandoc versions.

---

Best to use a pandoc filter to do this. Here's a Lua filter that does what you need. Store it in a file, e.g. promote-headers.lua and call pandoc with pandoc --lua-filter=promote-headers.lua.

local title

-- Promote all headers by one level. Set title from level 1 headers,
-- unless it has been set before.
function promote_header (header)

  if header.level >= 2 then
    header.level = header.level - 1
    return header
  end

  if not title then
    title = header.content
    return {}
  end

  local msg = '[WARNING] title already set; discarding header "%s"\n'
  io.stderr:write(msg:format(pandoc.utils.stringify(header)))
  return {}
end

return {
  {Meta = function (meta) title = meta.title end}, -- init title
  {Header = promote_header},
  {Meta = function (meta) meta.title = title; return meta end}, -- set title
}

Erlanger

Answer 2

As of git commit 88dc6fac5d in Pandoc, you can now use the --shift-heading-level-by option in Pandoc to promote metadata titles to first level headings (+1 shift), and first level headings to metadata titles (-1 shift). This is available from pandoc 2.8 and up. Pandoc manual reference

Sauter

This doesn't seem to work. Specifying --shift-heading-level-by=-1 results in the document title being dropped. – Deduction

@DanielWolf Did you miss using the -s option on the command line? – Grenoble

@YongweiWu Thanks, that did it! I knew the "standalone" flag, but I didn't know it had any effect on AsciiDoc output. – Deduction