### Install CodeRay Syntax Highlighter (gem command)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/syntax-highlighting.adoc

Use this command to install the coderay gem directly.

```bash
gem install coderay
```

--------------------------------

### Delimited Example Block

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-fits.adoc

A basic delimited example block. This is used for general content demonstration.

```asciidoc
====

Paragraph 1 in a delimited example block. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content.

Paragraph 2. This is content. End of example.
====
```

--------------------------------

### Install Rouge Syntax Highlighter (gem command)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/syntax-highlighting.adoc

Use this command to install the Rouge gem directly.

```bash
gem install rouge
```

--------------------------------

### Copy Example AsciiDoc File

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/README.adoc

Copy the `basic-example.adoc` file from the project's examples directory to the current directory for conversion.

```bash
cp examples/basic-example.adoc .
```

--------------------------------

### Build and Install Gem Locally

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Build the Asciidoctor PDF gem locally and then install it using the `gem install` command. This process involves cleaning the build directory, building the gem, and then installing the generated package.

```bash
rm -rf pkg
bundle exec rake build
gem install pkg/*.gem
```

--------------------------------

### Delimited Example Block with Anchor

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-fits.adoc

A delimited example block with an anchor for referencing. Includes a title and a list.

```asciidoc
[#below-example-with-anchor]
====
Paragraph 1 in a delimited example block. *Example, below top, fits, with anchor.*

.Title of list
* List item
** List item
*** List item
** List item
* List item
** List item
** Last list item of list 1

Paragraph 2. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. End of example.
====
```

--------------------------------

### Install Pygments.rb Syntax Highlighter (gem command)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/syntax-highlighting.adoc

Use this command to install the pygments.rb gem directly.

```bash
gem install pygments.rb
```

--------------------------------

### Install Bundler

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Install the Bundler gem if it is not already available. This is a prerequisite for managing project dependencies.

```bash
gem install bundler
```

--------------------------------

### Install Debian/Ubuntu Dependencies

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Installs necessary software for building and testing Asciidoctor PDF on Debian-based Linux distributions.

```bash
sudo apt-get install -y build-essential git ruby-dev ruby-bundler poppler-utils
```

--------------------------------

### Install RGhost Gem

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/optimize-pdf.adoc

Install the `rghost` gem to enable RGhost integration for PDF optimization. Use `gem install rghost` for direct installation or add `gem 'rghost'` to your Gemfile.

```ruby
gem install rghost
```

```ruby
gem 'rghost'
```

--------------------------------

### Configure Page Numbering Start

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/page.adoc

Set the `start-at` key in the `page.numbering` category to control where the 1-based page numbering begins. For example, setting it to `cover` will start numbering from the cover page.

```yaml
page:
  numbering:
    start-at: cover
```

--------------------------------

### Install Fedora Dependencies

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Installs necessary software for building and testing Asciidoctor PDF on Fedora-based Linux distributions.

```bash
sudo dnf group install -y "Development Tools"
  sudo dnf install -y redhat-rpm-config ruby-devel rubygem-bundler poppler-utils
```

--------------------------------

### Delimited Example Block with Anchor and Title

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-fits.adoc

A delimited example block featuring an anchor, a title, and a nested list.

```asciidoc
.Title of delimited example block with list
[#below-example-with-anchor-and-title]
====
Paragraph 1 in a delimited example block. *Example, below top, fits, with anchor and title.* This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content.

.Title of list
* List item
* List item
.. List item
... List item
* List item
* Last list item and end of example block
====
```

--------------------------------

### Set Example Block Background Color

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `background-color` key to set the background color of an example block. Accepts a color value.

```yaml
example:
  background-color: #FFFEF7
```

--------------------------------

### Verify asciidoctor-pdf Installation

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/README.adoc

Run this command to check if the `asciidoctor-pdf` script is installed and accessible. It should print the version of the project.

```bash
asciidoctor-pdf -v
```

--------------------------------

### Set Example Block Padding

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `padding` key to set the padding around the content of an example block. Accepts measurement values.

```yaml
example:
  padding: [5, 10, 5, 10]
```

--------------------------------

### Delimited Example Block with Title and Nested List

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-fits.adoc

Demonstrates a delimited example block with a title, a standard list, and a nested ordered list, including an anchor.

