pandoc
pandoc copied to clipboard
jgm
pandoc does not set `<title>` despite emitting `Defaulting to '<basename>' as the title.`
When writing to a (custom) html template, pandoc does not set <title> despite emitting Defaulting to '<basename>' as the title.
However, I am glad with the current behaviour (i.e. warn that a title is needed + not setting the title + advice on how to set the title using pandoc). I think setting the title automatically would be too invasive (e.g. I want to set the title later using js).
template.html:
<!DOCTYPE html>
<html>
<head>
<title></title>
</head>
<body>
$body$
</body>
</html>
source file:
echo hello world > test.md
convert to html:
pandoc -f commonmark -t html5 --template=template.html test.md
[WARNING] This document format requires a nonempty <title> element.
Defaulting to 'test' as the title.
To specify a title, use 'title' in metadata or --metadata title="...".
<!DOCTYPE html>
<html>
<head>
<title></title>
</head>
<body>
<p>hello world</p>
</body>
</html>
pandoc -v
pandoc 3.1.11.1
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: C:\Users\A141800\AppData\Roaming\pandoc
Copyright (C) 2006-2023 John MacFarlane. Web: https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.
The default template has this:
<title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
Do you have something similar in your custom template? You need $pagetitle$ not $title$.
I do not want pandoc to set the title, so I do not have $pagetitle$ in my template on purpose. pandoc reports Defaulting to '<basename>' as the title. anyway. I think that this is misleading, hence the report.
However, it works as expected with $pagetitle$:
$ cat template.html
<!DOCTYPE html>
<html>
<head>
<title>$pagetitle$</title>
</head>
<body>
$body$
</body>
</html>
pandoc -f commonmark -t html5 --template=template.html test.md
[WARNING] This document format requires a nonempty <title> element.
Defaulting to 'test' as the title.
To specify a title, use 'title' in metadata or --metadata title="...".
<!DOCTYPE html>
<html>
<head>
<title>test</title>
</head>
<body>
<p>hello world</p>
</body>
</html>
I did not used the same machine (but should not make any difference):
$ pandoc -v
pandoc 3.1.3
Features: -server +lua
Scripting engine: Lua 5.4
User data directory: /home/manon/.local/share/pandoc
Copyright (C) 2006-2023 John MacFarlane. Web: https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.
It's true that the warning is misleading if you're not using a template that uses pagetitle. But currently pandoc doesn't have information about which variables a template includes, so there isn't a way to check.
It could be interesting to expose a function in jgm/doctemplates that would return a list of the variables in a template. (This would be trivial to write.) We could then check to see if the template contains pagetitle before emitting the warning.