Blog | Interesting things


Syntax Highlighting with Markdown and Rainbows

14 February, 2013 by John W. O'Grady in with Comments

I needed an easy way to share code snippets on my new blogging platform. My requirements:

  • Uses GitHub Flavored Markdown
  • Syntax Highlighting - Of course I want my code to like nice.
  • Clean HTML - Server side solution like Pygments renders and returns modified HTML to the page. I think using javascript is a more elegant approach.
  • Protect the formatting of snippet regardless of screen size - Python is very sensitive to whitespace so it's important that my code examples retain formatting.

Here are the results:

Live View:

Python

friends = ['john', 'pat', 'gary', 'michael']
for i, name in enumerate(friends):
    print "iteration {iteration} is {name}".format(iteration=i, name=name)

Ruby

# Variables and expressions.
a = 10
b = 3 * a + 2
printf("%d %d\n", a, b);

# Type is dynamic.
b = "A string"
c = 'Another String'
print b + " and " + c + "\n"

Shell

#!/bin/bash
# declare STRING variable
STRING="Hello World"
#print variable on a screen
echo $STRING

Here is the Markdown I wrote to create the Python example.

###Live View:

     ####Python
     ````python
     friends = ['john', 'pat', 'gary', 'michael']
     for i, name in enumerate(friends):
     print "iteration {iteration} is {name}".format(iteration=i, name=name)
     ````

...and the HTML source....

<h3>Live View:</h3>
<h4>Python</h4>
<pre><code data-language="python">friends = ['john', 'pat', 'gary', 'michael']
for i, name in enumerate(friends):
    print &quot;iteration {iteration} is {name}&quot;.format(iteration=i, name=name)
</code></pre>

Comparing the two examples you will notice that I assign a language in Markdown which then gets rendered to the data-language attribute in the HTML. Rainbow.js uses the data-language attribute to apply the proper syntax highlighting.

Getting Markdown to work with Rainbows took two steps.

First, I followed the basic setup instrcutions on the Rainbows.js website.

Second, I modified Python Markdown to pass the data_language attribute instead of the default class. note: for this solution to work make sure your fenced_code extension is working. Here are the links to the relevant code.

How to enabled Python's fenced_code extension
How to make Markdown compatible with Rainbows.js

Setting Up Sublime Text 2 on Ubuntu 12.04

05 September, 2012 by John W. O'Grady in , with Comments

For years I've been searching for the holy grail of text editors. After hearing many good things about Sublime Text 2 I finally decided to give it a whirl. Unfortunately it's not available in Ubuntu's Software Center. That's not a good start. Even worse, Sublime doesn't maintain a PPA for the Ubuntu community.

Your installation choices are adding a PPA from a sketchy source, or doing a manual install. For security reasons you should opt for the manual install. Manual installs build character and only takes a few minutes anyway so let's get started.

Install Sublime Text 2 on Ubuntu

A few quick Google searches uncovered installation instructions for Ubuntu. Why these aren't on Sublime Text's own page is beyond me. A big thanks go out to Jevin from Technoreply for filling in the gap. I've modified his steps a little bit to fit my personal preferences, but I couldn't have done it without his help.

First, head over to Sublime's download page and Copy Link Addresss (right click in Chrome) for either Linux 32 or Linux 64, whichever one is appropriate for the version of Ubuntu you have installed.

  • download and unpack the tar file
  • move the folder to usr/lib
  • create a symbolic link
cd ~/Downloads
wget -O sublime.tar http://paste.appropriate.link.address.here.
tar xf sublime.tar
sudo mv Sublime\ Text\ 2 /usr/lib/
sudo ln -s /usr/lib/Sublime\ Text\ 2/sublime_text /usr/bin/sublime

The last line creates a symbolic link so can start Sublime Text 2 simply by opening up a terminal (Ctrl-Alt-T) and typing 'sublime'.

Note: Every time Sublime releases a new version you will have to copy the latest file to /usr/bin/sublime so bookmark this article for future reference.

Optional Configuration Steps

Add Sublime Text 2 to Ubuntu Launcher Utility

You may have notice that Sublime Text 2 isn't listed in the launcher utility. Let's fix that.

sudo sublime /usr/share/applications/sublime.desktop
  • Copy, past the following into Sublime Text 2.
[Desktop Entry]
Version=1.0
Name=Sublime Text 2
# Only KDE 4 seems to use GenericName, so we reuse the KDE strings.
# From Ubuntu's language-pack-kde-XX-base packages, version 9.04-20090413.
GenericName=Text Editor