```asciidoc
.Title of delimited example block
====
Paragraph 1 in a delimited example block. #Example, below top, fits, with title.# This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content.

* List item
* List item
* List item
* Last list item of list 1

Paragraph 2 in a delimited example block. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content.

[#below-ordered-list-with-anchor-and-title-in-example]
.Title of list 2
. List item
.. List item
... List item
.. List item
... List item
... List item
.... List item
.... List item
..... Last list item of list 2

Paragraph 3 in a delimited example block. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. This is content. End of example.
====
```

--------------------------------

### Set Example Block Border Width

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `border-width` key to set the border width of an example block. Accepts a measurement value.

```yaml
example:
  border-width: 0.75
```

--------------------------------

### Long Code Listing Example

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/examples/edge-cases.adoc

Demonstrates a long code listing that can span multiple pages. No specific setup is required beyond including the listing.

```text
Line 1
Line 2
Line 3
Line 4
Line 5
Line 6
Line 7
Line 8
Line 9
Line 10
Line 11
Line 12
Line 13
Line 14
Line 15
Line 16
Line 17
Line 18
Line 19
Line 20
Line 21
Line 22
Line 23
Line 24
Line 25
Line 26
Line 27
Line 28
Line 29
Line 30
Line 31
Line 32
Line 33
Line 34
Line 35
Line 36
Line 37
Line 38
Line 39
Line 40
Line 41
Line 42
Line 43
Line 44
Line 45
Line 46
Line 47
Line 48
Line 49
Line 50
```

--------------------------------

### Configure and Run Bundler

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Configure Bundler to install project dependencies locally and then run Bundler. Ensure you are in the project directory to find the Gemfile.

```bash
bundle config --local path .bundle/gems
bundle
```

--------------------------------

### Install HexaPDF Gem

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/optimize-pdf.adoc

Install the hexapdf gem using either Bundler or the gem command. This is the first step to using HexaPDF for PDF optimization.

```bash
gem install hexapdf
```

--------------------------------

### Install Latest Prerelease of asciidoctor-pdf

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/README.adoc

Use the `--pre` flag to install the latest prerelease version of the asciidoctor-pdf gem from RubyGems.org.

```bash
gem install asciidoctor-pdf --pre
```

--------------------------------

### Install Prawn Gem

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/examples/chronicles-example.adoc

Use this command to install the Prawn gem, which is required for generating PDF documents in Ruby.

```bash
$ gem install prawn
```

--------------------------------

### Nested Example Block with Sidebar and Source

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-fits.adoc

An example block containing a nested sidebar, which in turn contains a source block with an anchor, title, syntax highlighting, and callouts.

```asciidoc
====
*Example, below top, fits, with nested blocks.* Delimited example block ends directly after nested sidebar ends.

.Title of delimited sidebar block
[#below-sidebar-with-anchor-and-title-nested-in-example-bare]
****
.Title of delimited source block with callouts
[source#below-source-nested-in-sidebar-nested-in-example-bare,javascript]
----
/** This is a delimited source block with an anchor, title, syntax highlighting, and callouts that's nested in a sidebar that's nested in an example. */

function createExtensionRegistry (Asciidoctor, callbacks) {
  const registry = Asciidoctor.Extensions.create()
  registry.includeProcessor(IncludeProcessor.$new(callbacks.onInclude))
  return registry
}

module.exports = createExtensionRegistry

/** End of source. */
----
<1> Source callout 1 content. Callout content. Callout content. Callout content. Callout content. Callout content. Callout content. Callout content. Callout content. End of source callout 1.
<2> Source callout 2 content. End of source callout 2.
<3> Source callout 3 content for the big disco WIN! Who loves disco? We love disco! *Who loves disco? We love disco!*  End of source callout 3.
****
====
```

--------------------------------

### Install Ruby with RVM

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/install.adoc

Install a specific version of Ruby (e.g., 3.1) using RVM, a Ruby version manager.

```bash
rvm install 3.1
```

--------------------------------

### Install CodeRay Syntax Highlighter (Bundler)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/syntax-highlighting.adoc

Add this line to your Gemfile to manage the coderay gem with Bundler.

```ruby
gem 'coderay'
```

--------------------------------

