add page break and chapter name options for printing

[Evian-Zhang]

Background

For now, the only way to export to PDF format is by exporting to HTML and click the print button. However, the printed version simply hide the sidebar and merge all the chapters into one. This can lead to the loss of chapter information.

For example:

Chapter1.md:

This is chapter 1.

Chapter2.md:

This is chapter 2.

The printed version is

<p>This is chapter 1.</p>
<p>This is chapter 2.</p>

We can't determine the paragraph is in which chapter, which may be important for some books.

Solutions

I add two options to solve this problem:

In book.toml:

[output.html.print]
page-break = true
chapter-name = true

First, page-break inserts page breaks between chapters. This is a common practice in many markdown editors, such as Typora. To implement this feature, I use CSS property break-before (and page-break- before for compatibility).

Second, chapter-name inserts chapter name before each chapter.

The above two options only works for the printed version (PDF in most case), and will not affect the HTML version.

[ehuss]

Thanks! A few questions:

• Why make the page-break an option? Why not just have that on all the time? (It definitely looks a lot better, BTW!)

• I'm not sure I understand the purpose of the chapter-name option. It is standard practice for chapters to start with a markdown header with the name of the chapter, so it seems like this would cause the chapter names to appear twice. Do you have chapters that don't include the name? Can you say more why that would happen?

[Evian-Zhang]

Thanks! A few questions:

• Why make the page-break an option? Why not just have that on all the time? (It definitely looks a lot better, BTW!)
• I'm not sure I understand the purpose of the chapter-name option. It is standard practice for chapters to start with a markdown header with the name of the chapter, so it seems like this would cause the chapter names to appear twice. Do you have chapters that don't include the name? Can you say more why that would happen?

1. Ok, I will make a commit.
2. For example, markdown abc.md has first-level header # section1, # section 2. In most blog websites in my country that supports uploading markdown, it is common practice to treat abc as blog title, and section 1, section 2 as section header. And after we complete a series abc_1.md, abc_2.md, ..., we want to merge them into one PDF, and the current version of mdbook only preserves the headers, dropping the filename that serves as chapter title. By the way, if we write the file name again as a first-level header, does it mean the markdown file that contains this chapter only has one first-level header, and the sections name can only use h2 or smaller? I think this may be a waste to h1 header.

[azerupi]

Improving the print version is great! I am all for this change.

As @ehuss said, it is standard practice (but not a requirement) to write the title of the chapter at the beginning of the file as first level heading.

By the way, if we write the file name again as a first-level header, does it mean the markdown file that contains this chapter only has one first-level header, and the sections name can only use h2 or smaller? I think this may be a waste to h1 header.

Yes that is right. Generally the chapter title is h1 and sub-sections are h2 or lower. I can see your point, but I see in the diff that you inject the chapter title with <h1> tags. If your sections are also h1 then they have the same format in the output. I would consider that more of a problem than wasting one heading level on one title, no?

I would definitely not expect the chapter titles and section titles to have the same level in the printout version (even if it is off by default). What are your thoughts about this?

[Evian-Zhang]

Improving the print version is great! I am all for this change.

As @ehuss said, it is standard practice (but not a requirement) to write the title of the chapter at the beginning of the file as first level heading.

By the way, if we write the file name again as a first-level header, does it mean the markdown file that contains this chapter only has one first-level header, and the sections name can only use h2 or smaller? I think this may be a waste to h1 header.

Yes that is right. Generally the chapter title is h1 and sub-sections are h2 or lower. I can see your point, but I see in the diff that you inject the chapter title with <h1> tags. If your sections are also h1 then they have the same format in the output. I would consider that more of a problem than wasting one heading level on one title, no?

I would definitely not expect the chapter titles and section titles to have the same level in the printout version (even if it is off by default). What are your thoughts about this?

From MDN's doc Heading elements:

You should only use one <h1> per page. Using more than one will not result in an error, but using only one is seen as a best practice. It makes logical sense — <h1> is the most important heading, and tells you what the purpose of the overall page is. You wouldn't have a book with more than one title, or a movie with more than one name! Having a single top-level title is also arguably better for screenreader users, and SEO.

As it is the preferred practice, I will remove the chapter-name option.

[Evian-Zhang]

This pr is out-dated, and a new pr #1485 is proposed.