This gem allows you to generate PDFs from your Asciidoctor files.

To simplify installation, JekyllAsciidoctorPDF is packaged and distributed as a RubyGem (aka gem) to RubyGems.org.

Bundler

1. Open your Gemfile in the root folder of your Jekyll project

2. Add the jekyll_asciidoctor_pdf gem to your Gemfile as follows:

   source 'https://rubygems.org'
   gem 'jekyll_asciidoctor_pdf'
   
   # or specify the version explicitly
   # gem 'jekyll_asciidoctor_pdf', '0.3.0'

3. Save the Gemfile

4. Open a terminal and install the gem using:

   $ bundle

Rakefile

1. Open your Rakefile in the root folder of your Jekyll project

2. Add following lines

require 'rake_jekyll_asciidoctor_pdf'

RakeJekyllAsciidoctorPdf::BuildTask.new('buildAll') do |t|
  t.jekyll_config_file = '_config.yml'
  t.product_name = ENV['PRODUCT_NAME']
  t.repo_name = ENV['REPO_NAME']
  t.git_token = ENV['GH_API_TOKEN']
end

1. Save the Rakefile

Jekyll Configuration

1. Open your _config.yml in the root folder of your Jekyll project

2. Add following lines

jap_config:
    sidebar_path: '_data/sidebars/'
    output_path: 'pdfs'
    source_path: '.'
    exclude_list: []
    fullsite:
        subtitle: "Subtitle"
        authors: "Author1, Author2"
        revision: "Revision Date"
        background_image: 'cover_page_background.jpg'
    pdf_theme:
        extends: default

Note	This configuration assume an specific directory structure

Directory Structure

A basic directory structure usually looks something like this:

.
├── _config.yml
├── _data
│   └── sidebar.yml
├── media
│   └── assets files
├── pdfs # this folder will be created by rake_jekyll_asciidoctor_pdf
│   ├── pages/
│   └── fullsite/
└── *.adoc # all asciidoc files are in the root level

A complex directory structure could be like this

.
├── _config.yml
├── _data
│   ├── sidebar1
│   │ ...
│   └── sidebarN.yml
├── sidebar1_source
│   ├── media
│   ├── *.adoc # all asciidoc files are in the root level
|   ...
├── sidebarN_source
│   ├── media
│   ├── *.adoc # all asciidoc files are in the root level
└── pdfs # this folder will be created by rake_jekyll_asciidoctor_pdf
    ├── pages/
    ├── sidebar1/
    ├── ...
    ├── sidebarN/
    └── fullsite/

Usage

$ bundle exec rake buildAll

Known Limitations

• Mp4 is not supported

• Gif files need prawn-gmagick

• Absolute URL not supported in the sidebar.yml

• Problems with image labels like that

• Problems with internal links:

• Unicode characters are not supported by AsciiDocPdf (e.i. ✓)

//image:diagram_networking_cloud.png[service, a] not working, shoud be like this
image:diagram_networking_cloud.png["service, a"]

ToDo List

• ✓ Remove front matter from original files

• ✓ Generate a combined file with each item in the sidebar.yml

• ✓ Allow to customize PDF using a theme of AsciiDoctor-PDF

• ❏ Remove header attribuites in the original files

• ✓ Increase 1 level each time we combine a child in the sidebar

• ✓ Generate a PDF for each section

• ❏ Support multiple sidebar.yml like HCI (Partial)

• ✓ Support basic recursion over directories

• ✓ Add Copyright page

• ✓ Support remote authors information with GitHub API