### Install Fedora Dependencies (without Bundler)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Installs Ruby gems and utilities for running Asciidoctor PDF tests on Fedora without using Bundler.

```bash
sudo dnf install -y ruby rubygem-asciidoctor rubygem-chunky_png rubygem-coderay rubygem-pdf-inspector \
  rubygem-prawn rubygem-prawn-icon rubygem-prawn-svg rubygem-prawn-table rubygem-prawn-templates \
  rubygem-rouge rubygem-rspec rubygem-treetop poppler-utils
```

--------------------------------

### Install Asciidoctor PDF Globally

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Install the Asciidoctor PDF application globally using the provided Rake task. This makes the `asciidoctor-pdf` executable available system-wide.

```bash
bundle exec rake install
```

--------------------------------

### Set Example Block Border Radius

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `border-radius` key to set the border radius of an example block. Accepts a measurement value.

```yaml
example:
  border-radius: 4
```

--------------------------------

### Set Example Block Border Color

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `border-color` key to set the border color of an example block. Accepts a color value.

```yaml
example:
  border-color: #191970
```

--------------------------------

### Set Example Block Font Kerning

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `font-kerning` key to control font kerning within an example block. Accepts 'none' or 'normal'.

```yaml
example:
  font-kerning: none
```

--------------------------------

### Set Example Block Border Style

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `border-style` key to set the border style of an example block. Accepts a border style value.

```yaml
example:
  border-style: dashed
```

--------------------------------

### Set Example Block Font Size

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `font-size` key to set the font size for text within an example block. Accepts a font size value.

```yaml
example:
  font-size: 13
```

--------------------------------

### Install Pygments.rb Syntax Highlighter (Bundler)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/syntax-highlighting.adoc

Add this line to your Gemfile to manage the pygments.rb gem with Bundler.

```ruby
gem 'pygments.rb'
```

--------------------------------

### Calculate Base Line Height

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example demonstrating how to calculate the base line height using theme variables.

```yaml
base:
  line-height: >
    $base-line-height-length /
    $base-font-size
```

--------------------------------

### Listing Block Example

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/examples/chronicles-example.adoc

This is an example of a listing block in Asciidoctor. Content within this block is rendered as <pre> text, preserving original formatting.

```text
This is an example of a listing block.
The content inside is rendered as <pre> text.
```

--------------------------------

### Install Rouge Syntax Highlighter (Bundler)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/syntax-highlighting.adoc

Add this line to your Gemfile to manage the Rouge gem with Bundler.

```ruby
gem 'rouge'
```

--------------------------------

### Set Example Block Font Color

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `font-color` key to set the font color within an example block. Accepts a color value.

```yaml
example:
  font-color: #262626
```

--------------------------------

### Set Example Block Font Style

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `font-style` key to set the font style for text within an example block. Accepts a font style value.

```yaml
example:
  font-style: italic
```

--------------------------------

### Set Example Block Text Transform

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `text-transform` key to apply text transformations within an example block. Accepts a text transform value.

```yaml
example:
  text-transform: uppercase
```

--------------------------------

### Nested Example Block with Admonition

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-fits.adoc

A delimited example block nested within another block, which itself contains an admonition. This demonstrates hierarchical block structures.

```asciidoc
====
This is a delimited example block nested in a sidebar.

TIP: *This is an admonition nested in an example block that's nested in a sidebar block*. The Sun rotates in the opposite direction to Earth, from west to east.
This may or may not affect the kitchen sink and the infinite loop every other odd week. End of nested admonition.

End of nested example.
====
```

--------------------------------

### Configure Syntax Highlighter Theme

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/index.adoc

Use the `rouge-style` attribute to configure the theme for the Rouge syntax highlighter. This example sets the theme to 'monokai'.

```bash
$ asciidoctor-pdf -a rouge-style=monokai basic-example.adoc
```

--------------------------------

### Enable Hyphens

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of enabling hyphens globally for text.

```yaml
base:
  hyphens: true
```

--------------------------------

### Set Example Block Font Family

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/example.adoc

Use the `font-family` key to set the font family for text within an example block. Accepts a font family name.

```yaml
example:
  font-family: M+ 1p
```

--------------------------------

### XML Tag Example

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/examples/chronicles-example.adoc

