Getting from Github

As I mentioned Blio, has not been released yet so the way to install it is to get the latest version from Github.

If you have git installed you can use git clone git://github.com/domm/Blio.git to fetch the latest version. Alternatively, there is a button ZIP on the Github page of Blio. You can download the latest version of the source code using that button, and then you can unzip it.

Installing Prerequisites

Blio uses Dist::Zilla for packaging so probably the best thing is to first install Dist::Zilla using cpanm Dist::Zilla. Then you can type dzil install. It will install all the pre-requisites and Blio itself as well.

Alternatively, you can install the following modules, that are the pre-requisites of Blio:

DateTime
DateTime::Format::ISO8601
DateTime::Format::RFC3339
Digest::SHA1
Encode
File::Copy
File::ShareDir
File::Temp
Imager
Markup::Unified
Module::Build
Module::Pluggable
Moose
Moose::Util::TypeConstraints
MooseX::Getopt
MooseX::SimpleConfig
MooseX::Types::Path::Class
namespace::autoclean
Path::Class
Path::Class::Iterator
Template
Test::File
Test::Most
XML::Atom::SimpleFeed

Once you have installed everything you can go ahead and build your first site:

Simple setup

Create an empty directory, let's call it perl_blog.

Inside the perl_blog directory, you have to create a file called blio.ini. It can be empty, but it must exist. (If using a Linux system, you can just type touch blio.ini.)

In addition, create a subdirectory called src and create a file called src/index.txt with the following content:

title: Experimenting with Blio

Hello world

Pay attention that the filename is all lower case. The extension is .txt. The first part of the file is the header, there are more parts of it but, the title is required. After the empty line comes the content of the page.

Once you have this you can run blio.pl (while being in the perl_blog directory) that was installed when you installed Blio. It will create a directory called out and a file called index.html that was generated from the index.txt file.

The directory layout looks like this now:

 |-- perl_blog
     |-- blio.ini
     |-- src
         |-- index.txt
      -- out
         |-- index.html

You can now open the html file using your favorite web browser.

While this is a very simple "blog" so far, let's create a Github repository for the source of this site and then we can see how to deploy the site to Github.

Create Git repository for the source

The out directory should not be in the source repository so let's remove it for now: rm -rf out Create a git repository git init. Add all the necessary files: git add blio.ini src and commit this: git commit -m "initial version".

Optionally you can create a Github repository for this project and push it there. I have created one called perl_blog_with_blio. You can check it out to see the history of this article as well.

Deployment to Github

Github allows you to create a static web site driven from a repository in several ways. The one I am showing now is the nicest. You can create a github repository called USERNAME.github.com (where USERNAME is your username on Github) and it will be accessible as http://USERNAME.github.com/. Not only that, but you can even ask Github to serve the same pages when someone visits www.yourdomain.com.

In my case, I created a directory next to the perl_blog directory called szabgab.github.com. That directory will contain all the files needed on the web site. Both the generated files and other static files (e.g. CSS).

Now you can run blio.pl --output_dir ../szabgab.github.com (replacing szabgab with your username). That will generate the index.html file in the target directory and you will get this layout:

 |-- some_directory
     |-- perl_blog
         |-- blio.ini
         |-- src
             |-- index.txt
     |-- szabgab.github.com
         |-- index.html

In order to eliminate the need to pass the output_dir parameter every time you can add it to the blio.ini file like this:

output_dir=../szabgab.github.com/

Now go over to the output directory (cd ../szabgab.github.com), create a git repository there too, create a Github repository called USERNAME.github.com (with you username!) and push the local repository out. Mine is called szabgab.github.com. At this point, it has a single file called index.html in its root. (By the time you look at the repository there will be more files in my repository, but as a start there is only this one).

Once you pushed the output repository to Github you can got and drink a tea, or you can visit your favorite social network and share this article. In any case, Github needs a few minutes till it makes your site live.

After the break you can visit http://USERNAME.github.com/ and see the result. It is not very pretty, but it works!

Setting up a domain name

In order to avoid loosing your incoming links when you move your site to some other place, I strongly recommend setting up your own domain. It only costs 10-20 USD/year. A very good investment.

Once you have a domain you can set it up to point to Github and tell github to serve your pages when someone is accessing Github via that domain. For this you need to tell your DNS provider to point your host names to Github and you have to add a file called CNAME in your repository (containing the output files) with the hostname as the content.

As I only use the Github Pages for these experiments, I will use a hostname in my personal domain. So I set up github.szabgab.com to point to the github server as described in Setting up a custom domain with Github Pages and added a file called CNAME with one line in it: github.szabgab.com.

After another tea (and some more sharing of this article) you can check visit USERNAME.github.com again. It will automatically redirect to the hostname you set up and it will show the same demo page we created.

In my case you try szabgab.github.com that will redirect to github.szabgab.com.

More and nicer pages

Obviously this is only the first step in creating your on blog, but I hope this little tutorial will help you get started. You can read more details about Blio in its documentation. Both blio.pl and Blio.pm have some documentation.

If you have any question, comments, don't hesitate to post them here and don't forget to share this article. If enough people share it, I'll consider myself encouraged to extend the article...