move running content examples to new page (PR #2118)

5 files changed, 189 insertions, 178 deletions

diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc
index 22fbd1ae..3fc4efd8 100644
--- a/docs/modules/ROOT/pages/features.adoc
+++ b/docs/modules/ROOT/pages/features.adoc
@@ -17,9 +17,9 @@
 * Syntax highlighting with Rouge (preferred), Pygments, or CodeRay
 * Front and back cover pages
 * Page background color or page background image with configurable scaling
-* Page numbering
+* xref:theme:page-numbers.adoc[Page numbering]
 * Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)
-* Customizable running content (header and footer)
+* xref:theme:add-running-content.adoc[Customizable header and footer running content]
 * Section body indent
 * Unbreakable blocks
 * Orphaned section titles avoided (basic support)
diff --git a/docs/modules/theme/nav.adoc b/docs/modules/theme/nav.adoc
index 712f31e3..2316fd81 100644
--- a/docs/modules/theme/nav.adoc
+++ b/docs/modules/theme/nav.adoc
@@ -15,10 +15,11 @@
 *** xref:cjk.adoc[]
 ** xref:extend-theme.adoc[]
 ** xref:custom-role.adoc[]
-** xref:apply-theme.adoc[]
-** xref:asciidoc-attributes.adoc[]
+** xref:add-running-content.adoc[]
 ** xref:page-numbers.adoc[]
 ** xref:print-and-prepress.adoc[]
+** xref:asciidoc-attributes.adoc[]
+** xref:apply-theme.adoc[]
 ** xref:source-highlighting-theme.adoc[]
 * xref:keys.adoc[]
 ** xref:extends.adoc[]
