Where It All Started.

Where It All Started.

Life, Stock Trading, Investments, Business and Startup. Most are programming stuff.

Tag: publisher

Beautifully Design PDF Using CSS3 and AsciiDoctor

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

— Eleanor Roosevelt.

Planning to create 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 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 on 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 well 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 in order 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 are no good 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 your probably 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 your 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 finish as we need to generate 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 whole process of minification inside the build-stylesheet script. As a side note, always study all the command before executing it on your own workstation.

Now this 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, that 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.

If you haven’t subscribe yet… Check out the companion YouTube channel Where It All Started. Also don’t forget to click subscribe and tick the notification bell.

Automating HTML5 Generation With AsciiDoctor

If you’re a documentation nerd or somewhat planning to create content for publishing, surely you will encounter ASCII Doc. ASCII Doc is being use by different publishing giants like O’Reilly to create books and content.

One problem I encountered is generating HTML documents from asciidoc format. So how do I automate it?

Better to die fighting for freedom then be a prisoner all the days of your life.

— Bob Marley.

Prerequisites

  • Ruby 2.5 and above

So how do we render HTML5 from ASCII Doc?

We proceed by getting all the required gems. The first step is get the file watcher to watch for changes.

gem install asciidoctor guard guard-shell guard-livereload yajl-ruby

The livereload gem watch changes in the file system. Also, you may need to install companion browser extension.

After the installation of Chrome Extension, you need to check “Allow access to file URLs” checkbox in More Tools > Extensions > Live Reload Details in order for it to work with local file URLs.

Then we create a Guardfile with the contents below.

require "asciidoctor"
guard "shell" do
	watch(/^solidity\.adoc$/) {|m|
		Asciidoctor.convert_file m[0]
	}
end
guard "livereload" do
	watch(%r{^.+\.(css|js|html)$})
end

The first guard block converts file to HTML5. Then after that the second guard block watches for file changes and reloads browser.

When all is done start the guard process to monitor and serve files.

guard start

That’s it guys we created our workflow for generating HTML5 using the asciidoctor format. Hit like if you like, subs if you love and as always live life. Hope you guys, enjoyed this article!