Demonstrates the structure of an XML tag for an author with an ID.

```xml
<author id="1">
  <personname>
    <firstname>Lazarus</firstname>
    <surname>het Draeke</surname>
  </personname>
</author>
```

--------------------------------

### Set Page Numbering Start with YAML Theme

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/page-numbers.adoc

Specify the starting page for integer page numbering using the `start-at` key within the `page-numbering` category in the theme.

```yaml
page:
  numbering:
    start-at: toc
```

--------------------------------

### Hello World Output

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/examples/edge-cases.adoc

A simple Ruby snippet that prints 'Hello, World!' to the console. This is often used for basic testing or as a starting point.

```ruby
puts "Hello, World!" <1>
<1> Prints "Hello, World!" to the console
```

```ruby
puts "Hello, World!" <1>
<1> Prints "Hello, World!" to the console
```

--------------------------------

### Theme Configuration for Print

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/print-and-prepress.adoc

Example of theme configuration for print-optimized colors and margins. Use `margin-inner` and `margin-outer` for double-sided pages.

```yaml
page:
  margin: [0.5in, 0.67in, 0.67in, 0.67in]
  margin-inner: 0.75in
  margin-outer: 0.59in
```

--------------------------------

### JavaScript Include Processor Setup

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-at-top-fits.adoc

Sets up an include processor for Asciidoctor extensions. This is typically used for custom include handling within AsciidoDoc documents.

```javascript
/** This is a delimited source block nested in a listing block. */

const IncludeProcessor = require('./include/include-processor')

function createExtensionRegistry (Asciidoctor, callbacks) {
const registry = Asciidoctor.Extensions.create()
registry.includeProcessor(IncludeProcessor.$new(callbacks.onInclude))
return registry
}

module.exports = createExtensionRegistry

/** End of nested source. Parent listing ends directly following closing delimiter.*/
```

--------------------------------

### Check Ruby Version

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/install.adoc

Verify that your Ruby installation meets the minimum required version (2.7 or greater).

```bash
$ ruby -v
```

--------------------------------

### Create a Theme from Scratch

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/create-theme.adoc

To create a theme from scratch, set the `extends` key to `~` or omit it entirely. Asciidoctor PDF will then not load any theme before your own, providing a barebones starting point.

```yaml
extends: ~
#...
```

--------------------------------

### Set Base Font Style

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base font style to 'bold'.

```yaml
base:
  font-style: bold
```

--------------------------------

### Nested Source Block with Callouts

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-at-top-does-not-fit.adoc

Demonstrates a JavaScript source block with callouts, nested within a sidebar and an example block. Use this for complex code examples requiring detailed explanations.

```javascript
/** This is a delimited source block with a title, syntax highlighting, and callouts that's nested in a sidebar that's nested in an example. */

function createExtensionRegistry (Asciidoctor, callbacks) {
  const registry = Asciidoctor.Extensions.create()
  registry.includeProcessor(IncludeProcessor.$new(callbacks.onInclude))
```

--------------------------------

### Run Asciidoctor PDF Command

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/convert-to-pdf.adoc

Verify the installation of Asciidoctor PDF by checking its version. This command confirms that the tool is accessible and ready for use.

```bash
$ asciidoctor-pdf -v
```

--------------------------------

### Build Documentation (Project Only Mode)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Configure and build the documentation for Asciidoctor PDF in isolation using Antora. This requires a local Antora playbook file.

```yaml
runtime:
  log:
    level: info
site:
  title: Asciidoctor Docs
  start_page: pdf-converter::index.adoc
content:
  sources:
  - url: .
    branches: HEAD
    start_paths: docs
asciidoc:
  attributes:
    experimental: ''
    idprefix: '@'
    idseparator: '-@'
    table-caption: false
    table-frame: 'none@'
    table-grid: 'rows@'
    example-caption: false
    listing-caption: false
    hide-uri-scheme: '@'
ui:
  bundle:
    url: https://github.com/asciidoctor/docs.asciidoctor.org-ui/releases/download/prod-309/ui-bundle.zip
```

--------------------------------

### Install Development Version with Bundler

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Update project gems using Bundler after modifying the Gemfile to point to a development branch. This command ensures the correct gem versions are installed locally.

