add extended converter example that turns off running content on empt…

…y pages
asciidoctor · Jan 17, 2024 · 591a590 · 591a590
1 parent 253dbcc
commit 591a590
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 0 deletions.
diff --git a/docs/modules/extend/examples/pdf-converter-no-running-content-empty-page.rb b/docs/modules/extend/examples/pdf-converter-no-running-content-empty-page.rb
@@ -0,0 +1,17 @@
+class NoRunningContentOnEmptyPageConverter < (Asciidoctor::Converter.for 'pdf')
+  register_for 'pdf'
+
+  def ink_running_content(*)
+    state.pages.each do |page_|
+      page_.imported if page_.empty?
+    end
+    # or
+    #(1..page_count).each do |pgnum|
+    #  go_to_page pgnum
+    #  page.imported if page.empty?
+    #  ## to write content to an empty page, use this next statement instead
+    #  #ink_prose ' ' if page.empty?
+    #end
+    super
+  end
+end
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
@@ -226,6 +226,23 @@ Then, you can add this number in the left margin at the start of each paragraph
 include::example$pdf-converter-numbered-paragraphs.rb[]
 ----
 
+== No running content on empty page
+
+If a page is labeled as imported, Asciidoctor PDF will not add running content to that page.
+Thus, you can use an extended converter to turn off the running content on otherwise empty pages by marking them as imported.
+
+.Extended converter to turn off running content on empty page
+[,ruby]
+----
+include::example$pdf-converter-no-running-content-on-empty-page.rb[]
+----
+
+This converter does not attempt to detect pages that are empty to make the next page facing (i.e., empty verso pages).
+Therefore, you may want to add a filter to only turn off the running content on those pages.
+
+If the running content on empty pages is causing the PDF to fail validation, you can instead write an non-visible character (such as a space) to those pages instead.
+See the commented code in the example for how to do that.
+
 == Change bars
 
 If you have a preprocessor that adds change metadata to the content, you can use an extended converter to draw change bars to add a visual indicator in the rendered output.