Section break handling when compiling to Pandoc

Scrivener Scrivener for macOS
3

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)