Markdown: recent pandoc --standalone writes not clear warnings about title #4048

nightroman · 2017-11-06T18:50:47Z

I recently moved from pandoc 1.x to 2.0.1.1 and noticed some new not clear warnings.

Example, hello.md:

Hello

Command:

pandoc hello.md --standalone

Output:

> pandoc hello.md --standalone
[WARNING] This document format requires a nonempty <title> element.
  Please specify either 'title' or 'pagetitle' in the metadata.
  Falling back to 'hello'
<HTML output>
...

What does this warning mean?
What is wrong with the markdown file or the pandoc command?

NB: This warning is written to stderr and this causes a lot of pain on calling from
PowerShell (due to its own strange handling of stderr output of external apps).

Related issues:

The text was updated successfully, but these errors were encountered:

jgm · 2017-11-06T19:42:55Z

+++ Roman Kuzmin [Nov 06 17 18:50 ]:

I recently moved from pandoc 1.x to 2.0.1.1 and noticed some new not clear warnings. Example, hello.md: Hello Command: pandoc hello.md --standalone Output: > pandoc hello.md --standalone [WARNING] This document format requires a nonempty <title> element. Please specify either 'title' or 'pagetitle' in the metadata. Falling back to 'hello' <HTML output> ... What does this warning mean? What is wrong with the markdown file or the pandoc command?

It means what it says. HTML5 requires a nonempty title element. You did not specify a title in the metadata (see the manual under "metadata" for how to do this). So pandoc is warning you that it's using the title "hello" (derived from the filename) in order to have a valid title element. This will show up in the title bar of browsers when they look at this web page.

NB: This warning is written to stderr and this causes a lot of pain on calling from PowerShell (due to its own strange handling of stderr output of external apps).

I wasn't aware of these issues. Can you elaborate? By the way, if you don't want any warnings, just use --quiet.

nightroman · 2017-11-06T20:15:18Z

HTML5 requires a nonempty title element. You did not specify a title in the
metadata (see the manual under "metadata" for how to do this). So pandoc is
warning you that it's using the title "hello" (derived from the filename) in
order to have a valid title element. This will show up in the title bar of
browsers when they look at this web page.

I see. Can this be done without a warning? If I get the default title which
pandoc chooses then I am 99% happy. In 1%, when I want a custom title, it's my
duty to read the docs and set it.

I wasn't aware of these issues. Can you elaborate?

There more than one, including subtle depending on environments and hosts.
For example, in the console host run this (i.e. in PowerShell console):

pandoc.exe hello.md --standalone --output hello.html 2>&1

As a result, I am getting something like this:

pandoc.exe : [WARNING] This document format requires a nonempty <title> element.
At C:\tmp\_171106_195128_pandoc_stderr\test.ps1:2 char:1
+ pandoc.exe hello.md --standalone --output hello.html 2>&1
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: ([WARNING] This ...title> element.:String) [], RemoteException
    + FullyQualifiedErrorId : NativeCommandError

  Pl
ease

s
p
e
c
i
f
y
... a lot of lines with one character of the message each ....

nightroman · 2017-11-06T20:23:56Z

see the manual under "metadata" for how to do this

Is it this part?

    Metadata blocks

    Extension: pandoc_title_block

    If the file begins with a title block

    % title

Then it says it is related to the extension pandoc_title_block.
But I am not using this extension in my command.
Do I have to use it then? That's strange or I miss something.

nightroman · 2017-11-06T20:38:25Z

Here is the PowerShell known issue PowerShell/PowerShell#3813 and the coming (who knows when) fix PowerShell/PowerShell#5190

Currently PowerShell "wraps stderr as ErrorRecord". The result depends on the current settings and the host. It may fail, produce strange errors and output, etc.

jgm · 2017-11-06T22:21:25Z