Exec=sublime
Terminal=false2012-09-05 14:41:00
Icon=/usr/lib/Sublime Text 2/Icon/48x48/sublime_text.png
Type=Application
Categories=TextEditor;IDE;Development
X-Ayatana-Desktop-Shortcuts=NewWindow

[NewWindow Shortcut Group]
Name=New Window
Exec=sublime -n
TargetEnvironment=Unity
  • save Ctrl-s and quit Ctrl-q Sublime Text 2

Since Sublime was open when you saved the desktop file Ubuntu will probably throw an error message. No worries. Just cancle/ignore it and move on.

To test that everything is working simply go to Dash Home (the top icon on the Unity nav bar) and search for "Sublime". You should see a nice Sublime Text 2 icon. If it's not there it's because you didn't save the file in the right place. Try again.

Make sublime the default text editor

Now let's associate all text files with Sublime by updating the default file associations. Sublime's built editing feature makes it easy.

sudo sublime /usr/share/applications/defaults.list
  • In sublime, Ctrl-f and type 'gedit` to find the first instance
  • Use your mouse to highlight the complete phrase gedit.desktop
  • Ctlr-d and hold untill all instances are highlighted
  • type sublime.desktop to replace all instances of gedit.desktop
  • Save Ctrl-s and quit Ctrl-q Sublime Text 2

You are all setup now.

Installations hassles aside, my first impressions of Sublime are pretty good so I encourage you to try it.

PS: I lost power while writing this article. I'm happy to report the Sublime Text 2 has a great auto-save feature that is active by default. Yeeehaawww!

Have a problem? Need help? Leave a comment and I promise to reply quickly.


Building a Better Blogging Platform

03 September, 2012 by John W. O'Grady in with Comments

When someone says they are going to build a new blogging platform the sane response is to tell them they are nuts! Wordpress, Drupal, Tumblr, BlogSpot, Octopress - these are oustanding products with thriving communities. What isssues could a new blogging platform possibly address that hasn't already been solved?

It all boils down to syle and personal preference. While the above solutions may be technically superior, none of them conform to the way I want to work.

I suspect my ideal blogging system is similar to what others want. My hope is that this project builds momentum and attracts collaborators. What better way to improve your software development skills than to participate on a team solving issues everyone already understands? To this end, I'll be maintaining the repo on GitHub. Consider this a formal invitation to send a pull request, file a bug report, or tell me I'm crazy.

My Ideal Blogging Platfrom

Since I am the project's chief architect at the moment I better start by defining some requirements.

Project Guiding Principles

  • Free and open source
  • Easy authoring. For me that means text files using markdown syntax
  • Easy editing. I don't mind editing existing source in the browser
  • Statically generated
  • No Command lines - Nothing kills inspiration like firing up a terminal

Technology Goals

I plan to implement the concept of a static content generator on Google App Engine.

Static content generator means the articles' HTML gets rendered when authored or edited. There are no calls to a database to retrieve content when the page receives a visitor. Everything is statically served HTML. The main benefits to this approach are...

  • fast, very fast.
  • stable. Since you are only serving static files there is hardly anything to break.
  • good separation of code and content. The generator is completely separate from the published content.

Of course, none of this is new. There are many static blogging engines out there. In fact, at the moment I'm using Octopress hosted on GitHub which is very good solution. The only issue I have with Octopress is that I have to manage the process of generating and pushing the content. All that administrative overhead takes my focus away from content development.

Google App Engine is very well suited for managing the generation process. The way I envision it working is that I would upload my markdown or HTML files to GAE. GAE would add the files to a task queue and render the blog's pages. Should I want to edit the file after that I simply log into the admin interface and make changes in a web browser. The GAE app would be smart enough to figure out what pages need to changed and render them accordingly.

This idea is also not new. Nick Johnson, a former member of the Google App Engine team, wrote an outstanding tutorial for a GAE powered blogging platform called Bloggart in 2009 that does many of the things I described above. The Bloggart source is still available on GitHub, but there hasn't been a commit in over a year. Google App Engine has also made significant enhancements since Bloggart was released. Thanks to GAE commitment to backwards compatibility the Bloggart code still runs flawlessly, but its uses several depreciated libraries; most notably Django forms which was phased out with GAE's Python 2.7 support. There are also some exciting new possibilities with GAE's new Search and URL Fetch features that simply weren't available when Bloggart was developed.

