YAGeekBlog

Prose, an on-line text editor for Jekyll

2012-06-26T00:00:00-07:00

Prose is simply an amazing tool used to write content for your Jekyll blog hosted on github pages.

This blog post is my first test.

Satchmo colissimo a new shipping module for your satchmo projects

2012-04-04T00:00:00-07:00

I just released the first version of a new shipping module for satchmo django e-commerce solution: satchmo-colissimo. The module basic documentation follows. You can find the sources on github: https://github.com/jmaupetit/satchmo-colissimo

Dependancies

Considering you have a properly configured (and working) satchmo project. The only required dependancy is the django-colissimo module up-to-date with LaPoste Colissimo shipping rates. For more informations on how to update django-colissimo to youryear rates, please refer to the project page.

Most of the time, a simple:

pip install django-colissimo

will do the trick. If pip does not found the module on PyPI, use the github repository

pip install git+git://github.com/matm/django-colissimo

Installation

Configure django-colissimo

Once dependancies installed, edit your satchmo project settings.py and add colissimo to your INSTALLED_APPS, e.g.:

INSTALLED_APPS = (
    ...
    'colissimo',
)

Now you need to create colissimo database scheme with

python manage.py syncdb

This will also load colissimo rates in the db. If not, fetch initial data:

mkdir data
wget https://raw.github.com/matm/django-colissimo/master/colissimo/fixtures/initial_data.json \
  -O data/colissimo_initial_data.json
python manage.py loaddata data/colissimo_initial_data.json

Now you need to install satchmo-colissimo from github, either by cloning the project of using pip.

Clone the module from github

git clone git://github.com/jmaupetit/satchmo-colissimo
cd satchmo-colissimo
python setup.py install

Use pip

pip install git+git://github.com/jmaupetit/satchmo-colissimo

Activate satchmo-colissimo

To activate your custom shipping module, add satchmo_colissimo to your CUSTOM_SHIPPING_MODULES list, e.g.:

SATCHMO_SETTINGS = {
    ....
    'CUSTOM_SHIPPING_MODULES':['satchmo_colissimo'],
}

Now go to your site settings (once logged in the django admin): in development mode it would be something like http://127.0.0.1:8000/settings/. Click on Shipping settings and select Colissimo as an activated shipping module. Then, update settings and a new configuration section will appear for Colissimo shipping module.

Changelog

Initial release based on the django-colissimo module
Applies colissimo rates given a package weight, destination and recommanded level

Roadmap

Complete support of So Colissimo WS (multiple delivery modes, tracking number, shipping label, etc.)

Write your own AsciiDoc theme for HTML5 backend with SASS

2012-03-21T00:00:00-07:00

A few months ago, I was searching for a good markup language to write documents for my company. Desired features I was looking for were:

text based pivot markup language to ease collaborative work with a version control system, such as git or mercurial
easy convertion to other file formats like HTML, PDF, etc.
rich enough to define my own stylesheet/classes for the HTML backend. This is a crucial point.

To my knowledge, AsciiDoc seems to answer to all of these requirements.

AsciiDoc

As defined in the AsciiDoc home page:

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.

In a few words, AsciiDoc is yet another markup language with its own syntax and command line tool asciidoc (written in python!) used to compile your document to a specified backend. For example,

asciidoc -b html5 -a icons -a toc2 -a theme=flask {yourdocument}.adoc

This will generate a file {yourdocument}.html with the flask theme embedded.

CSS to SASS

When dealing with CSS, I have the (good?) habit to avoid doing pure CSS! There are two major languages used to ease the heavy task of writing a stylesheet: SASS and LESS. I will not debate here about what is the best framework to use for your own case, you will find plenty of articles about this around the web (see for example the smashing magazine review). I have started using SASS even it seems less (!) popular than LESS since twitter boostrap use it (personal thought).

SASS: Syntaxically Awesome StyleSheets

Compass is a CSS authoring framework based on the SASS language. In a few words, Sass is an extension of CSS3 adding some pretty cool and useful features such as nested rules, variables, mixins, etc. The language has two different syntaxes, SCSS (close to CSS) and SASS (indented syntax inspired by Haml). If you use to practice CSS, I think you would prefer SCSS (as I do!). Your SASS source will be compiled to a clean CSS thanks to the compass command line tool.

The Compass framework

The Compass framework adds a lot of mixins to deal with CSS3, a grid system (blueprint), your layout and more. For an up-to-date exhaustive list of implemented mixins, please, check out the compass documentation.

Let’s start working

First, you need to install Compass (see compass install instructions), and then create a new compass project with:

$ compass create AsciiDoc_SASS --using blueprint

The --using blueprint argument is optional; add it if you want to use the blueprint grid framework. Once created, your project will look like:

AsciiDoc_SASS/
├── config.rb
├── images
│   └── grid.png
├── sass
│   ├── ie.scss
│   ├── partials
│   │   └── _base.scss
│   ├── print.scss
│   └── screen.scss
└── stylesheets
    ├── ie.css
    ├── print.css
    └── screen.css

Since by default, AsciiDoc will only consider one single css file for your theme, you can remove unused print.{scss,css} and ie.{scss,css} files (please, tell me you are not using IE < 9).

Now, it’s time to find a name for your theme! My theme is hightly inspired by the flask theme so let it sounds more frenchy, and call it fiole. You will need to rename your screen.scss file to {yourtheme}.scss.

By default, the html5 backend template file loads two javascript files: asciidoc.js and {yourtheme}.js, so create a js directory and fetch the latest version of asciidoc.js. Your project tree is now:

