Section break handling when compiling to Pandoc

Posts: 37
Joined: Fri May 04, 2018 8:43 am
Platform: Mac + Windows

Thu May 17, 2018 4:25 pm Post

I have a document with 10 chapters and 40 sections.

When compiling to Pandoc -> ePub, section breaks are rendered as a horizontal line:

Code: Select all


Thus, Pandoc export creates an ePub with 10 xhtml files, one for each chapter.

However, when I export the same project to "ePub 3 eBook," Scrivener uses the section breaks as a delimiter and outputs a separate xhtml file for each section.

Thus, ePub 3 export creates an ePub with 40 xhtml files, one for each section.

Now, for the most part, I prefer the way Pandoc export works, because I want each chapter to be its own file (I could also fix the ePub 3 export by reducing the number of section breaks in the compile settings).

However, my problem is that in some parts of the book, I want to insert a manual page break without creating a new chapter.

For example, in the front matter, I have a copyright page and a dedication. Right now, Pandoc export just puts a line between these, but they really should be on separate pages.

Also, within one chapter, I have a section that includes several different lessons, and I would like to have page breaks between them so that each new lesson starts on the top of a page.

But, it appears that Pandoc does not internally support page breaks yet:

So, do I have any options for inserting page breaks with Pandoc to ePub export inside Scrivener?

User avatar
Site Admin
Posts: 20569
Joined: Tue Jun 13, 2006 11:23 pm
Platform: Mac
Location: Truro, Cornwall

Thu May 17, 2018 6:58 pm Post

Scrivener just invokes Pandoc on a generated plain text file, so here you are limited to what Pandoc can do in terms of breaking files up, and how Pandoc breaks up files.

(Incidentally, "ePub 3 Ebook" would normally only create a separate HTML file for each chapter - "Section Break" is an explicit command to split up the files for that format, and normally you would only have it set before each chapter.)

I believe the only way to have new HTML files created in Pandoc is for the headings of the files to be of the header level that is set as the chapter level (set via "Split chapters at level" in the metadata area). So, if "Split chapters at level" is set to "1", you will need the headings of the documents you want to split to begin "# A Title" and so on.

All the best,
"You can't waltz in here, use my toaster, and start spouting universal truths without qualification."

User avatar
Posts: 22493
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza

Thu May 17, 2018 8:53 pm Post

As for routine, structural level file breaking, what Keith notes above is the best approach. If level 2 headers are your desired break point rather than the chapter level, then you can easily achieve that with a setting.

Procedural Breaking

As noted in the thread you linked to: page breaks are less a structural element and more a function of layout, i.e. CSS. Namely the ‘page-break-before’ directive, which can in theory be applied to any element.

If the problem you are solving is procedural but not one you’d want to solve by actually splitting files (as that can mess up automatic ToC generators, chapter navigation in readers and so forth)—say you want all level 1 headings into new HTML files, but page breaks down to the h2 level, then it is worth nothing that Pandoc uses the <section> element, and it classes them according to level. For example:

Code: Select all

<section id="heading" class="Level2">

So in that case the following CSS would give you page breaks before all h1 and h2 heading elements, but only split by file at h1 elements:

Code: Select all

section.Level2 { page-break-before: always; }

Non-Procedural Breaking

But for cases that are non-procedural—say you’ve got three h2 sections but only one of them should have a page break—a good way of approaching such things with Scrivener is via the use of Section Layouts (and on the project side of things, Section Types). Here is a basic recipe:

Section Type

  1. Use the Project ▸ Project Settings... command and click on the “Section Types” pane.
  2. Click the + button and create a type. I’ll call my example, “Lesson”.
  3. Keep in mind that second tab in this pane. If your lessons are all located on a specific binder level then you could set up the structure to automatically apply the “Lesson” type to that level. For now I’ll assume they are scattered though.

Project setup

  1. For a quick test, locate one of the binder items that is a lesson, right click on it, and set its section type to “Lesson”.
  2. Alternatively, if you have a group with a bunch of lessons nested beneath it, right-click on the group and use the default subdocument type feature.

Compile format setup

  1. Now that we’ve added the semantics of what things are to the binder, we need to sort out how these things are displayed. First edit your compile format.
  2. In the Section Layouts pane, select the layout that is closest to what a lesson should look like, and click the + button to duplicate it. I’ll call my example, “Section with Page Break”.
  3. Pandoc, as with most forms of Markdown, has the innate ability to add structural HTML as you see fit (in other words, you don’t have to wait for them to support specific features, often, because you can do whatever you need to do on top of it). So what we’ll do here is add a little HTML to this layout that will help us break this to a new page.
  4. In the “Prefix” tab, add “<div class="newsection">”, and follow that line with a carriage return.

    Make sure the prefix after title option is disabled—otherwise the page break will happen after the section heading.
  5. In the “Suffix” tab, of course return + "</div>".

    You might want to enable Place suffix after subdocuments, if your lessons are broken up into smaller chunks in the binder.
  6. Briefly double-check the Separators pane for your new layout. You just want empty lines, most likely.
  7. Lastly, we need to add the CSS that will make this div do what it should. Click on the Pandoc Options pane, and add the following:

    Code: Select all

    div.newsection{ page-break-before: always; }
  8. Click Save, and then Assign Section Layouts.... Map the “Lesson” document type to the new “Section with Page Break” layout. You should see the HTML in the preview, if it looks malformed here, now is a good time to fix it. :)

Give that a compile, and see how it works in iBooks. It’s worth noting that not every ebook reader may support this CSS command. But then again, not every ebook reader is going to use the convention of page breaks for even full technical HTML file sections, either! Often the best we can do is stick to standards and at least make sure our directives are correct. Those reading on devices that never display page breaks will likely not notice anything odd with your book anyway, it’s how all of their books work.

Attached is a simple demonstration project of the above.
(91.32 KiB) Downloaded 39 times
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles