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.

Sign up for GitHub

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

Jump to bottom

Empty title warning and disappearing metadata with --shift-heading-level-by #5957

Closed
riceissa opened this issue Dec 3, 2019 · 2 comments
Closed

Empty title warning and disappearing metadata with --shift-heading-level-by #5957

riceissa opened this issue Dec 3, 2019 · 2 comments

Comments

@riceissa
Copy link

riceissa commented Dec 3, 2019

I am using pandoc 2.8.0.1.

Here is the Markdown document I am using (blah.md):

---
title: my post
author: alice
---

# first section

first para

# second section

second para

and here is my template (t.html):

<html>
<head><title>$pagetitle$</title></head>
<body>
<h1>$title$</h1>
$body$
</body>
</html>

The desired behavior is for "my post" to appear both in the <title> tag as well as the <h1>, and for "first section" and "second section" to be <h2>. This used to be accomplished by setting --base-header-level=2. Here is the desired output, using pandoc 2.7.3 (pandoc -f markdown -t html5 --template=t.html blah.md -o blah.html --base-header-level=2):

<html>
<head><title>my post</title></head>
<body>
<h1>my post</h1>
<h2 id="first-section">first section</h2>
<p>first para</p>
<h2 id="second-section">second section</h2>
<p>second para</p>
</body>
</html>

On the other hand, with pandoc 2.8.0.1 here is what I get with different values of --shift-heading-level-by:

  • pandoc -f markdown -t html5 --template=t.html blah.md -o blah.html --shift-heading-level-by=0

    <html>
<head><title>my post</title></head>
<body>
<h1>my post</h1>
<h1 id="first-section">first section</h1>
<p>first para</p>
<h1 id="second-section">second section</h1>
<p>second para</p>
</body>
</html>

    ("first section" and "second section" are <h1> rather than <h2>)

  • pandoc -f markdown -t html5 --template=t.html blah.md -o blah.html --shift-heading-level-by=1

    <html>
<head><title>blah</title></head>
<body>
<h1></h1>
<h1>my post</h1>
<h2 id="first-section">first section</h2>
<p>first para</p>
<h2 id="second-section">second section</h2>
<p>second para</p>
</body>
</html>

    (the <title> is "blah" rather than "my post", and there is an empty <h1>)

    I also get a warning:

    [WARNING] This document format requires a nonempty <title> element.
Defaulting to 'blah' as the title.
To specify a title, use 'title' in metadata or --metadata title="...".

  • pandoc -f markdown -t html5 --template=t.html blah.md -o blah.html --shift-heading-level-by=2

    <html>
<head><title>blah</title></head>
<body>
<h1></h1>
<h2>my post</h2>
<h3 id="first-section">first section</h3>
<p>first para</p>
<h3 id="second-section">second section</h3>
<p>second para</p>
</body>
</html>

    (the <title> is "blah" rather than "my post", empty <h1>, and all headings are wrong)

    Again, I get the warning:

    [WARNING] This document format requires a nonempty <title> element.
Defaulting to 'blah' as the title.
To specify a title, use 'title' in metadata or --metadata title="...".

  • pandoc -f markdown -t html5 --template=t.html blah.md -o blah.html --shift-heading-level-by=-1

    <html>
<head><title>first section</title></head>
<body>
<h1>first section</h1>
<p>first para</p>
<p>second section</p>
<p>second para</p>
</body>
</html>

    (<title> is "first section", "second section" is not a heading, "my post" disappears)

I've also noticed that metadata can sometimes disappear in the output. For example, when compiling with pandoc -f markdown -t html5 --standalone blah.md -o blah.html --shift-heading-level-by=1 (i.e. using the default pandoc template, not t.html), the author name ("alice") does not appear in the HTML output. This appears to be because of the way the author block is wrapped around $if(title)$.

I may be misunderstanding how the new --shift-heading-level-by option works. The release notes state "The new option does everything the old one does, but also allows negative shifts". If there is some simple way to obtain the pandoc 2.7.3 behavior, I would like to know.
@jgm jgm mentioned this issue Dec 3, 2019
Closed
@jgm
Copy link
Owner

jgm commented Dec 3, 2019 •
edited
Loading

The option that most closely corresponds with --base-heading-level=2 would be --shift-heading-level-by=1. This moves your level 1 headings up to level 2, as you desire.

But it also moves the metadata title up to a level 1 heading, and depopulates the metadata title, which I see isn't good for you. (And I'd imagine your case is a fairly normal one.)

@mb21 @DanielSWolf maybe you have some thoughts on what should be done?

@jgm jgm added this to the next-release milestone Dec 3, 2019
@jgm jgm closed this as completed in 992f77c Dec 5, 2019
@mb21
Copy link
Collaborator

mb21 commented Dec 6, 2019

Yeah, guess that's a good solution...

renjianxiongqi pushed a commit to renjianxiongqi/pandoc that referenced this issue Dec 23, 2019
@jgm @renjianxiongqi
Roll back part of of --shift-heading-level-by change.
429382a 
With positive heading shifts, starting in 2.8 this option caused
metadata titles to be removed and changed to regular headings.
This behavior is incompatible with the old behavior of
`--base-header-level` and breaks old workflows, so with this
commit we are rolling back this change.

Now, there is an asymmetry in positive and negative heading
level shifts:

+ With positive shifts, the metadata title stays the same and
  does not get changed to a heading in the body.
+ With negative shifts, a heading can be converted into the
  metadata title.

I think this is a desirable combination of features, despite
the asymmetry.  One might, e.g., want to have a document
with level-1 section headigs, but render it to HTML with
level-2 headings, retaining the metadata title (which pandoc
will render as a level-1 heading with the default template).

Closes jgm#5957.
Revises jgm#5615.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@jgm @mb21 @riceissa