```bash
rm -f Gemfile.lock
bundle config --local github.https true
bundle --path=.bundle/gems --binstubs=.bundle/.bin
```

--------------------------------

### Install Asciidoctor PDF Gem

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/README.adoc

Install the Asciidoctor PDF gem from RubyGems.org. This command also installs necessary dependencies like asciidoctor, prawn, and others.

```bash
gem install asciidoctor-pdf
```

--------------------------------

### Set Base Text Decoration

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base text decoration to underline.

```yaml
base:
  text-decoration: underline
```

--------------------------------

### Set Base Border Width

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base border width with a measurement unit.

```yaml
base:
  border-width: 0.6
```

--------------------------------

### Set Base Font Size

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base font size to a specific point size.

```yaml
base:
  font-size: 10.5
```

--------------------------------

### Set Base Text Alignment

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base text alignment to center.

```yaml
base:
  text-align: center
```

--------------------------------

### Build Full Site with Antora

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Build the complete Asciidoctor documentation site using the Antora build tool and the configured playbook. This command generates the static site in your browser.

```bash
npx antora antora-playbook.yml
```

--------------------------------

### Set Base Font Color

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base font color using a hex value.

```yaml
base:
  font-color: #333333
```

--------------------------------

### Set Base Text Decoration Width

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base text decoration width with a measurement unit.

```yaml
base:
  text-decoration-width: 0.5
```

--------------------------------

### Run Asciidoctor PDF Application

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Execute the `asciidoctor-pdf` script using Ruby and Bundler to verify the application is runnable. This command checks the installed version.

```bash
bundle exec asciidoctor-pdf -v
```

--------------------------------

### Golo Method Resolution Example

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/examples/chronicles-example.adoc

Demonstrates how Golo resolves a method call when a field with the same name exists in the class. It shows writing to the field and calling the method.

```golo
let foo = Foo()

foo: bar("baz") # <1>

println(foo: bar()) # <2>
```

--------------------------------

### Update Dependencies After Fetching PR

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Run the `bundle` command to install or update project dependencies after switching to a pull request branch. This ensures all necessary gems are available.

```bash
bundle
```

--------------------------------

### Check Ruby Version

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/README.adoc

Verify that a compatible Ruby runtime is installed. Asciidoctor PDF requires Ruby 2.7 or greater, or JRuby 9.2 or greater.

```bash
ruby -v
```

--------------------------------

### Install Text-Hyphen Gem for Automatic Hyphenation

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/README.adoc

Install the `text-hyphen` gem to enable automatic hyphenation in your PDF documents when using the `hyphens` attribute.

```bash
gem install text-hyphen
```

--------------------------------

### Activate Custom Optimizer via Command Line

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/optimize-pdf.adoc

Load a custom Ruby optimizer and set it as the PDF optimizer using command-line flags.

```bash
asciidoctor-pdf -r ./optimizer-hexapdf.rb -a optimize -a pdf-optimizer=hexapdf filename.adoc
```

--------------------------------

### Example Block Nested in Table Cell

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-fits.adoc

Demonstrates an example block nested within a table cell. This block contains text and a paragraph.

```asciidoc
|Table, below top, fits, with blocks in cells.
a|Check out this example.

====
Example block nested in a table cell. This is content. This is content. This is content. This is content. This is content. This is content. This is title content. This is content.

Paragraph in example block. This is content. This is content. This is content. This is content. End of example block.
====
```

--------------------------------

### JavaScript Extension Registry with Callouts

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-at-top-fits.adoc

Demonstrates setting up an Asciidoctor extension registry with an include processor, including an anchor, title, and source code callouts for detailed explanations.