Well, that looks like a PowerShell problem, not a pandoc problem. We don't really have an alternative to writing the warnings to stderr, becaue pandoc can be used as a pipe, writing its output to stdout, and if warnings went there too, things would be messed up. +++ Roman Kuzmin [Nov 06 17 20:38 ]:

…

Here is the PowerShell known issue [1]PowerShell/PowerShell#5190 Currently PowerShell "wraps stderr as ErrorRecord". The result depends on settings and the host. It may fail, produce strange errors and output, etc. — You are receiving this because you commented. Reply to this email directly, [2]view it on GitHub, or [3]mute the thread. References 1. PowerShell/PowerShell#5190 2. #4048 (comment) 3. https://github.com/notifications/unsubscribe-auth/AAAL5EyzyM7sdAwR3X7Q89JYEURQsj2iks5sz25CgaJpZM4QTs7W

jgm · 2017-11-06T22:23:01Z

+++ Roman Kuzmin [Nov 06 17 20:23 ]:

Then it says it is related to the extension pandoc_title_block. But I am not using this extension in my command.

It's built into pandoc's markdown by default. You can also use a YAML metadata block, or specify the title on the command line `--metadata title="Blah"`.

nightroman · 2017-11-06T23:05:33Z

It's built into pandoc's markdown by default.

Probably not:

Example:

% title

Hello

Command:

pandoc hello.md --standalone --from=markdown_strict --output hello.html

Output:

C:\tmp\_171106_195128_pandoc_stderr>pandoc hello.md --standalone --from=markdown_strict --output hello.html
[WARNING] This document format requires a nonempty <title> element.
  Please specify either 'title' or 'pagetitle' in the metadata.
  Falling back to 'hello'

nightroman · 2017-11-06T23:11:43Z

title on the command line --metadata title="Blah".

Aha, this is what I am looking for. Thank you.

No problem, if all is by design, please close.

NB: IMHO it kind of violates the least surprise principle. I have to use not obvious tricks (documented, yes). I did not have to do this in the old version. Just my opinion.

nightroman · 2017-11-06T23:18:35Z

Aha, this is what I am looking for. Thank you.

Hmm, no. The title is rendered in the document itself....

nightroman · 2017-11-06T23:30:36Z

Example:

% title

Hello

Command:

pandoc hello.md --standalone --from=markdown_strict --output hello.html --metadata title=Blah.

Output html:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>Blah.</title>
  <style type="text/css">
      code{white-space: pre-wrap;}
      span.smallcaps{font-variant: small-caps;}
      div.line-block{white-space: pre-line;}
      div.column{display: inline-block; vertical-align: top; width: 50%;}
  </style>
  <!--[if lt IE 9]>
    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
  <![endif]-->
</head>
<body>
<header>
<h1 class="title">Blah.</h1>
</header>
<p>% title</p>
<p>Hello</p>
</body>
</html>

In the browser it is rendered as

Blah.

% title

Hello

I did not mean Blah. to be shown in the page.
Is it by design?

jgm · 2017-11-06T23:30:39Z

You're specifying markdown_strict, which turns off pandoc extensions. +++ Roman Kuzmin [Nov 06 17 23:05 ]:

…

It's built into pandoc's markdown by default. Probably not: Example: % title Hello Command: pandoc hello.md --standalone --from=markdown_strict --output hello.html Output: C:\tmp\_171106_195128_pandoc_stderr>pandoc hello.md --standalone --from=markdown _strict --output hello.html [WARNING] This document format requires a nonempty <title> element. Please specify either 'title' or 'pagetitle' in the metadata. Falling back to 'hello' — You are receiving this because you commented. Reply to this email directly, [1]view it on GitHub, or [2]mute the thread. References 1. #4048 (comment) 2. https://github.com/notifications/unsubscribe-auth/AAAL5AHk3kJWMGJSr7A9CEFJ9ZztlVT5ks5sz5C9gaJpZM4QTs7W

nightroman · 2017-11-06T23:33:03Z

You're specifying markdown_strict, which turns off pandoc extensions.