diff --git a/docs/modules/theme/pages/add-running-content.adoc b/docs/modules/theme/pages/add-running-content.adoc
new file mode 100644
index 00000000..aa9ab4fc
--- /dev/null
+++ b/docs/modules/theme/pages/add-running-content.adoc
@@ -0,0 +1,181 @@
+= Add Running Content
+:conum-guard-yaml: #
+
+You can customize the arrangement and style of the running header and footer content by extending the built-in themes and using the `header`, `footer`, and `running-content` category keys.
+
+== Activate the running content
+
+The running content won't be activated unless:
+
+. the periphery (header or footer) is configured, and
+. the `height` key for the periphery is assigned a value.
+
+By default, the built-in themes insert a footer with the page number on the right side of recto pages and the left side of verso pages if you don't specify any running content.
+By extending the base or default themes, you can add content to and customize the layout of the header and footer, or disable the running content.
+Using the `running-content` key, you can also specify on which page the header and footer start.
+
+CAUTION: If the height of the running content periphery is taller than the page margin, the running content will cover the main content.
+To avoid this problem, reduce the height of the running content periphery or make the page margin on that side larger.
+
+See xref:running-content.adoc[] for the complete list of keys you can use to customize your running content.
+
+[#page-number]
+== Modify page number position
+
+To replace the alternating page numbers with a centered page number, you can restrict the footer to a single column and specify the content for the center position.
+
+[,yaml]
+----
+extends: default
+footer:
+  columns: =100%
+  recto:
+    center:
+      content: '{page-number}'
+  verso:
+    center:
+      content: '{page-number}'
+----
+
+If the recto and verso keys have the same content, you can reduce the amount of configuring using a YAML reference.
+
+[,yaml]
+----
+extends: default
+footer:
+  columns: =100%
+  recto: &shared_footer
+    center:
+      content: '{page-number}'
+  verso: *shared_footer
+----
+
+The `&shared_footer` assigns an ID to the YAML subtree under the `recto` key and the `*shared_footer` outputs a copy of it under the `verso` key.
+This technique can be used throughout the theme file as it's a core feature of YAML.
+
+To learn more about the default page numbering and how to customize the numbering, see xref:page-numbers.adoc[].
+
+[#attribute-references]
+== Attribute references
+
+You can use any attribute defined in your AsciiDoc document (such as `doctitle`) in the content of the running header and footer.
+In addition, the following attributes are also available when defining the content keys in the footer:
+
+* `page-count`
+* `page-number` (only set if the `pagenums` attribute is set on the document, which it is by default)
+* `page-layout`
+* `document-title`
+* `document-subtitle`
+* `part-title`
+* `chapter-title`
+* `section-title`
+* `section-or-chapter-title`
+
+If you reference an attribute which is not defined, all the text on that same line in the running content will be dropped.
+This feature allows you to have alternate lines that are selected when all the attribute references are satisfied.
+One case where this is useful is when referencing the `page-number` attribute.
+If you unset the `pagenums` attribute on the document, any line in the running content that makes reference to `\{page-number}` will be dropped.
+
+You can also use built-in AsciiDoc text replacements like `+(C)+`, numeric character references like `+©+`, hexadecimal character references like `+€+`, and inline formatting (e.g., bold, italic, monospace).
+
+Here's an example that shows how attributes and replacements can be used in the running footer:
+
+[,yaml]
+----
+header:
+  height: 0.75in
+  line-height: 1
+  recto:
+    center:
+      content: '(C) ACME -- v{revnumber}, {docdate}'
+  verso:
+    center:
+      content: $header-recto-center-content
+footer:
+  background-image: image:running-content-bg-{page-layout}.svg[]
+  height: 0.75in
+  line-height: 1
+  recto:
+    right:
+      content: '{section-or-chapter-title} | *{page-number}*'
+  verso:
+    left:
+      content: '*{page-number}* | {chapter-title}'
+----
+
+== Multi-line values
+
+You can split the content value across multiple lines using YAML's multiline string syntax.
+In this case, the single quotes around the string are not necessary.
+To force a hard line break in the output, add `{sp}+` to the end of the line in normal AsciiDoc fashion.
+
+[,yaml]
+----
+footer:
+  height: 0.75in
+  line-height: 1.2
+  recto:
+    right:
+      content: |
+        Section Title - Page Number +
+        {section-or-chapter-title} - *{page-number}*
+  verso:
+    left:
+      content: |
+        Page Number - Chapter Title +
+        *{page-number}* - {chapter-title}
+----
+
+TIP: You can use most AsciiDoc inline formatting in the values of these keys.
+For instance, to make the text bold, surround it in asterisks (as shown above).
+One exception to this rule are inline images, which are described in the next section.
+
+== Add an image
+
+You can add an image to the running header or footer using the AsciiDoc inline image syntax.
+The image target is resolved relative to the value of the `pdf-themesdir` attribute.
+If the image macro is the whole value for a column position, you can use the `position` and `fit` attributes to align and scale it relative to the column box.
+Otherwise, the image is treated like a normal inline image, for which you can only adjust the width.
+
+Here's an example of how to use an image in the running header (which also applies for the footer).
+
+[,yaml,subs=attributes+]
+----
+header:
+  height: 0.75in
+  image-vertical-align: 2 {conum-guard-yaml} <1>
+  recto:
+    center:
+      content: image:footer-logo.png[pdfwidth=15pt]
+  verso:
+    center:
+      content: $header-recto-center-content
+----
+<1> You can use the `image-vertical-align` key to slightly nudge the image up or down.
+
+CAUTION: The image must fit in the allotted space for the running header or footer.
+Otherwise, you'll run into layout issues or the image may not display.
+You can adjust the width of the image to a fixed value using the `pdfwidth` attribute.
+Alternatively, you can use the `fit` attribute to set the size of the image dynamically based on the available space.
+Set the `fit` attribute to `scale-down` (e.g., `fit=scale-down`) to reduce the image size to fit in the available space or `contain` (i.e., `fit=contain`) to scale the image (up or down) to fit the available space.
+You should not rely on the `width` attribute to set the image width when converting to PDF.
+
+[#disable]
+== Disable the header or footer
+
+If you define running header and footer content in your theme (including the height), you can still disable this content per document by setting the `noheader` and `nofooter` attributes in the AsciiDoc document header, respectively.
+
+If you extend either the base or default theme, and don't specify content for the footer, the current page number will be added to the right side on recto pages and the left side on verso pages.
+To disable this behavior, you can use the following snippet:
+
+[,yaml]
+----
+extends: default
+footer:
+  recto:
+    right:
+      content: ~
+  verso:
+    left:
+      content: ~
+----
diff --git a/docs/modules/theme/pages/page-numbers.adoc b/docs/modules/theme/pages/page-numbers.adoc
index 4ad212a9..a916cf30 100644
--- a/docs/modules/theme/pages/page-numbers.adoc
+++ b/docs/modules/theme/pages/page-numbers.adoc
@@ -43,5 +43,6 @@ footer:
 
 If you want the running content to also appear on front matter pages, you can use the theme to change the page on which the running content starts with the `running-content-start-at` key.
 For instance, to start the running content on the title page, assuming the title page is enabled, set `running-content-start-at: title` in your theme file.
+To learn more about customizing the running content, see xref:add-running-content.adoc[].
 
 Aside from the configurability mentioned, the page numbering logic is computed automatically.
diff --git a/docs/modules/theme/pages/running-content.adoc b/docs/modules/theme/pages/running-content.adoc
index f66d7f41..384cc417 100644
--- a/docs/modules/theme/pages/running-content.adoc
+++ b/docs/modules/theme/pages/running-content.adoc
@@ -4,20 +4,13 @@
 :conum-guard-yaml: #
 
 The `header`, `footer`, and `running-content` category keys control the arrangement and style of running header and footer content.
-The running content won't be activated unless:
-
-. the periphery (header or footer) is configured, and
-. the `height` key for the periphery is assigned a value.
-
-CAUTION: If the height of the running content periphery is taller than the page margin, the running content will cover the main content.
-To avoid this problem, reduce the height of the running content periphery or make the page margin on that side larger.
 
 [#header]
 == header
 
 The `header` category key accepts the keys listed in the following table.
 
-IMPORTANT: If you don't specify a `height` for either the `header` or `footer` key, it effectively disables the content at that periphery.
+IMPORTANT: If you don't specify a `height` for the header, it effectively disables the header.
 
 [cols="3,4,6a"]
 |===
@@ -245,7 +238,7 @@ header:
 
 The `footer` category key accepts the keys listed in the following table.
 
-IMPORTANT: If you don't specify a `height` for either the `header` or `footer` key, it effectively disables the content at that periphery.
+IMPORTANT: If you don't specify a `height` for the footer, it effectively disables the footer.
 
 [cols="3,4,6a"]
 |===
@@ -532,168 +525,3 @@ If the value is `toc`, and the toc macro is used to position the Table of Conten
 * If the value is `after-toc`, the running content will start after the TOC, no matter where it's placed in the document.
 To disable the running content on TOC pages inserted by the toc macro, set the `noheader` or `nofooter` options on the macro (e.g., `toc::[opts=nofooter]`).
 * If the value of `start-at` is an integer, the running content will start at the specified page of the body (i.e., 1 is the first page, 2 is the second page).
-
-//TODO Move the following sections to a page, such as add-running-content.adoc in the the theme module.
-
-[#disable]
-== Disable the header or footer
-
-If you define running header and footer content in your theme (including the height), you can still disable this content per document by setting the `noheader` and `nofooter` attributes in the AsciiDoc document header, respectively.
-
-If you extend either the base or default theme, and don't specify content for the footer, the current page number will be added to the right side on recto pages and the left side on verso pages.
-To disable this behavior, you can use the following snippet:
-
-[source,yaml]
-
-extends: default
-footer:
-  recto:
-    right:
-      content: ~
-  verso:
-    left:
-      content: ~
-
-
-Instead of erasing the content (which is what the `~` does), you can specify content of your choosing.
-
-[#page-number]
-== Modify page number position
-
-If you want to replace the alternating page numbers with a centered page number, then you can restrict the footer to a single column and specify the content for the center position.
-
-[source,yaml]
-
-extends: default
-footer:
-  columns: =100%
-  recto:
-    center:
-      content: '{page-number}'
-  verso:
-    center:
-      content: '{page-number}'
-
-
-In the last two examples, the recto and verso both have the same content.
-In this case, you can reduce the amount of configuring using a YAML reference.
-For example:
-
-[source,yaml]
-
-extends: default
-footer:
-  columns: =100%
-  recto: &shared_footer
-    center:
-      content: '{page-number}'
-  verso: *shared_footer
-
-
-The `&shared_footer` assigns an ID to the YAML subtree under the `recto` key and the `*shared_footer` outputs a copy of it under the `verso` key.
-This technique can be used throughout the theme file as it's a core feature of YAML.
-
-[#attribute-references]
-== Attribute references
-
-You can use _any_ attribute defined in your AsciiDoc document (such as `doctitle`) in the content of the running header and footer.
-In addition, the following attributes are also available when defining the content keys in the footer:
-
-* `page-count`
-* `page-number` (only set if the `pagenums` attribute is set on the document, which it is by default)
-* `page-layout`
-* `document-title`
-* `document-subtitle`
-* `part-title`
-* `chapter-title`
-* `section-title`
-* `section-or-chapter-title`
-
-If you reference an attribute which is not defined, all the text on that same line in the running content will be dropped.
-This feature allows you to have alternate lines that are selected when all the attribute references are satisfied.
-One case where this is useful is when referencing the `page-number` attribute.
-If you unset the `pagenums` attribute on the document, any line in the running content that makes reference to `\{page-number}` will be dropped.
-
-You can also use built-in AsciiDoc text replacements like `+(C)+`, numeric character references like `+&#169;+`, hexadecimal character references like `+&#x20ac;+`, and inline formatting (e.g., bold, italic, monospace).
-
-Here's an example that shows how attributes and replacements can be used in the running footer:
-
-[source,yaml]
-
-header:
-  height: 0.75in
-  line-height: 1
-  recto:
-    center:
-      content: '(C) ACME -- v{revnumber}, {docdate}'
-  verso:
-    center:
-      content: $header-recto-center-content
-footer:
-  background-image: image:running-content-bg-{page-layout}.svg[]
-  height: 0.75in
-  line-height: 1
-  recto:
-    right:
-      content: '{section-or-chapter-title} | *{page-number}*'
-  verso:
-    left:
-      content: '*{page-number}* | {chapter-title}'
-
-
-== Multi-line values
-
-You can split the content value across multiple lines using YAML's multiline string syntax.
-In this case, the single quotes around the string are not necessary.
-To force a hard line break in the output, add `{sp}+` to the end of the line in normal AsciiDoc fashion.
-
-[source,yaml]
-
-footer:
-  height: 0.75in
-  line-height: 1.2
-  recto:
-    right:
-      content: |
-        Section Title - Page Number +
-        {section-or-chapter-title} - {page-number}
-  verso:
-    left:
-      content: |
-        Page Number - Chapter Title +
-        {page-number} - {chapter-title}
-
-
-TIP: You can use most AsciiDoc inline formatting in the values of these keys.
-For instance, to make the text bold, surround it in asterisks (as shown above).
-One exception to this rule are inline images, which are described in the next section.
-
-== Add an image to the header or footer
-
-You can add an image to the running header or footer using the AsciiDoc inline image syntax.
-The image target is resolved relative to the value of the `pdf-themesdir` attribute.
-If the image macro is the whole value for a column position, you can use the `position` and `fit` attributes to align and scale it relative to the column box.
-Otherwise, the image is treated like a normal inline image, for which you can only adjust the width.
-
-Here's an example of how to use an image in the running header (which also applies for the footer).
-
-[source,yaml,subs=attributes+]
-
-header:
-  height: 0.75in
-  image-vertical-align: 2 {conum-guard-yaml} <1>
-  recto:
-    center:
-      content: image:footer-logo.png[pdfwidth=15pt]
-  verso:
-    center:
-      content: $header-recto-center-content
-
-<1> You can use the `image-vertical-align` key to slightly nudge the image up or down.
-
-CAUTION: The image must fit in the allotted space for the running header or footer.
-Otherwise, you'll run into layout issues or the image may not display.
-You can adjust the width of the image to a fixed value using the `pdfwidth` attribute.
-Alternatively, you can use the `fit` attribute to set the size of the image dynamically based on the available space.
-Set the `fit` attribute to `scale-down` (e.g., `fit=scale-down`) to reduce the image size to fit in the available space or `contain` (i.e., `fit=contain`) to scale the image (up or down) to fit the available space.
-You should not rely on the `width` attribute to set the image width when converting to PDF.