```javascript
/** Source, at top, fits, with and anchor, title, and callouts. */

const IncludeProcessor = require('./include/include-processor')

/** This is content.
* This is content.
*/

function createExtensionRegistry (Asciidoctor, callbacks) { <1> 
  const registry = Asciidoctor.Extensions.create()
  registry.includeProcessor(IncludeProcessor.$new(callbacks.onInclude))
  return registry <2> 
}

/** This is content.
* This is content.
*/

module.exports = createExtensionRegistry <3> 

/** End of source. */
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Changes the current directory to the cloned Asciidoctor PDF project folder.

```bash
cd asciidoctor-pdf
```

--------------------------------

### Find Asciidoctor PDF Gem Location

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/install.adoc

After installing the asciidoctor-pdf gem, use this command to determine its installation path. The path should typically be within your RVM home directory.

```bash
gem which asciidoctor-pdf
```

--------------------------------

### Install prawn-gmagick Gem

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/image-paths-and-formats.adoc

Install the prawn-gmagick gem to enable Asciidoctor PDF to delegate image decoding to GraphicsMagick. This requires C Ruby and is supported on Linux and macOS.

```bash
$ gem install prawn-gmagick
```

--------------------------------

### Block Image Nested in Example Block

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-does-not-fit.adoc

Demonstrates a block image, placed below the top and not fitting, nested within an example block. The image size is controlled by pdfwidth.

```adoc
====
image::tall.svg[pdfwidth=120mm]
====
```

--------------------------------

### Change Directory to Parent

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Navigate to the parent directory. This is a prerequisite step before cloning related repositories.

```bash
cd ..
```

--------------------------------

### Masquerading Admonition with Nested List and Example

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-fits.adoc

An admonition block masquerading as a different type, containing nested lists and an example block. This showcases complex nesting within sidebars.

```asciidoc
[IMPORTANT#below-masqued-with-anchor-and-nested-in-sidebar]
====
Paragraph 1 in a *masquerading admonition block with an anchor and nested in a delimited sidebar block*.

* List item in nested masquerading admonition block.
** List item. This is content.
*** List item. This is content. This is content. This is content. This is content. This is content. This is content.
**** List item. This is content. This is content. This is content. This is content. This is content. This is content.
+
======
Paragraph 1 in a delimited example block attached to the previous list item with a list continuation. This is content. This is content. This is content. This is content. This is content. This is content.

Paragraph 2 in a delimited example block. This is content. This is content. This is content. End of nested delimited example block.
======
***** List item. This is content. This is content. This is content. This is content. This is content. This is content. End of list.

Paragraph 2 in a masquerading admonition block. This is content. This is content. This is content. This is content. This is content. This is content. End of nested masquerading admonition block.
====
```

--------------------------------

### Generate Basic PDF with Prawn

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/examples/chronicles-example.adoc

This Ruby code snippet demonstrates how to generate a simple PDF document named 'output.pdf' with the text 'Hello, World!' using the Prawn library.

```ruby
require 'prawn' # <1>

Prawn::Document.generate 'output.pdf' do # <3>
  text 'Hello, World!' # <2>
end
```

--------------------------------

### Run Antora with Local Playbook

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/CONTRIBUTING-CODE.adoc

Execute Antora using a local playbook file to build the documentation. This command is used for initial setup or when working with a specific playbook configuration.

```bash
npx antora local-antora-playbook.yml
```

--------------------------------

### Nested Source Block in Sidebar within Example

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-at-top-fits.adoc

This snippet shows a JavaScript source block with callouts nested within a sidebar, which is itself nested within an example block. It demonstrates how to define extensions for Asciidoctor.

```javascript
/** This is a delimited source block with a title, syntax highlighting, and callouts that's nested in a sidebar that's nested in an example. */

function createExtensionRegistry (Asciidoctor, callbacks) { 
  const registry = Asciidoctor.Extensions.create()
  registry.includeProcessor(IncludeProcessor.$new(callbacks.onInclude))
  return registry 
}

module.exports = createExtensionRegistry 

/** End of source. */

```

--------------------------------

### Nested Theme Keys (Level 1)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/language.adoc

Shows how to use nesting to organize base font properties, reducing redundancy.

```yaml
base:
  font-color: #333333
  font-family: Times-Roman
  font-size: 12
```

--------------------------------

### Advanced Inline Page Number Macro (Ruby)

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/extend/pages/use-cases.adoc

This macro displays the start page of the current section. It can also show the page number label by subtracting the start page number from the physical page number.

```ruby
require "asciidoctor"
require "asciidoctor/extensions"

Asciidoctor::Extensions.register do
  inline_macro do
    name :pagenum
    process do |node, _target, _attributes|
      if node.document.catalog[:start_page_numbers]
        start_page = node.document.catalog[:start_page_numbers][node.section.id]
        page_label = node.page_number - start_page + 1
        page_label.to_s
      else
        node.page_number.to_s
      end
    end
  end
end
```

--------------------------------

### Nested Literal Block with Callouts and Multiple Annotations

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-fits.adoc

A literal block nested within sidebar and example blocks, featuring multiple callouts and annotations. This example highlights how to annotate specific lines or sections of preformatted text.

```text
This is a delimited literal block with an anchor, title, and callouts that's nested in a sidebar that's nested in an example.

This is content. <1>
     This is content. <2>

End of literal.
....
```

--------------------------------

### Import First Page of PDF

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/import-pdf-pages.adoc

Use the image macro with the PDF filename as the target to import the first page. No manual page breaks are needed.

```asciidoc
image::custom-page.pdf[]
```

--------------------------------

### Enable Prepress Mode

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/print-and-prepress.adoc

Set the `media` document attribute to `prepress` to activate print mode features plus double-sided margins and automatic facing pages. Configure this in the document header or via the CLI.

```asciidoc
media=prepress
```

--------------------------------

### JavaScript Source Block Nested in Sidebar and Example Block

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-at-top-fits.adoc

This snippet demonstrates a JavaScript source code block with callouts, nested within a sidebar block, which is itself nested inside a larger example block. This illustrates complex content embedding within AsciiDoc structures.

```javascript
/** This is a delimited source block with an anchor, title, syntax highlighting, and callouts that's nested in a sidebar that's nested in an example. */

function createExtensionRegistry (Asciidoctor, callbacks) { <1>
  const registry = Asciidoctor.Extensions.create()
  registry.includeProcessor(IncludeProcessor.$new(callbacks.onInclude))
  return registry <2>
}
```

--------------------------------

### Load Theme with CLI Option

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/apply-theme.adoc

Use the `--theme` CLI option as a shorthand for the `pdf-theme` attribute. This is useful for quickly applying a theme without setting the attribute explicitly.

```bash
$ asciidoctor-pdf --theme basic -a pdf-themesdir=resources/themes -a pdf-fontsdir=resources/fonts doc.adoc
```

--------------------------------

### Specify Theme and Fonts Directory

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/apply-theme.adoc

Use the `--theme` and `-a pdf-fontsdir` options to specify the paths to your theme file and font directory. Absolute paths are used as is.

```bash
$ asciidoctor-pdf --theme /path/to/resources/themes/basic-theme.yml -a pdf-fontsdir=/path/to/resources/fonts doc.adoc
```

--------------------------------

### Set Base Font Kerning

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base font kerning to 'none'.

```yaml
base:
  font-kerning: none
```

--------------------------------

### Extend Base Theme with Custom Styling

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/create-theme.adoc

Create a theme that extends the base theme, providing rudimentary styling. This example customizes page layout, margins, font properties, roles, headings, links, and lists.

```yaml
extends: base
page:
  layout: portrait
  margin: [0.75in, 1in, 0.75in, 1in]
  size: Letter
base:
  font-color: #333333
  font-family: Times-Roman
  font-size: 12
  line-height-length: 17
  line-height: $base-line-height-length / $base-font-size
role:
  removed:
    font-style: italic
    text-decoration: line-through
    text-decoration-color: #FF0000
heading:
  font-color: #262626
  font-size: 17
  font-style: bold
  line-height: 1.2
  margin-bottom: 10
link:
  font-color: #002FA7
list:
  indent: $base-font-size * 1.5
```

--------------------------------

### Configure Front and Back Cover Images

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/covers.adoc

Use the `cover` category in your theme to specify front and back cover images. Image parameters like `page`, `fit`, `width`, and `position` can be set using the inline image macro syntax.

```yaml
cover:
  front:
    image: image:cover.pdf[page=2]
  back:
    image: image:splash.png[fit=fill]
```

--------------------------------

### Set Base Font Family

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base font family to a specific font name.

```yaml
base:
  font-family: Noto Serif
```

--------------------------------

### Load Theme with Attributes

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/apply-theme.adoc

Use `pdf-theme`, `pdf-themesdir`, and `pdf-fontsdir` attributes to specify the theme and font locations. The `pdf-theme` can be a name or file path, `pdf-themesdir` points to the theme directory, and `pdf-fontsdir` points to the font directory.

```bash
$ asciidoctor-pdf -a pdf-theme=basic -a pdf-themesdir=resources/themes -a pdf-fontsdir=resources/fonts doc.adoc
```

--------------------------------

### Set Base Border Color

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base border color using a hex value.

```yaml
base:
  border-color: #F0FFF0
```

--------------------------------

### Nested Source Block with Callouts

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-below-top-does-not-fit.adoc

This JavaScript code snippet demonstrates a function to create an extension registry. It includes callouts for specific lines.

```javascript
/** This is a delimited source block with a title, syntax highlighting, and callouts that's nested in a sidebar that's nested in an example. */

function createExtensionRegistry (Asciidoctor, callbacks) { <1>
  const registry = Asciidoctor.Extensions.create()
  registry.includeProcessor(IncludeProcessor.$new(callbacks.onInclude))
```

--------------------------------

### HexaPDF Optimize Options

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/optimize-pdf.adoc

View all available options for the `hexapdf optimize` command by running `hexapdf help optimize`.

```bash
$ hexapdf help optimize
```

--------------------------------

### Install Asciidoctor PDF with Bundler

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/install.adoc

Add this line to your Gemfile to include Asciidoctor PDF when using Bundler for gem management.

```ruby
gem 'asciidoctor-pdf'
```

--------------------------------

### Set Example Block Border Width with Two Values

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/blocks.adoc

Applies border widths using a two-value array. The first value sets the top and bottom borders, and the second sets the left and right borders.

```yaml
example:
  border-width: [0.5, 2]
```

--------------------------------

### Create a basic PDF document using Prawn

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/attachments/basic-example.adoc

Use this Ruby code to generate a simple PDF file with text content using the Prawn library. Ensure Prawn is installed.

```ruby
require 'prawn'

Prawn::Document.generate 'example.pdf' do
  text 'Hello, World!'
end
```

--------------------------------

### Set Base Text Decoration Color

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the base text decoration color using a hex value.

```yaml
base:
  text-decoration-color: #0000FF
```

--------------------------------

### Set Minimum Base Font Size

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/base.adoc

Example of setting the minimum base font size using a rem unit.

```yaml
base:
  font-size-min: 0.75rem
```

--------------------------------

### Combine Quality and Compliance Optimization

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/ROOT/pages/optimize-pdf.adoc

Separate quality and compliance keywords with a comma in the `optimize` attribute, with the quality keyword listed first.

```bash
$ asciidoctor-pdf -a optimize=prepress,PDF/A filename.adoc
```

--------------------------------

### Configure Back Cover Image

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/cover.adoc

Use the `back-image` key to specify the image for the back cover. The value can be an image macro or a path. The default is not set.

```yaml
cover:
  back:
    image: image:solid-cover.pdf[]
```

--------------------------------

### Sidebar Block with Nested Admonition

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-at-top-fits.adoc

This example demonstrates a sidebar block nested within a table cell, which itself contains a nested admonition block.

```asciidoc
.Title of delimited sidebar
****
This is a delimited sidebar block that spans two columns!

Paragraph in sidebar block. This is content. This is content. This is content. This is content. This is content.

[IMPORTANT]
====
This is a masquerading admonition block nested in a sidebar nested in a table cell that spans two columns.

This is content. This is content. This is content. This is content. This is content. End of masquerading admonition. End of sidebar directly following admonition closing delimiter.
====
****
```

--------------------------------

### Apply Bundled Rouge Theme

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/modules/theme/pages/source-highlighting-theme.adoc

Set the `source-highlighter` to `rouge` and `rouge-style` to the desired theme name in the document header.

```asciidoc
= Document Title
:source-highlighter: rouge
:rouge-style: monokai

```

--------------------------------

### HTML Article with Title

Source: https://github.com/asciidoctor/asciidoctor-pdf/blob/main/spec/fixtures/arrange-block-at-top-fits.adoc

A standard HTML article structure presented with a title. This block is a simple HTML example within an AsciiDoc document.

```html
<!-- Source, at top, fits, with title. -->

<article>
  <div>
    <main>

      <!-- This is awesome! -->

    </main>
  </div>
</article>

<!-- End of source. -->
```