gfm, markdown_phpextra -- the same issue.

jgm · 2017-11-06T23:35:08Z

+++ Roman Kuzmin [Nov 06 17 23:11 ]:

NB: IMHO it kind of violates the least surprise principle. I have to use not obvious tricks (documented, yes). I did not have to do this in the old version. Just my opinion.

The old version would just happily produce an invalid HTML5 document. If we don't want to do that, we need to put something in the title element, and I think a warning to the user that we're populating the title element with text they didn't explicitly specify is appropriate in that case. Better to be surprised by a warning than surprised by something inserted without your knowledge into the document itself.

jgm · 2017-11-06T23:35:48Z

+++ Roman Kuzmin [Nov 06 17 23:18 ]:

Aha, this is what I am looking for. Thank you. Hmm, no. The title is rendered in the document itself....

If you don't want that, then set pagetitle instead of title (as the warning suggests).

jgm · 2017-11-06T23:36:48Z

gfm, markdown_phpextra -- the same issue.

Well yes. These don't include pandoc-specific extensions either.
Please see the MANUAL.

Fixes #156 Idea to use --quiet came from here: jgm/pandoc#4048 Idea for previous solution (more targetted, more involved) came from here: rstudio/rmarkdown@6558c3c

See jgm/pandoc#4048

FlorianHeigl · 2018-05-27T13:37:16Z

Definitely wasn't a clear message - i didn't even notice I finally was getting beautiful CSS, it just sounds like it's totally failing. (now also will use --metadata title="Blah" since I want to not set it in the markdown till I understand more)

stanford-scs · 2018-06-20T17:29:59Z

So what's the resolution here? Is there some way to put title metadata in a document of type gfm or markdown_strict? I certainly can't get pandoc to output such a gfm file from its own markdown format--it seems to strip the title off always.

jgm · 2018-06-21T09:11:14Z

No---these formats don't support metadata. However, for `markdown_strict` (but not `gfm`) you can add in support for pandoc-style yaml metadata: `-f markdown_strict+yaml_metadata_block`. (This is not currently possible in `gfm` because here we just wrap a C library.) stanford-scs <notifications@github.com> writes:

…

So what's the resolution here? Is there some way to put title metadata in a document of type gfm or markdown_strict? I certainly can't get pandoc to output such a gfm file from its own markdown format--it seems to strip the title off always. -- You are receiving this because you modified the open/close state. Reply to this email directly or view it on GitHub: #4048 (comment)

stanford-scs · 2018-08-08T21:27:49Z

This continues to be really frustrating. Are you just saying don't use gfm format as input for pandoc? Otherwise, can you just break it down in really stupid terms and spoon feed me a solution here for turning a gfm file into an html file?

Basically I would like to preview mardown files before pushing them to github by translating them to HTML. Surely I can't be the only person to want to do this. But this annoying problem is such that it is not clear whether or not pandoc could be used for the purpose. I would love a definitive answer of yes or no, and if no, suggestions for other tools would of course be welcome...

FlorianHeigl · 2018-08-08T21:31:36Z

@stanford-scs this is what I ended up using:

https://gist.github.com/FlorianHeigl/773411d0b2d180d5974508d4b716256a

I lack the css/html understanding to make anything more of it, but it is my "everyday toolchain" now. Pending inotify or other extensions that will probably take another year.
At some point it was time to cut my losses and just have something good enough...

jgm · 2018-08-08T22:57:49Z

@stanford-scs if you have YAML metadata, but use GitHub extensions, you can try

pandoc -f markdown_github+yaml_metadata_block

