Section break handling when compiling to Pandoc

I have a document with 10 chapters and 40 sections.

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

<hr/>

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: https://github.com/jgm/pandoc/issues/1934

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

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,
Keith

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:

<section id="heading" class="Level2">
	<h2>Heading</h2>
	...
</section>

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:

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:

Project setup...

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

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.

Compile Format setup...
  1. 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, “Text Section w/ Break”.

  2. Pandoc has a way of inserting <div> elements where we want them, and wrapping them around sections that should act different is an excellent use of this. We can use Scrivener’s prefix and suffix tabs for the new Section Layout to do so.

  3. In the “Prefix” tab, add “::: break”, and follow that line with a carriage return. This will add a div with the “break” class assigned to it.

    Make sure the prefix after title option is disabled—otherwise the page break will happen after the section heading.

    (You will note in my example project I did something else, I used a different form that gives the div an ID as well, so we can insert a link that jumps to it, for easier referencing of the example. You’ll find the link to jump to it toward the very beginning of the first chapter.)

  4. In the “Suffix” tab we close the div with “:::”, inserting a carriage return before it, so that it falls on its own line.

    You might want to enable Place suffix after subdocuments, if your lessons are broken up into smaller chunks in the binder.

  5. Briefly double-check the Separators pane for your new layout. You just want empty lines, most likely.

  6. 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:

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

    Note that in most cases you’ll want a lot of other CSS as well. If you compile without any CSS first, open the .epub in Sigil and examine the stylesheet.css file, you can copy and paste all of that into the Pandoc Options pane in Scrivener to get a nicer looking result (which is what I did in the example).

  7. Click Save, and then Assign Section Layouts.... Map the “Lesson” document type to the new “Section with Page Break” layout. You should see the Pandoc markup for divs in the preview, if it looks malformed here, now is a good time to fix it. :slight_smile:

Give that a compile, and see how it works in your ebook reader. 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. Sigil, for example, won’t show breaks.

Attached is a simple demonstration project of the above.

custom_break.zip (156.0 KB)