While this project may have been inspired Bloggart, I fully expect the end product to look and act very different so the project needs a new name. Stay tuned!


Uploading Your Google App Engine Projects To GitHub

02 September, 2012 by John W. O'Grady in with Comments

Yesterday I wrote about setting up GAE 1.7.1 on Ubuntu 12.04. Now I'm going to show you how to add your Google App Engine projects to a Github repository.

GitHub Social Coding

The GitHub repository setup process...

  • assigns the correct username and email address to the proejct.
  • configures the git .ignore files
  • creates the readme file
  • initializes the repository and does the first commit.

Now simply clone the repository to your workstation.

NOTE: I assume you know how to create the repo on GitHub and clone it to your workstation. If you don't, GitHub has excellent documentation on how to do it.

Adding GAE Project Files to the Git Repository

Now that you have the GitHub repository cloned to your workstation you have to add your project files.

Windows

First you have to copy GAE project files into the repo and commit the changes. I normally just create a project with the launcher and copy and past the files it creates into the repo. That part is not too bad, but adding your new project to the launcher is a bit of a pain because you have to import your repo as an existing project. You can't simply create a project and tell launcher where to place the files because the launcher insists on creating a folder too.

Linux

Things get a lot easier when you move over to Linux.

  • clone the repo
  • copy the template files to the repo
  • cd to the repo
  • git add and commit the project template files
  • git push origin to master
git clone git@github.com:your_username/your_project.git
cp -a /path/to/google_appenine/new_project_template/. your_project
cd your_project
git add .
git commit -m "your message"
git push origin master

Now you are all set. Here is what you have accomplished.

  • Created and cloned a repo
  • Added and committed the GAE project template files to the repo.
  • Pushed everything to GitHub

Lost? Confused? Did I make a mistake? Send me a comment. I promise to respond quickly.


Setup Google App Engine 1.7.1 on Ubuntu 12.04

01 September, 2012 by John W. O'Grady in , with Comments

Google App Engine's (GAE) Python Software Development Kit (SDK) for Windows includes a convenient installation package and launcher utility for managing your web applications. The Linux version lacks these features, so when I ditched Windows in favor of Ubuntu 12.04 I was a bit disoriented at first. I'm pleased to report that despite the lack of hand holding, the Linux platform is better suited for GAE Python development. Follow these steps and you will be up and running in five minutes or less.

First, I assume you already have Ubuntu 12.04 up and running, so open a new terminal with Ctrl-Alt t and perform the following tasks:

  • navigate to your home directory
  • create a google_projects folder
  • move into google_projects
  • download Google App Engine 1.7.1
  • unzip the file
  • delete the .zip archive
cd ~
mkdir google_projects
cd google_projects
wget -O gae.zip http://googleappengine.googlecode.com/files/google_appengine_1.7.1.zip
unzip gae.zip
rm gae.zip

Next, create a test project and start the development server. We will use Google's new_project_template for testapp

  • copy new_project_template from google_appengine and rename it testapp in your google_projects directory
  • start dev_appserver.py
cp -r google_appengine/new_project_template testapp
python google_appengine/dev_appserver.py testapp
  • open up your web browser to http://localhost:8080 to be greated with "Hello world!".
  • stop the server with Ctrl-c.

That's it!

Keep Reading For Optional Configurations

Luanch Your App on a Specific Port

Sometimes you need to run dev_appserver.py on a specific port.

python google_appengine/dev_appserver.py --port=1234 testapp

Update Your System Path

Adding Google App Engine to your systems path saves you time. It's really simple too.

pico ~/.bashrc

Scroll all the way to the bottom of the file and add these two lines.

# Path for Google App Engine
PATH=$PATH:/home/your_user_name/your_project_folder/google_appengine/

*be sure to replace your_user_name and your_project_folder with the correct values.

  • Ctrl-o to save
  • Ctrl-x to exit
  • For the changes to take affect you must close and reopen your terminal window
  • Start your Google App Engine app like this:
dev_appserver.py google_projects/testapp

*Did you notice that you didn't have to type out the path to dev_appserver.py? That means your path is working.

Go back to http://localhost:8080 to see "Hello world!" again.

Read The Python Development Server's Official Doc

GAE's official docs on the Python development server are pretty good and are definately worth a look.

Have a question? Something doesn't work?

Leave a comment and I promise to respond quickly.