(or use markdown_strict+yaml_metadata_block if the only extension you need is YAML metadata.

markdown_github is our legacy parser for gfm. It's not as accurate as gfm, which you should use if you want the input to be parsed exactly as GitHub does it. But unlike gfm you can tack on the YAML metadata extension.

rwxrob · 2019-01-16T16:16:15Z

Just hit this myself. One nice-to-have would be potentially suppressing that warning if --template is specified, but --quiet is fine with me. Overall I agree with the warning because if you use $title$ anywhere you might be surprised.

xealits · 2020-11-16T20:24:55Z

+++ Roman Kuzmin [Nov 06 17 23:18 ]:
Aha, this is what I am looking for. Thank you. Hmm, no. The title is rendered in the document itself....
If you don't want that, then set pagetitle instead of title (as the warning suggests).

Let's add pagetitle to the man page? -> pull request #6843.

allefeld · 2022-01-07T14:15:07Z

Is it possible to achieve this behavior – that the file name is used as the basis for the <title> element – explicitly through a setting in a defaults file?

I like this behavior, but would like to get rid of the warning. I understand the reason for the warning – something happens that the user didn't ask for – so it would be good to be able to ask for it.

jgm · 2022-01-07T18:29:17Z

@allefeld you can always set the pagetitle variable explicitly in a defaults file (variables section).
But there's no generic way to get this behavior without explicitly typing the filename.

jgm closed this as completed Nov 6, 2017

yihui mentioned this issue Nov 14, 2017

Issues with pandoc 2.0 and rendering README.Rmd rstudio/rmarkdown#1200

Closed

yangle added a commit to yangle/mdh that referenced this issue Feb 18, 2018

Suppress a pandoc warning about missing title

d37af12

See jgm/pandoc#4048

ghost mentioned this issue Sep 17, 2018

Provide example in output #4909

Closed

haozhu233 mentioned this issue Jan 22, 2019

Warning message "This document format requires a nonempty <title> element" haozhu233/kableExtra#310

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Markdown: recent pandoc --standalone writes not clear warnings about title #4048

Markdown: recent pandoc --standalone writes not clear warnings about title #4048

nightroman commented Nov 6, 2017

jgm commented Nov 6, 2017 via email

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017 •

edited

jgm commented Nov 6, 2017 via email

jgm commented Nov 6, 2017 via email

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017

jgm commented Nov 6, 2017 via email

nightroman commented Nov 6, 2017

jgm commented Nov 6, 2017 via email

jgm commented Nov 6, 2017 via email

jgm commented Nov 6, 2017

FlorianHeigl commented May 27, 2018

stanford-scs commented Jun 20, 2018

jgm commented Jun 21, 2018 via email •

edited

stanford-scs commented Aug 8, 2018

FlorianHeigl commented Aug 8, 2018 •

edited

jgm commented Aug 8, 2018

rwxrob commented Jan 16, 2019

xealits commented Nov 16, 2020

allefeld commented Jan 7, 2022

jgm commented Jan 7, 2022

Markdown: recent pandoc --standalone writes not clear warnings about title #4048

Markdown: recent pandoc --standalone writes not clear warnings about title #4048

Comments

nightroman commented Nov 6, 2017

jgm commented Nov 6, 2017 via email

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017 • edited

jgm commented Nov 6, 2017 via email

jgm commented Nov 6, 2017 via email

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017

nightroman commented Nov 6, 2017

jgm commented Nov 6, 2017 via email

nightroman commented Nov 6, 2017

jgm commented Nov 6, 2017 via email

jgm commented Nov 6, 2017 via email

jgm commented Nov 6, 2017

FlorianHeigl commented May 27, 2018

stanford-scs commented Jun 20, 2018

jgm commented Jun 21, 2018 via email • edited

stanford-scs commented Aug 8, 2018

FlorianHeigl commented Aug 8, 2018 • edited

jgm commented Aug 8, 2018

rwxrob commented Jan 16, 2019

xealits commented Nov 16, 2020

allefeld commented Jan 7, 2022

jgm commented Jan 7, 2022

nightroman commented Nov 6, 2017 •

edited

jgm commented Jun 21, 2018 via email •

edited

FlorianHeigl commented Aug 8, 2018 •

edited