= Jekyll Pages + Asciidoctor => PDF
:gem-name: rake_jekyll_asciidoctor_pdf
:gh-name: ggenzone/{gem-name}
:gh-branch: master
:badge-style: flat

image:https://img.shields.io/gem/v/{gem-name}.svg?style={badge-style}[Gem Version, link="https://rubygems.org/gems/{gem-name}"]

toc::[]

== Overview

The basic idea is to be able to generate PDFs files for each page in Jekyll, and also to generate one complete PDF with the whole site using the sidebar structure as starting point.

== Constraints

 * We assume that the original pages use **Asciidoc** with traditional front matter like this
 
[source,asciidoc]
----

---
layout: info
permalink: /sample/
---
= Sample Page
:url-asciidoctor: http://asciidoctor.org

This is a sample page composed in AsciiDoc.
Jekyll converts it to HTML using {url-asciidoctor}[Asciidoctor].

[source,ruby]
puts "Hello, World!"
----

 * Each page **must** have a permalink attribute in the front matter and **must** be unique.
 * The permalink will be used in the sidebar as foreign key of each page
 * The sidebar structure **should** be like this

 entries:
   - title: Chapter 1
     url: /chapter1.html
   - title: Chapter 2
     entries:
       - title: Section 1
         url: /chapter_2_section_1.html
       - title: Section 2
         url: /chapter_2_section_2.html
  ...
 

== Process
. Generate PDF files for each page
.. Copy all files and remove the front matter information
.. Execute **asciidoctor-pdf** in each new file

. Generate a fullsite.adoc using the sidebar.yml structure
.. Copy all files, remove front matter information and rename it with the permalink as name
.. Load sidebar.yml into a *tree* like structure
.. Generate the whole content using recursion over the *tree*
.. Execute **asciidoctor-pdf** in the new file


== Installation

Add this line to your application’s Gemfile:

  gem 'rake_jekyll_asciidoctor_pdf'

and then execute:

  $ bundle
  
== Tasks

=== BuildTask

This task builds the full

==== Usage

The most simple usage is

[source, ruby]
----
require 'rake_jekyll_asciidoctor_pdf'

RakeJekyllAsciidoctorPdf::BuildTask.new
----

This listing introduces all the configurable options with their default values:

[source, ruby]
----
require 'rake_jekyll_asciidoctor_pdf'

RakeJekyllAsciidoctorPdf::BuildTask.new(:build) do |t|

  # Description of the rake task.
  t.description = 'Generate PDFs files'
  t.config_pdf_file = 'pdf-theme.yml'
  t.sidebar_file = 'data/sidebar.yml'
  t.data_path = 'data'

end
----

== Example

 $ rake buildAll

Or

 $ rake SOURCE_PATH='<PATH_LIKE_DATA_EXAMPLE>'

If you want to use a diferent SOURCE_PATH you should know the structure of the data folder. 

 media
 sidebar.yml
 *.adoc


== 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 interal *links:*
 * Unicode characters are not supported by AsciiDocPdf (e.i. &check;)
 
[source,asciidoc]
----
//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
 * [x] 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
 * [x] Increase 1 level each time we combine a child in the sidebar