Asbath's Arena

Pillar Quick Start

You just want to generate your book in HTML, you know Pillar already, this tutorial is for you.

Some features:

  • Table of contents: With the new book archetype, a document generated in Html has a table of contents allowing users to generate which is a resume of titles present in the document.
  • Template per file: Now when writing a book or website with Pillar, we have the possibility to specify for each file a different template. We use this feature to have different presentations on our websites.

Quick Install

All the new features (new archetypes, architecture, book testing) are on branch dev-7 

#for SSH cloning
$ git clone git@github.com:pillar-markup/pillar.git -b dev-7
#for HTTPS cloning
$ git clone https://github.com/pillar-markup/pillar.git -b dev-7
$ cd pillar
$ ./scripts/build.sh
$ cd ..
$ mv pillar ~/.pillar
# update path in your .bashrc or .zshrc
$ export PILLAR_HOME="$HOME/.pillar/build"
$ export PATH="$PATH:$PILLAR_HOME"

These commands will install pillar on your machine and provide you a pillar executable.

Start your project

Just install a chosen archetype and compile in your desired format 

$ pillar archetype book
$ pillar build html

You know Pharo, you want to see the generated book quickly. Start a server in yourProject/_result/html/.

You can use this in Pharo7 and Pharo6.1 

(ZnServer defaultOn: 1701) start.

ZnServer default delegate: ((ZnStaticFileServerDelegate new) 
directory: '/home/abiyalou/Documents/STAGE/Perso/samakhov.github.io/_result/html' asFileReference;
yourself).

Enjoy your website locally on localhost:1701.

You want to deploy on Github and host it using Github Pages, follow the next section.

How to use Table of contents (review)

You could notice that, there is no table of contents displayed. We have to change some things in the conf file.

How does it work?? The table of contents starts looking for titles via a specified file. For example, when you have an index.pillar including other pillar files (different chapters of your book), Pillar visits titles starting from index.pillar.

So to have a table of contents displayed, you have to decomment a line in pillar.conf. The first line of the below picture. By decommenting this line, you are telling Pillar to starts looking for titles in index.pillar and so on. Pay attention index.pillar is including all other files. 

  #'"tocFile": "index.pillar" if you have a index.pillar file containing the table of contents of your book': #comment,
  "latexWriter" : #'latex:sbabook',
  "htmlWriter": #html

Deploy on Github

You want to have acces to your website via Internet. You have a free hosting service provided by Gihtub. To use it, just create a Github repository containing your pillar book files. To automatize your book building, you are going to use Travis. Follow this quick start for Travis.