j1-template 2021.1.27 → 2021.2.1

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/200_themes.adoc

@@ -0,0 +1,61 @@
+---
+title:                                  Asciidoctor PDF Themes
+tagline:                                Theming Guide for the Asciidoctor PDF Converter
+description:                            Asciidoctor PDF Theming Guide
+
+categories:                             [ Knowledge ]
+tags:                                   [ Asciidoctor, PDF, Converter ]
+
+permalink:                              /pages/public/skeleton/documentation/200_themes/
+regenerate:                             false
+
+resources:                              [ lightbox, clipboard, rouge ]
+resource_options:
+  - toccer:
+      collapseDepth:                    2
+---
+
+// Page Initializer
+// =============================================================================
+// Enable the Liquid Preprocessor
+:page-liquid:
+
+// Set page (local) attributes here
+// -----------------------------------------------------------------------------
+// :page--attr:                         <attr-value>
+
+//  Load Liquid procedures
+// -----------------------------------------------------------------------------
+{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
+
+// Load page attributes
+// -----------------------------------------------------------------------------
+{% include {{load_attributes}} scope="all" %}
+
+
+// Page content
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+// Include sub-documents
+// -----------------------------------------------------------------------------
+
+//////////
+Topics remaining to document:
+* line height and line height length (and what that all means)
+* title page layout / title page images (logo & background)
+* document that unicode escape sequences can be used inside double-quoted strings
+//////////
+
+The theming system in *Asciidoctor PDF* is used to control the layout and styling
+of the PDF file *Asciidoctor PDF* generates from AsciiDoc. This document describes
+how the theming system works, how to define a custom theme in YAML and how to
+activate the theme when running *Asciidoctor PDF*.
+
+IMPORTANT: If you're using a custom theme, you're expected to bring your own
+fonts or declare the fonts from the default theme. If you don't declare your
+own fonts, the built-in PDF (afm) fonts will be used, which only support
+WINANSI characters (similar to Basic Latin).
+
+// Include documents
+// -------------------------------------------------------------------
+include::{documentdir}/200_themes.asciidoc[]

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/_includes/attributes.asciidoc

@@ -0,0 +1,95 @@
+// ~/document_base_folder/_includes
+//  Asciidoc attribute includes:                 attributes.asciidoc
+// -----------------------------------------------------------------------------
+
+// URLs - Internal references and/or sources on the Internet
+// -----------------------------------------------------------------------------
+tag::urls[]
+:uri-symfony-yaml-format-strings:                 https://symfony.com/doc/current/components/yaml/yaml_format.html#strings
+
+:uri-wikipedia-yaml:                              https://en.wikipedia.org/wiki/YAML
+:uri-wikipedia-codepage-windows-1252:             https://en.wikipedia.org/wiki/Windows-1252
+
+:uri-asciidoctor:                                 https://asciidoctor.org
+:uri-asciidoctor-extentions-catalog:              https://github.com/asciidoctor/asciidoctor-extensions-lab#extension-catalog
+:uri-asciidoctor-pdf:                             https://github.com/asciidoctor/asciidoctor-pdf
+:uri-asciidoctor-pdf-gem:                         https://rubygems.org/gems/asciidoctor-pdf
+:uri-asciidoctor-pdf-repo:                        {uri-asciidoctor-pdf}
+:uri-asciidoctor-pdf-issues:                      {uri-asciidoctor-pdf-repo}/issues
+:uri-asciidoctor-pdf-issues-1:                    {uri-asciidoctor-pdf}/issues/1
+:uri-asciidoctor-pdf-issues-95:                   {uri-asciidoctor-pdf}/issues/95
+:uri-asciidoctor-pdf-list:                        https://discuss.asciidoctor.org
+:uri-asciidoctor-pdf-base-theme:                  https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/base-theme.yml
+:uri-asciidoctor-pdf-default-theme:               https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml
+:uri-asciidoctor-mathematical:                    https://github.com/asciidoctor/asciidoctor-mathematical
+:uri-asciidoctor-pdf-cjk-kai_gen_gothic:          https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic
+:uri-asciidoctor-pdf-cjk:                         https://github.com/chloerei/asciidoctor-pdf-cjk
+:uri-asciidoctor-yaml-style-for-maven:            http://discuss.asciidoctor.org/Asciidoctor-YAML-style-file-for-PDF-and-maven-td3849.html
+:uri-asciidoctor-theme-example-for-maven:         https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoctor-pdf-with-theme-example
+:uri-asciidoctor-theme-example-for-gradle:        https://github.com/asciidoctor/asciidoctor-gradle-examples/tree/master/asciidoc-to-pdf-with-theme-example
+
+:uri-ghostscript-ps-pdf-marks:                    http://milan.kupcevic.net/ghostscript-ps-pdf/#marks
+
+:uri-prawn-home:                                  http://prawnpdf.org
+:uri-prawn-gmagick:                               https://github.com/packetmonkey/prawn-gmagick
+:uri-prawn-svg:                                   https://github.com/mogest/prawn-svg
+:uri-prawn-improved-handling-of-encodings:        https://github.com/prawnpdf/prawn/blob/master/CHANGELOG.md#vastly-improved-handling-of-encodings-for-pdf-built-in-afm-fonts
+:uri-prawn-lib-page-geometry:                     https://github.com/prawnpdf/pdf-core/blob/0.6.0/lib/pdf/core/page_geometry.rb#L16-L68[Named size]
+:uri-prawn-pdf-typesetting:                       http://www.sitepoint.com/hackable-pdf-typesetting-in-ruby-with-prawn
+
+:uri-rouge-home:                                  http://rouge.jneen.net/
+:uri-rouge-token:                                 https://github.com/jneen/rouge/blob/master/lib/rouge/token.rb
+:uri-rouge-themes:                                https://github.com/jneen/rouge/tree/master/lib/rouge/themes
+
+:uri-rvm:                                         https://rvm.io
+:uri-graphicsmagick:                              https://www.graphicsmagick.org
+:uri-google-groups-image-quality:                 https://groups.google.com/forum/#!msg/prawn-ruby/MbMsCx862iY/6ImCsvLGfVcJ[Discussion about image quality in PDFs]
+
+:uri-font-font-awesome:                           https://fortawesome.github.io/Font-Awesome/
+:uri-font-foundation-icon-fonts-3:                http://zurb.com/playground/foundation-icon-fonts-3
+:uri-font-paymentfont:                            http://paymentfont.io/
+:uri-font-octicons:                               https://octicons.github.com/
+:uri-font-prawn-icon:                             https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts
+
+:uri-font-roboto-ttf:                             https://github.com/google/roboto/tree/master/out/RobotoTTF
+:uri-font-droid-sans-fallback-ttf:                https://github.com/android/platform_frameworks_base/blob/master/data/fonts/DroidSansFallback.ttf
+:uri-font-noto-serif:                             https://www.google.com/get/noto/#/family/noto-serif
+:uri-font-m-plus-fonts:                           https://mplus-fonts.osdn.jp/about-en.html
+end::urls[]
+
+
+// FOOTNOTES, local asciidoc attributes (variables)
+// -----------------------------------------------------------------------------
+tag::footnotes[]
+end::footnotes[]
+
+
+// Tags - Asciidoc attributes used internally
+// -----------------------------------------------------------------------------
+tag::tags[]
+:images-dir:                                      pages/manuals/asciidoctor_pdf
+end::tags[]
+
+
+// Data - Data elements for Asciidoctor extensions
+// -----------------------------------------------------------------------------
+tag::data[]
+end::data[]
+
+
+// Images - Images from local include/images folder
+// -----------------------------------------------------------------------------
+tag::images[]
+end::images[]
+
+
+// PRODUCTS, local product information (e.g. release)
+// -----------------------------------------------------------------------------
+tag::products[]
+end::products[]
+
+
+// AUTHORS, local author information (e.g. article)
+// -----------------------------------------------------------------------------
+tag::authors[]
+end::authors[]

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/_includes/documents/000_intro.asciidoc

@@ -0,0 +1,54 @@
+// ~/document_base_folder/000_includes/documents
+// Intro document: 000_intro.asciidoc
+// -----------------------------------------------------------------------------
+
+== Introduction
+
+The skeleton of type *documentation* (book) can be used to create HTML output
+(backend *html5*) for websites and *PDF* output (backend *pdf*) for offline
+reading as well. _J1 Template_ comes with the full support of _Asciidoctor PDF_,
+a Ruby-based add-on for _Asciidoctor_ using the Ruby PDF writer _Prawn_.
+
+[IMPORTANT]
+====
+If you have plans to convert documents of type type documentation (book)
+into PDF, make sure you have enabled the Ruby *Gem* `asciidoctor-pdf` with
+your projects's Gemfile. To make the converter usable, the plugin has to be
+enabled with your site config file `_config.yml` in section
+*PLUGIN configuration* as well.
+====
+
+Prawn is a pure Ruby PDF generation library that provides a lot of great
+functionality while trying to remain simple by providing a reasonable
+performance.
+
+Some of the important features of the *PDF* writer _Prawn_ are:
+
+* Vector drawing support, including lines, polygons, curves,
+  ellipses, etc.
+* Extensive text rendering support, including flowing text
+  nd limited inline formatting options.
+* Support for both PDF builtin fonts as well as embedded TrueType
+  fonts
+* A variety of low level tools for basic layout needs, including a
+  simple grid system
+* PNG and JPG image embedding, with flexible scaling options
+* Security features including encryption and password protection
+* Tools for rendering repeatable content (i.e headers, footers, and
+  page numbers)
+* Comprehensive internationalization features, including full support
+  for UTF-8 based fonts, right-to-left text rendering, fallback font support,
+  and extension points for customizable text wrapping.
+* Support for PDF outlines for document navigation
+
+[NOTE]
+====
+.Converting the Skeleton
+
+The Asciidoc skeleton *documentation* (book) is fully *relocateable* and can
+be placed in any subfolder of your Jekyll site for *HTML* output. For *PDF*
+output, a single variable `BASE_PATH` has to be set for your environment.
+
+See the *batch* files `a2p.bat` for _Windows_ (`cmd.exe`) or `a2p.sh` used
+on _Unix_ or _Linux_ OS for the shell (bash).
+====

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/_includes/documents/100_converter/000_basic_example.asciidoc

@@ -0,0 +1,31 @@
+= Document Title
+Doc Writer <doc@example.com>
+:doctype: book
+:reproducible:
+//:source-highlighter: coderay
+:source-highlighter: rouge
+:listing-caption: Listing
+// Uncomment next line to set page size (default is A4)
+//:pdf-page-size: Letter
+
+A simple http://asciidoc.org[AsciiDoc] document.
+
+== Introduction
+
+A paragraph followed by a simple list with square bullets.
+
+[square]
+* item 1
+* item 2
+
+Here's how you say "`Hello, World!`" in Prawn:
+
+.Create a basic PDF document using Prawn
+[source,ruby]
+----
+require 'prawn'
+
+Prawn::Document.generate 'example.pdf' do
+  text 'Hello, World!'
+end
+----

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/_includes/documents/100_converter/111_about_the_converter.asciidoc

@@ -0,0 +1,111 @@
+== About the PDF-Generator Prawn
+
+{uri-asciidoctor-pdf}[Asciidoctor PDF, {browser-window--new}] is made possible by an amazing
+Ruby gem named _Prawn_. And what a gem it is! {uri-prawn-home}[Prawn, {browser-window--new}] is a
+nimble PDF writer for _Ruby_. More important, it's a hackable platform that offers
+both high level APIs for the most common needs and low level APIs for bending
+the document model to accommodate special circumstances.
+
+[caption=Status]
+CAUTION: _Asciidoctor PDF_ is currently _alpha_ software. While the converter
+handles most AsciiDoc content, there's still work needed to fill in gaps
+where conversion is incomplete, incorrect or not implemented. See the
+milestone v1.5.0 in the {uri-asciidoctor-pdf-issues}[Issue tracker, {browser-window--new}]
+for details.
+
+With _Prawn_, you can write text, draw lines and shapes and place images
+_anywhere_ on the page and add as much color as you like. In addition, it
+brings a fluent API and aggressive code re-use to the printable document space.
+
+Here's an example that demonstrates how to use _Prawn_ to create a basic PDF
+document.
+
+.Create a basic PDF document using _Prawn_
+[source,ruby]
+----
+require 'prawn'
+
+Prawn::Document.generate 'output.pdf' do
+  text 'Hello, PDF creation!'
+end
+----
+
+It's that easy.
+And that's just the beginning.
+
+_Prawn_ is the _killer library_ for PDF generation we've needed to close this
+critical gap in _Asciidoctor_. It absolutely takes the pain out of creating
+printable documents. Picking up from there, _Asciidoctor PDF_ takes the pain out
+ of creating PDF documents _from AsciiDoc_.
+
+=== Highlights
+
+* Direct AsciiDoc to PDF conversion
+* SVG support
+* PDF document outline (i.e., bookmarks)
+* Table of contents page(s)
+* Document metadata (title, authors, subject, keywords, etc)
+* Internal cross reference links
+* Syntax highlighting with Rouge, Pygments, or CodeRay
+* Page numbering
+* Customizable running content (header and footer)
+* “Keep together” blocks (i.e., page breaks avoided in certain block content)
+* Orphaned section titles avoided
+* Autofit verbatim blocks (as permitted by base_font_size_min setting)
+* Table border settings honored
+* Font-based icons
+* Custom (TTF) fonts
+* Double-sided printing mode (margins alternate on recto and verso pages)
+
+=== Prerequisites
+
+All that's needed is _Ruby_ (1.9.3 or above; 2.3.x recommended) and a few _Ruby_
+gems, which we explain how to install in the next section.
+
+To check if you have _Ruby_ available, use the `ruby` command to query the
+version installed:
+
+ $ ruby --version
+
+[WARNING]
+====
+By default, _Asciidoctor PDF_ automatically installs the latest version of _Prawn_
+if you don't already have _Prawn_ installed. This will fail on older versions of
+_Ruby_. To workaround, you need to install certain dependencies first.
+
+Starting with _Prawn_ 2.0.0, _Prawn_ requires Ruby >= 2.0.0 during installation.
+Therefore, to use _Asciidoctor PDF_ with Ruby 1.9.3, you must first explicitly
+install the following dependencies to lock the versions:
+
+ $ gem install prawn --version 1.3.0
+   gem install addressable --version 2.4.0
+   gem install prawn-svg --version 0.21.0
+   gem install prawn-templates --version 0.0.3
+
+You can then proceed with installation of _Asciidoctor PDF_ on Ruby 1.9.3.
+
+Starting with _Prawn_ 2.2.0, _Prawn_ requires Ruby >= 2.1.0 during installation.
+Therefore, to use _Asciidoctor PDF_ with Ruby 2.0.0, you must first explicitly
+install the following dependencies to lock the versions:
+
+ $ gem install prawn --version 2.1.0
+   gem install prawn-svg --version 0.26.0
+   gem install prawn-templates --version 0.0.4
+
+For all other versions of _Ruby_, you can simply install the _Asciidoctor PDF_ gem.
+It will transitively install the required dependencies.
+====
+
+==== System Encoding
+
+_Asciidoctor_ assumes you're using UTF-8 encoding. To minimize encoding problems,
+make sure the default encoding of your system is set to UTF-8.
+
+If you're using a non-English Windows environment, the default encoding of your
+system may not be UTF-8. As a result, you may get an `Encoding::UndefinedConversionError`
+or other encoding issues when invoking _Asciidoctor_. To solve these problems, we
+recommend at least changing the active code page in your console to UTF-8.
+
+ chcp 65001
+
+Once you make this change, all your Unicode headaches will be behind you.

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/_includes/documents/100_converter/112_getting_started.asciidoc

@@ -0,0 +1,95 @@
+== Getting Started
+
+You can get _Asciidoctor PDF_ by installing the published gem or running th
+ code from source.
+
+=== Install the Published Gem
+
+_Asciidoctor PDF_ is published as a pre-release on RubyGems.org.
+First, make sure you have satisfied the prerequisites.
+Then, you can install the published gem using the following command:
+
+ $ gem install asciidoctor-pdf --pre
+
+If you want to syntax highlight source listings, you'll also want to install
+Rouge, Pygments, or CodeRay. Choose one (or more) of the following:
+
+.Rouge (preferred)
+ $ gem install rouge
+
+.Pygments
+ $ gem install pygments.rb
+
+.CodeRay
+ $ gem install coderay
+
+You then activate syntax highlighting for a given document by adding the
+`source-highlighter` attribute to the document header (Rouge shown):
+
+[source,asciidoc]
+----
+:source-highlighter: rouge
+----
+
+Assuming all the required gems install properly, verify you can run the
+`asciidoctor-pdf` script:
+
+ $ asciidoctor-pdf -v
+
+If you see the version of _Asciidoctor PDF_ printed, you're ready to use
+_Asciidoctor PDF_.
+
+Let's grab an AsciiDoc document to distill and start putting _Asciidoctor PDF_
+to use!
+
+=== An Example AsciiDoc Document
+
+If you don't already have an AsciiDoc document, you can use the
+*basic_example.adoc* file found in the examples directory of this
+project.
+
+ifeval::[{safe-mode-level} < 20]
+.000_basic_example.adoc
+[source,asciidoc]
+....
+include::000_basic_example.asciidoc[]
+....
+endif::[]
+
+It's time to convert the AsciiDoc document directly to PDF.
+
+=== Convert AsciiDoc to PDF
+
+IMPORTANT: You'll need the `rouge` gem installed to run this example since
+it uses the `source-highlighter` attribute with the value of `rouge`.
+
+Converting to PDF is a simple as running the `asciidoctor-pdf` script using
+_Ruby_ and passing our AsciiDoc document as the first argument.
+
+ $ asciidoctor-pdf 000_basic_example.adoc
+
+This command is just a shorthand way of running:
+
+ $ asciidoctor -r asciidoctor-pdf -b pdf 000_basic_example.adoc
+
+The `asciidoctor-pdf` command just saves you from having to remember all those
+flags. That's why we created it.
+
+When the script completes, you should see the file *000_basic_example.pdf*
+in the same directory. Open the *000_basic_example.pdf* file with a PDF
+viewer to see the result.
+
+ifdef::backend-html5[]
+.Example PDF document rendered in a PDF viewer
+image::/assets/images/pages/asciidoc_skeletons/example-pdf-screenshot.png[Screenshot of PDF document,width=800,scaledwidth=100%]
+endif::[]
+
+ifdef::backend-pdf[]
+.Example PDF document rendered in a PDF viewer
+image::/assets/images/pages/asciidoc_skeletons/example-pdf-screenshot.png[Screenshot of PDF document,width=800,scaledwidth=100%]
+endif::[]
+
+You're also encouraged to try converting the documents in the examples
+directory to see more of what _Asciidoctor PDF_ can do.
+
+The pain of the DocBook toolchain should be melting away about now.

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/_includes/documents/100_converter/113_themes.asciidoc

@@ -0,0 +1,39 @@
+== Themes
+
+The layout and styling of the PDF is driven by a YAML configuration file. To
+learn how the theming system works and how to create and apply custom themes,
+refer to the _Asciidoctor PDF_ Theme Guide. You can use
+the built-in theme files, which you can find in the *data/themes* directory,
+as examples.
+
+=== Support for Non-Latin Languages
+
+_Asciidoctor_ can process the full range of characters in the UTF-8 character
+set. That means you can write your document in any language, save the file
+with UTF-8 encoding, and expect _Asciidoctor_ to convert the text properly.
+However, you may notice that certain characters for certain languages, such
+as Chinese, are missing in the PDF. Read on to find out why and how to
+address it.
+
+If you're writing in a non-Latin language, you need to use a dedicated theme
+that provides the necessary fonts. For example, to produce a PDF from a
+document written in a CJK language such as Chinese, you need to use a CJK
+theme. You can get such a theme by installing the `asciidoctor-pdf-cjk-kai_gen_gothic`
+gem. See the {uri-asciidoctor-pdf-cjk-kai_gen_gothic}[asciidoctor-pdf-cjk-kai_gen_gothic, {browser-window--new}]
+project for detailed instructions.
+
+Using a dedicated theme is necessary because PDF is a "`bring your own font`"
+kind of system. In other words, the font you provide must provide glyphs for
+all the characters. There's no one font that supports all the worlds languages
+(though some, like Noto Serif, certainly come close). Even if there were such
+a font, bundling that font with the main gem would make the package enormous.
+It would also severely limit the style choices in the default theme, which
+targets Latin-based languages.
+
+Therefore, we're taking the strategy of creating separate dedicated theme
+gems that target each language family, such as CJK. The base theme for CJK
+languages is provided by the {uri-asciidoctor-pdf-cjk}[asciidoctro-pdf-cjk, {browser-window--new}]
+project and a concrete implementation provided by the
+{uri-asciidoctor-pdf-cjk-kai_gen_gothic}[asciidoctor-pdf-cjk-kai_gen_gothic, {browser-window--new}]
+project that's based on the kai_gen_gothic font. Of course, you're free to
+follow this model and create your own theme gem that uses fonts of your choice.

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/_includes/documents/100_converter.asciidoc

@@ -0,0 +1,8 @@
+// Include documents
+// -------------------------------------------------------------------
+
+include::100_converter/111_about_the_converter.asciidoc[]
+
+include::100_converter/112_getting_started.asciidoc[]
+
+include::100_converter/113_themes.asciidoc[]

data/lib/starter_web/pages/public/asciidoc_skeletons/documentation/_includes/documents/200_themes/211_language_overview.asciidoc

@@ -0,0 +1,122 @@
+== Language Overview
+
+The theme language in *Asciidoctor PDF* is based on the {uri-wikipedia-yaml}[YAML, {browser-window--new}]
+data format and incorporates many concepts from CSS and SASS. Therefore, if you
+have a background in web design, the theme language should be immediately
+familiar to you.
+
+Like CSS, themes have both selectors and properties. Selectors are the component
+you want to style. The properties are the style elements of that component that
+can be styled. All selector names are implicit (e.g., `heading`), so you
+customize the theme primarily by manipulating pre-defined property values
+(e.g., `font_size`).
+
+[NOTE]
+====
+The theme language in *Asciidoctor PDF* supports a limited subset of the
+properties from CSS. Some of these properties have different names from
+those found in CSS.
+
+* Underscores (`_`) can be used in place of hyphens (`-`) for all property names in the theme language.
+* Instead of separate properties for font weight and font style, the theme language combines these settings in the `font_style` property (allowed values: `normal`, `bold`, `italic` and `bold_italic`).
+* The `text_align` property from CSS is the `align` property in the theme language.
+* The `color` property from CSS is the `font_color` property in the theme language.
+====
+
+A theme (or style) is described in a YAML-based data format and stored in a
+dedicated theme file. YAML is a human-friendly data format that resembles CSS
+and helps to describe the theme. The theme language adds some extra features
+to YAML, such as variables, basic math, measurements and color values. These
+enhancements will be explained in detail in later sections.
+
+The theme file must be named _<name>-theme.yml_, where `<name>` is the name
+of the theme. Here's an example of a basic theme file:
+
+.basic-theme.yml
+[source,yaml]
+----
+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
+vertical_spacing: $base_line_height_length
+heading:
+  font_color: #262626
+  font_size: 17
+  font_style: bold
+  line_height: 1.2
+  margin_bottom: $vertical_spacing
+link:
+  font_color: #002FA7
+outline_list:
+  indent: $base_font_size * 1.5
+----
+
+When creating a new theme, you only have to define the keys you want to
+override from the base theme, which is loaded prior to loading your custom
+theme. All the available keys are documented in section *Keys*. The converter
+uses the information from the theme map to help construct the PDF.
+
+[TIP]
+====
+Instead of creating a theme from scratch, another option is to download the
+{uri-asciidoctor-pdf-default-theme}[default-theme.yml, {browser-window--new}] file from the source
+repository. Save the file using a unique name (e.g. _custom-theme.yml_) and
+start hacking on it.
+
+Alternatively, you can snag the file from your local installation using the
+following command:
+
+ $ ASCIIDOCTOR_PDF_DIR=`gem contents asciidoctor-pdf --show-install-dir`;\
+   cp "$ASCIIDOCTOR_PDF_DIR/data/themes/default-theme.yml" custom-theme.yml
+====
+
+Keys may be nested to an arbitrary depth to eliminate redundant prefixes (an
+approach inspired by SASS). Once the theme is loaded, all keys are flattened
+into a single map of qualified keys. Nesting is simply a shorthand way of
+organizing the keys. In the end, a theme is just a map of key/value pairs.
+
+Nested keys are adjoined to their parent key with an underscore (`_`).
+This means the selector part (e.g., `link`) is combined with the property
+name (e.g., `font_color`) into a single, qualified key (e.g., `link_font_color`).
+
+For example, let's assume we want to set the base (i.e., global) font size
+and color. These keys may be written longhand:
+
+[source,yaml]
+----
+base_font_color: #333333
+base_font_family: Times-Roman
+base_font_size: 12
+----
+
+Or, to avoid having to type the prefix `base_` multiple times, the keys may
+be written hierarchically:
+
+[source,yaml]
+----
+base:
+  font_color: #333333
+  font_family: Times-Roman
+  font_size: 12
+----
+
+Or even:
+
+[source,yaml]
+----
+base:
+  font:
+    color: #333333
+    family: Times-Roman
+    size: 12
+----
+
+Each level of nesting must be indented by two more spaces of indentation than
+the parent level. Also note the presence of the colon after each key name.