Beautifully Design PDF Using CSS3 and ASCII Doctor

The future belongs to those who believe in the beauty of their dreams.
— Eleanor Roosevelt.

Planning to create an e-book but don’t know what tools you’ll be using?

In this day of age, no one will stop you building your own e-book, not even a publishing house. With the increasing tool set that will make publishing easy, you can now with open-source tools.

In this article we will be discussing how to make a beautifully designed PDF using CSS3 and ASCII Doctor. So how do we do that?

Creating the Workflow

After searching through all the internet, we found multiple clues on how big publishing house produces ebooks using AsciiDoctor and HTML5. Unfortunately, most of them are using proprietary tools like PrinceXML and Antenna House to create beautiful and professionally design PDF outputs. But don’t lose hope, as we got you covered in this how to.

First, you may need to setup your workstation to produce beautiful rich PDF. You need of course asciidoctor.

gem install asciidoctor

After asciidoctor you need to install weasyprint.

pip install weasyprint

If you’re curious why I would pick weasyprint, it’s because there is no useful tool set in ruby. Most of the HTML5 to PDF in ruby gems relies on wkhtmltopdf binary, not including prawn which relies purely on hard-coded design which you're not that familiar with compared to CSS3.

Now it’s time to get your hands dirty, create a simple ASCII Doctor document:

:doctype: book
:author: Some Author
:doctitle: Some Title
:description: Some Description
:keywords: some keywords
:toc:
:toclevels: 2
:sectnumlevels: 2
:icons: font
:icon-set: fa
:stem:
:hide-uri-scheme:
:source-highlighter: pygments
:pygments-style: xcode
:imagesdir: assets/images
:chapter-label: Chapter
:appendix-caption: Appendix
:creator: {author}
:uuid: e9a22dcf-2d0a-4237-addd-527fb847d816
:front-cover-image: image:cover.png[cover,1050,1600]
:title-logo-image: image:logo.svg[pdfwidth=4.25in,align=center]
:copyright: (c) {docyear} Some Press
:lang: en
:sourcedir: {docdir}/samples/code
:datadir: {docdir}/samples/data
:nofooter:
ifdef::backend-html5[]
:data-uri:
:stylesdir: {docdir}/assets/styles/html/themes
:stylesheet: asciidoctor.css
:linkcss:
:mathematical-format: svg
:mathematical-ppi: 300
endif::[]

= {doctitle}

// And more...

As you can see in line 39-40 the word stylesdir and stylesheets which you need to create and modify. This stylesdir will be the path on which you will be storing your custom CSS3 stylesheet.

Assuming you're working in the root directory of your ASCII Doc project. Create a themes folder on which will hold your CSS files. After that clone the asciidoctor-stylesheet-factory repository on which you’ll be spending time to customize the design of your PDF.

mkdir -p $PWD/assets/vendor
git clone https://github.com/asciidoctor/asciidoctor-stylesheet-factory $PWD/assets/vendor/asciidoctor-stylesheet-factory

Then change the stylesdir in your asciidoc document to point to /assets/vendor/asciidoctor-stylesheet-factory/stylesheets. It’s not yet finished as we need to generate the required CSS files.

cd $PWD/assets/vendor/asciidoctor-stylesheet-factory
bundle install
npm install cssshrinkwrap
./build-stylesheets.sh

The commands above if deconstructed would be.

1. Change directory to the cloned repository path.
2. Install all the gems required by the repository.
3. Install node dependency to minify the CSS needed in build-styleheet script.

Alternatively, you could run compass compile which skips the entire process of minification inside the build-stylesheet script. As a side note, always study all the commands before executing them on your own workstation.

Now this is where the fun begins, modify the theme (SASS file) you want to use inside the repository that we cloned. Compile the file and generate your PDF.

asciidoctor --backend=html5 -a max-width=55em --out-file=sample.html my-sample.adoc
weasyprint sample.html sample.pdf

What this will do is create an HTML5 compatible document from asciidoc source. Then from the sample.html generated from last command, use it to generate PDF file.

Voila! A generated PDF with CSS design.

So, here’s a recap of what you’ve learned so far.

• Get to know the tools needed to create a beautifully designed PDF.
• Modify stylesheets intended to create PDFs.
• Generate HTML5 from asciidoc source.
• Create PDF from HTML5.

Also, I’d recommend this book if you want to learn more about CSS3.

Where to go now?

Now, you know how to style and generate PDF with CSS + HTML5. On next chapter we will go in depth on how to make an e-book. Stay tuned.