Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
nightroman opened this Issue Nov 6, 2017 · 22 comments

Comments

Projects
None yet
5 participants
@nightroman
Copy link

nightroman commented Nov 6, 2017

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:

@jgm

This comment has been minimized.

Copy link
Owner

jgm commented Nov 6, 2017

@nightroman

This comment has been minimized.

Copy link
Author

nightroman commented Nov 6, 2017

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

This comment has been minimized.

Copy link
Author

nightroman commented Nov 6, 2017

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

This comment has been minimized.

Copy link
Author

nightroman commented Nov 6, 2017

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

This comment has been minimized.

Copy link
Owner

jgm commented Nov 6, 2017

@jgm

This comment has been minimized.

Copy link
Owner

jgm commented Nov 6, 2017

@nightroman

This comment has been minimized.

Copy link
Author

nightroman commented Nov 6, 2017

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

This comment has been minimized.

Copy link
Author

nightroman commented Nov 6, 2017

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

This comment has been minimized.

Copy link
Author

nightroman commented Nov 6, 2017

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

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

@nightroman

This comment has been minimized.

Copy link
Author

nightroman commented Nov 6, 2017

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

This comment has been minimized.

Copy link
Owner

jgm commented Nov 6, 2017

@nightroman

This comment has been minimized.

Copy link
Author

nightroman commented Nov 6, 2017

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

gfm, markdown_phpextra -- the same issue.

@jgm

This comment has been minimized.

Copy link
Owner

jgm commented Nov 6, 2017

@jgm

This comment has been minimized.

Copy link
Owner

jgm commented Nov 6, 2017

@jgm

This comment has been minimized.

Copy link
Owner

jgm commented Nov 6, 2017

gfm, markdown_phpextra -- the same issue.

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

@jgm jgm closed this Nov 6, 2017

jennybc added a commit to tidyverse/reprex that referenced this issue Feb 5, 2018

Simpler way to suppress pandoc warning
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

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

@FlorianHeigl

This comment has been minimized.

Copy link

FlorianHeigl commented May 27, 2018

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

This comment has been minimized.

Copy link

stanford-scs commented Jun 20, 2018

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

This comment has been minimized.

Copy link
Owner

jgm commented Jun 21, 2018

@stanford-scs

This comment has been minimized.

Copy link

stanford-scs commented Aug 8, 2018

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

This comment has been minimized.

Copy link

FlorianHeigl commented Aug 8, 2018

@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

This comment has been minimized.

Copy link
Owner

jgm commented Aug 8, 2018

@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.

@robmuh

This comment has been minimized.

Copy link

robmuh commented Jan 16, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.