diff options
Diffstat (limited to 'docs/modules/theme/pages/running-content.adoc')
| -rw-r--r-- | docs/modules/theme/pages/running-content.adoc | 851 |
1 files changed, 851 insertions, 0 deletions
diff --git a/docs/modules/theme/pages/running-content.adoc b/docs/modules/theme/pages/running-content.adoc new file mode 100644 index 00000000..76328821 --- /dev/null +++ b/docs/modules/theme/pages/running-content.adoc @@ -0,0 +1,851 @@ += Running Content Category Keys +:navtitle: Running Content +:conum-guard-yaml: # + +== Running header and footer content + +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. + +[#key-prefix-header,cols="3,4,6a"] +|=== +|Key |Value Type |Example + +|`background-color`^[1]^ +|xref:color.adoc[Color] + +(default: _not set_) +| +[,yaml] +---- +header: + background-color: '#eeeeee' +---- + +|`background-image` +|image macro + +(default: _not set_) +| +[,yaml] +---- +header: + background-image: image:running-content.svg[fit=contain] +---- + +|`border-color` +|xref:color.adoc[Color] + +(default: _not set_) +| +[,yaml] +---- +header: +border-color: '#dddddd' +---- + +|`border-style` +|`solid` {vbar} `double` {vbar} `dashed` {vbar} `dotted` + +(default: `solid`) +| +[,yaml] +---- +header: + border-style: dashed +---- + +|`border-width` +|xref:measurement-units.adoc[Measurement] + +(default: `$base-border-width`) +| +[,yaml] +---- +header: + border-width: 0.25 +---- + +|`column-rule-color` +|xref:color.adoc[Color] + +(default: _not set_) +| +[,yaml] +---- +header: + column-rule-color: '#CCCCCC' +---- + +|`column-rule-spacing` +|xref:measurement-units.adoc[Measurement] + +(default: `0`) +| +[,yaml] +---- +header: + column-rule-spacing: 5 +---- + +|`column-rule-style` +|`solid` {vbar} `double` {vbar} `dashed` {vbar} `dotted` + +(default: `solid`) +| +[,yaml] +---- +header: + column-rule-style: dashed +---- + +|`column-rule-width` +|xref:measurement-units.adoc[Measurement] + +(default: _not set_) +| +[,yaml] +---- +header: + column-rule-width: 0.25 +---- + +|`font-color` +|xref:color.adoc[Color] + +(default: _inherit_) +| +[,yaml] +---- +header: + font-color: '#333333' +---- + +|`font-family` +|xref:font-support.adoc[Font family name] + +(default: _inherit_) +| +[,yaml] +---- +header: + font-family: Noto Serif +---- + +|`font-kerning` +|`normal` {vbar} `none` + +(default: _inherit_) +| +[,yaml] +---- +header: + font-kerning: none +---- + +|`font-size` +|xref:language.adoc#values[Number] + +(default: _inherit_) +| +[,yaml] +---- +header: + font-size: 9 +---- + +|`font-style` +|xref:text.adoc#font-style[Font style] + +(default: _inherit_) +| +[,yaml] +---- +header: + font-style: italic +---- + +|`height`^[2]^ +|xref:measurement-units.adoc[Measurement] + +(default: _not set_) +| +[,yaml] +---- +header: + height: 0.75in +---- + +|`line-height` +|xref:language.adoc#values[Number] + +(default: `$base-line-height`) +| +[,yaml] +---- +header: + line-height: 1.2 +---- + +|`margin` +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom (n/a),left\]] + +(default: [`0`, `inherit`]) +| +[,yaml] +---- +header: + margin: 0 +---- + +|`content-margin` +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] + +(default: [`0`, `inherit`]) +| +[,yaml] +---- +header: + content-margin: 0 +---- + +|`padding`^[3]^ +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] + +(default: `0`) +| +[,yaml] +---- +header: + padding: [0, 3, 0, 3] +---- + +|`image-vertical-align` +|`top` {vbar} `middle` {vbar} `bottom` {vbar} xref:measurement-units.adoc[Measurement] + +(default: _not set_) +| +[,yaml] +---- +header: + image-vertical-align: 4 +---- + +|`sectlevels`^[4]^ +|Integer + +(default: `2`) +| +[,yaml] +---- +header: + sectlevels: 3 +---- + +|`text-transform` +|xref:text.adoc#transform[Text transform] + +(default: `none`) +| +[,yaml] +---- +header: + text-transform: uppercase +---- + +|`title-style` +|`document` {vbar} `toc` {vbar} `basic` + +(default: `document`) +| +[,yaml] +---- +header: + title-style: toc +---- + +|`vertical-align` +|`top` {vbar} `middle` {vbar} `bottom` {vbar} [`top` {vbar} `middle` {vbar} `bottom`, xref:measurement-units.adoc[Measurement]] + +(default: `middle`) +| +[,yaml] +---- +header: + vertical-align: middle +---- + +|`<side>-columns`^[5]^ +|Column specs triple + +(default: _not set_) +| +[,yaml] +---- +header: + recto: + columns: <25% =50% >25% +---- + +|`<side>-margin`^[5]^ +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom (n/a),left\]] + +(default: _inherit_) +| +[,yaml] +---- +header: + recto: + margin: [0, 0, 0, inherit] +---- + +|`<side>-content-margin`^[5]^ +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] + +(default: _inherit_) +| +[,yaml] +---- +header: + recto: + content-margin: [0, 0, 0, inherit] +---- + +|`<side>-padding`^[5]^ +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] + +(default: _inherit_) +| +[,yaml] +---- +header: + recto: + padding: [0, 3, 0, 3] +---- + +|`<side>-<position>-content`^[5,6]^ +|xref:quoted-string.adoc[Quoted string] + +(default: '\{page-number}') +| +[,yaml] +---- +header: + recto: + left: + content: '{page-number}' +---- +|=== +1. To make the background color and border span the width of the page, set the margin to `0` (and adjust the content-margin accordingly). +2. *If the height is not set, the running content at this periphery is disabled.* +3. Do not use negative margins. +Instead, adjust the values of the `margin` and `content-margin` keys. +4. The maximum section level considered when assigning the implicit `section-title` attribute (and related) available to the running content. +5. `<side>` can be `recto` (right-hand, odd-numbered pages) or `verso` (left-hand, even-numbered pages). +The `columns` key can also be defined one level up (on `header` or `footer`), in which case the setting will be inherited. +Where the page sides fall in relation to the physical or printed page number is controlled using the `pdf-folio-placement` attribute (except when `media=prepress`, which implies `physical`). +The column rules are only added if the `columns` key is specified. +6. `<position>` can be `left`, `center` or `right`. + +TIP: Although not listed in the table above, you can control the font settings (`font-family`, `font-size`, `font-color`, `font-style`, `text-transform`) that get applied to the running content in each column position for each page side (e.g., `header-<side>-<position>-font-color`). +For example, you can set the font color used for the right-hand column on recto pages by setting `header-recto-right-font-color: 6CC644`. + +[#footer] +== footer + +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. + +[#key-prefix-footer,cols="3,4,6a"] +|=== +|Key |Value Type |Example + +|`background-color`^[1]^ +|xref:color.adoc[Color] + +(default: _not set_) +| +[,yaml] +---- +footer: + background-color: '#eeeeee' +---- + +|`background-image` +|image macro + +(default: _not set_) +| +[,yaml] +---- +footer: + background-image: image:running-content.svg[fit=contain] +---- + +|`border-color` +|xref:color.adoc[Color] + +(default: _not set_) +| +[,yaml] +---- +footer: + border-color: '#dddddd' +---- + +|`border-style` +|`solid` {vbar} `double` {vbar} `dashed` {vbar} `dotted` + +(default: `solid`) +| +[,yaml] +---- +footer: + border-style: dashed +---- + +|`border-width` +|xref:measurement-units.adoc[Measurement] + +(default: `$base-border-width`) +| +[,yaml] +---- +footer: + border-width: 0.25 +---- + +|`column-rule-color` +|xref:color.adoc[Color] + +(default: _not set_) +| +[,yaml] +---- +footer: + column-rule-color: '#CCCCCC' +---- + +|`column-rule-spacing` +|xref:measurement-units.adoc[Measurement] + +(default: `0`) +| +[,yaml] +---- +footer: + column-rule-spacing: 5 +---- + +|`column-rule-style` +|`solid` {vbar} `double` {vbar} `dashed` {vbar} `dotted` + +(default: `solid`) +| +[,yaml] +---- +footer: + column-rule-style: dashed +---- + +|`column-rule-width` +|xref:measurement-units.adoc[Measurement] + +(default: _not set_) +| +[,yaml] +---- +footer: + column-rule-width: 0.25 +---- + +|`font-color` +|xref:color.adoc[Color] + +(default: _inherit_) +| +[,yaml] +---- +footer: + font-color: '#333333' +---- + +|`font-family` +|xref:font-support.adoc[Font family name] + +(default: _inherit_) +| +[,yaml] +---- +footer: + font-family: Noto Serif +---- + +|`font-kerning` +|`normal` {vbar} `none` + +(default: _inherit_) +| +[,yaml] +---- +footer: + font-kerning: none +---- + +|`font-size` +|xref:language.adoc#values[Number] + +(default: _inherit_) +| +[,yaml] +---- +footer: + font-size: 9 +---- + +|`font-style` +|xref:text.adoc#font-style[Font style] + +(default: _inherit_) +| +[,yaml] +---- +footer: + font-style: italic +---- + +|`height`^[2]^ +|xref:measurement-units.adoc[Measurement] + +(default: _not set_) +| +[,yaml] +---- +footer: + height: 0.75in +---- + +|`line-height` +|xref:language.adoc#values[Number] + +(default: `$base-line-height`) +| +[,yaml] +---- +footer: + line-height: 1.2 +---- + +|`margin` +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top (n/a),right,bottom,left\]] + +(default: [`0`, `inherit`]) +| +[,yaml] +---- +footer: + margin: 0 +---- + +|`content-margin` +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] + +(default: [`0`, `inherit`]) +| +[,yaml] +---- +footer: + content-margin: 0 +---- + +|`padding`^[3]^ +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] + +(default: `0`) +| +[,yaml] +---- +footer: + padding: [0, 3, 0, 3] +---- + +|`image-vertical-align` +|`top` {vbar} `middle` {vbar} `bottom` {vbar} xref:measurement-units.adoc[Measurement] + +(default: _not set_) +| +[,yaml] +---- +footer: + image-vertical-align: 4 +---- + +|`sectlevels`^[4]^ +|Integer + +(default: `2`) +| +[,yaml] +---- +footer: + sectlevels: 3 +---- + +|`text-transform` +|xref:text.adoc#transform[Text transform] + +(default: `none`) +| +[,yaml] +---- +footer: + text-transform: uppercase +---- + +|`title-style` +|`document` {vbar} `toc` {vbar} `basic` + +(default: `document`) +| +[,yaml] +---- +footer: + title-style: toc +---- + +|`vertical-align` +|`top` {vbar} `middle` {vbar} `bottom` {vbar} [top {vbar} middle {vbar} bottom, xref:measurement-units.adoc[Measurement]] + +(default: `middle`) +| +[,yaml] +---- +footer: + vertical-align: top +---- + +|`<side>-columns`^[5]^ +|Column specs triple + +(default: _not set_) +| +[,yaml] +---- +footer: + verso: + columns: <50% =0% <50% +---- + +|`<side>-margin`^[5]^ +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top (n/a),right,bottom,left\]] + +(default: [`0`, `inherit`]) +| +[,yaml] +---- +footer: + verso: + margin: [0, inherit, 0, 0] +---- + +|`<side>-content-margin`^[5]^ +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] + +(default: _inherit_) +| +[,yaml] +---- +footer: + verso: + content-margin: [0, inherit, 0, 0] +---- + +|`<side>-padding`^[5]^ +|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] + +(default: _inherit_) +| +[,yaml] +---- +footer: + verso: + padding: [0, 3, 0, 3] +---- + +|`<side>-<position>-content`^[5,6]^ +|xref:quoted-string.adoc[Quoted string] + +(default: `'\{page-number}'`) +| +[,yaml] +---- +footer: + verso: + center: + content: '{page-number}' +---- +|=== +1. To make the background color and border span the width of the page, set the margin to `0` (and adjust the content-margin accordingly). +2. *If the height is not set, the running content at this periphery is disabled.* +3. Do not use negative margins. +Instead, adjust the values of the `margin` and `content-margin` keys. +4. The maximum section level considered when assigning the implicit `section-title` attribute (and related) available to the running content. +5. `<side>` can be `recto` (right-hand, odd-numbered pages) or `verso` (left-hand, even-numbered pages). +The `columns` key can also be defined one level up (on `header` or `footer`), in which case the setting will be inherited. +Where the page sides fall in relation to the physical or printed page number is controlled using the `pdf-folio-placement` attribute (except when `media=prepress`, which implies `physical`). +The column rules are only added if the `columns` key is specified. +6. `<position>` can be `left`, `center` or `right`. + +TIP: Although not listed in the table above, you can control the font settings (`font-family`, `font-size`, `font-color`, `font-style`, `text-transform`) that get applied to the running content in each column position for each page side (e.g., `footer-<side>-<position>-font-color`). +For example, you can set the font color used for the right-hand column on recto pages by setting `footer-recto-right-font-color: 6CC644`. + +[#running-content] +== running-content + +The key in the `running-content` category controls on what page the running content starts. + +[cols="3,4,6a"] +|=== +|Key |Value Type |Example + +|`start-at` +|`title` {vbar} `toc` {vbar} `after-toc` {vbar} `body` {vbar} Integer + +(default: `body`) +| +[,yaml] +---- +running-content: + start-at: toc +---- +|=== + +* The `title`, `toc`, and `after-toc` values are only recognized if the title page is enabled (i.e., doctype is `book` or the `title-page` document attribute is set). +* The `toc` value only applies if the toc is in the default location (before the first page of the body). +If the value is `toc`, and the toc macro is used to position the Table of Contents, the `start-at` behavior is the same as if the TOC is not enabled. +* 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). + +IMPORTANT: If you don't specify a `height` for either the `header` or `footer` key, it effectively disables the content at that periphery. + +TIP: Although not listed in the table above, you can control the font settings (`font-family`, `font-size`, `font-color`, `font-style`, `text-transform`) that get applied to the running content in each column position for each page side (e.g., `footer-<side>-<position>-font-color`). +For example, you can set the font color used for the right-hand column on recto pages by setting `footer-recto-right-font-color: 6CC644`. + +[#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 `+©+`, 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: + +[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. |