AsciiDoc_SASS/
├── config.rb
├── images
│   ├── grid.png
├── js
│   ├── asciidoc.js
│   └── fiole.js
├── sass
│   ├── fiole.scss
│   └── partials
│       ├── _base.scss
└── stylesheets
	└── fiole.css

We will now convert asciidoc default CSS to SASS, thanks to css2sass service (source code of the project is available on GitHub). To do so, fetch the latest release of the asciidoc default stylesheet:

$ cd /tmp
$ wget http://asciidoc.googlecode.com/hg/stylesheets/asciidoc.css

Then copy all the asciidoc.css file content to the sass2css form and click “Convert 2 SCSS”. Copy The lower textarea SCSS code to a new partial file:

$ cd AsciiDoc_SASS
$ touch sass/partials/_asciidoc.scss
$ emacs sass/partials/_asciidoc.scss

Add paste the SCSS code to the _asciidoc.scss file. You will need to add this style definition to the main document, by adding:

@import "partials/asciidoc"

at the end of the sass/{yourtheme}.scss file. Now you are ready to compile stylesheets with:

$ compass compile

A more efficient way to work is to use the:

$ compass watch

command. In this case, each time you save your scss file, compass automatically compiles your source file to update your css.

Create your own theme

Now you are ready to work on you own theme. Go create a partial called _{yourtheme}.scss in partials directory to override _asciidoc.scss scss rules, and add it to your main theme file: {yourtheme}.scss.

@import "partials/asciidoc";
@import "partials/fiole";
@import "partials/h5bp_print";

Procede the same way for printing rules. A good idea is to create a _print.scss partial with html5 boilerplate good practices for @media print rules.

Work Work Work … coffee … Work Work Work … done!

Once your style is ready for production, use the following command to generate a minified version of your CSS file:

$ compass compile -e production --force

Use your new AsciiDoc theme

Now it’s time to test your style on your AsciiDoc file (e.g. lorem_ipsum.adoc) by typing the command:

asciidoc -b html5 -a linkcss \
-a stylesdir=AsciiDoc_SASS/stylesheets \
-a scriptsdir=AsciiDoc_SASS/js \
-a themedir=$(PWD)/AsciiDoc_SASS/stylesheets \
-a theme=fiole \
lorem_ipsum.adoc

And tadaaaah!

Resources of the tutorial

You will find all ressources of this tutorial on github:

https://github.com/jmaupetit/AsciiDoc_SASS

Hello Jekyll

2012-02-20T00:00:00-08:00

After searching for months an easy to use blogging system for my everyday use, I finally found Jekyll, thanks to my twitter feeds.

Features

With Jekyll, create a new blog post or a new page for your blog is as easy as typing a single command line like rake do something. You only need to focus on the content written in markdown. Main advantages of this tool are:

You only need your favourite text editor (GNU Emacs of course!) and a terminal (with git installed) to publish new content on your blog
No database is requiered
Github free hosting (uses GitHub Pages)
GitHub Pages allows you to use your own domaine name (define a CNAME) pointing to your repository (your blog in fact)
Optionally you can locally install jekyll to preview your content

Overview of Jekyll

Create a blog post

Once installed and configured (5 minutes with the Jekyll quick start guide), simply create a blog post with the command:

$ rake post title="My New Post"

This will create a properly formated file ./_posts/2012-03-15-my-new-post.md. This is the one you must edit with your post content.

Create pages

You may also want to generate static pages for your blog. Let’s say you want to create a static page with relevant informations about you, type:

$ rake page name="about.md"

This will create your page template about.md in your project root directory. This page will be automatically listerd in the /pages.html view and available at /about.html. The Jekyll documentation mention the possibility to create nested pages via the command:

$ rake page name="pages/about.md"

Publish

Once configured, publishing new content to your blog is a classical git workflow:

$ git add .
$ git commit -am 'New blog post added'
$ git push origin master

Now wait for a few minutes, GitHub will send you a notification once our page has been build successfully.

Syntax highlighting

One of the major feature I liked is the opportunity to add syntax highlighting for code blocks: Jekyll uses Liquid to process templates and adds its own tags including highlight.

Using the highlight liquid tag, the following block code:

{% highlight python linenos %}
print "Hello Jekyll!"
{% endhighlight %}

will be rendered as:

1 print "Hello Jekyll!"

Note to myself: to display the non-rendered block you should use the literal tag for liquid 2.2.2 and the raw tag for liquid 2.3.0, and both of them are not backward compatible… Hence, when gh-pages will upgrade to liquid 2.3.0, this page will be broken and will need an update. Please, dear reader: do not hesitate to warn me! This has been reported in issue #425

Configure your domain name

As explained in GitHub Pages documentation, GitHub offers you the possibility to use your own CNAME pointing to your repository/blog. Hence, at the root of your repository add a file named CNAME which contains your subdomain name, e.g.

yageekblog.maupetit.net

And of course, configure your DNS settings properly, e.g.

yageekblog.maupetit.net. CNAME IN jmaupetit.github.com.

Still some work to do…

Now that I have found the technical solution I was looking for, I have to do some more work to migrate posts from my previous blog ( http://www.maupetit.net/Blog/ ) and define my own template and not the-minimum theme.

UPDATE 2012/04/05

Last remarks

Debugging your pages/posts

In page build failure case (when pushing to github), install gem versions used in production by github, e.g. liquid 2.2.2 and jekyll 0.11.0

sudo gem install liquid -v 2.2.2
sudo gem install jekyll -v 0.11.0

To see building errors, inactivate the auto mode, by editing your _config.yml as:

auto: false

Always run the jekyll server with the --safe option

$ jekyll --server --safe