There comes a point, usually after you've been using something for awhile, when you realize you are no longer just using it casually. And no, I'm not talking about drugs.I'm talking about defining my first shortcut key in my .vimrc
.
A little background
I was first introduced to Vim by my Hacker School buddy James. For those of you who don't know, Vim is a very peculiar text editor. It is an "improved" version of Vi, the de facto Unix editor. Vim allows for a very efficient coding experience in which your hands generally never have to leave their main resting positions on the keyboard. And unlike editors (see Emacs), Vim makes heavy usage of different input modes to separate document navigation, inserting content, and text selection. This makes for a steep initial learning curve, as the default mode in Vim is mostly navigational, which is a farcry from the style of most word processors (hjkl actually mean hjkl, not left down up right).
Word Wrap
So I was excited to be able to write these blog posts using Vim since I've gotten quite good and fast at using it. However, I quickly realized that a text editor that primarily displays lines of code needs a bit of work to properly display words and sentences.
For instance, here's what I was seeing everytime I wrote a paragraph of text:
This is a medium paragraph of text. Everything is all fine and dandy until you
get to the end of the line. Then, whatever text you just wrote gets cut off p
recisely when you reach the column width of your Vim window. This leads to awk
ward and hard to read paragraphs!
So, after a bit of research, I threw this into my .vimrc
file.
" F5 word wrap mode (great for writing blog posts!)
set wrap
nnoremap <F5> :set linebreak<CR>
nnoremap <C-F5> :set nolinebreak<CR>
The first line turns the wrap
option on. The second line binds :set linebreak<CR>
to F5
in normal mode. The last line binds the reverse to Ctrl
+ F5
. <CR>
is a carriage return, otherwise known as the enter
or return
button.
So hitting F5
in normal mode effectively types out :set linebreak
then hits enter
for you, rendering much more readable text for when you are not just writing code!
This is a medium paragraph of text. Everything is all fine and dandy until
you get to the end of the line. Then, whatever text you just wrote gets cut
off precisely when you reach the column width of your Vim window. This
leads to awkward and hard to read paragraphs!
For those of you that are curious, Vim will automatically break the line as soon as it encounters any of these characters ^I !@*-+;:,./?
. You can change that default by redefining the breakat
option. See here for details.
[vim]
[vimrc]
[shortcut]
[emacs]
[word wrap]
[blog]
[hacker school]
Since I started actively programming a few months ago, I've learned much about what technology I take for granted. In order to help me appreciate the many abstractions that our lives are built upon, I've made it my goal to be more technologically self-sufficent. The first step was to revamp my personal website. Next up was to move my code blog from Tumblr to my own domain, and then rebuild it on top of a static site/blog generator. That way, I would have complete ownership and control over my own posts.
Static what nots?
Static site generators do what they advertise. They take some content you provide, then generate a pre-determined set of static html pages that are web ready. The idea here is that once you finish setting up the styling and format of your site, you can simply focus on writing content. Of course, they have boiler plate templates ready for you too, if you'd rather jump right into writing.
Getting set up
You should certainly consult the Pelican docs for the full guide, but here's my general guide on how to get started.
Pelican is written in Python (major selling point for me), so install it and it's dependencies using virtualenv and pip. Pelican only supports reST out of the box but provides Markdown support upon installation of the Python-Markdown library. I use Markdown for my posts.
Then, you'll want to make a settings.py
file somewhere in your project folder. This file will hold the global variables you set for Pelican. The important ones include:
AUTHOR = 'YOUR NAME'
SITENAME = 'YOUR SITE NAME'
SITEURL = 'https://your-site.com'
For the purposes of setting up a blog on Pelican, you will want to set DEFAULT_PAGINATION
to be the (number of posts)/page and DEFAULT_ORPHANS
as the largest remainder of posts you'll allow on your last page. For my setup, I selected 5 posts/page, and no more than 3 posts on the last page (so up to 8 posts on the last page).
You can browse over all my selected settings here.
Making it yours
Now, you can certainly use the default theme provided by Pelican, or one of their other sample themes, but I prefer to make a theme that suits my own tastes. Reading the Pelican documentation and working through the quickstart guide took up half of my weekend, which means I spent the other half on designing my theme.
You'll need some familiarity with Jinja2 templates. At the minimum, you should read about the conditionals/loop syntax (especially loop attributes) and template inheritance (include and block). I believe Jinja2's templating system is similar to Django's, so you should feel at home if that's your forte.
Pelican is specific about what file structure it wants in a custom theme. The documentation outlines the structure, but doesn't give you adequate information on what attributes you can access from variable objects. If you need specific functionality beyond what objects and object attributes others have done in the sample themes, you'll probably just need to read through the Pelican source or ask some questions in their IRC channel.
I ended up starting with the default theme (called: notmyidea) templates and stripping it of everything I didn't want to use. For instance, I had no need for the category and author functionalities. I don't want to categorize posts and I'll be the only author on this blog, therefore, I did not supply:
categories.html
category.html
author.html
authors.html
Pelican is smart enough to just use it's base templates from the Simple theme if you don't provide all the desired html templates.
You will, however, want to make the basic html frame for your blog and save it as base.html
, as all other html templates will inherit from it. Otherwise, use the default theme's templates as a guide for building your custom templates.
Once you have your html templates set, you'll want to work on the CSS, which you will save in static/css
folder.
The theme for this blog is here. Please give me a shoutout in the footer if you want to use it ;).
Workflow
So once you have your theme, you're ready to create content! I host my pages on Github Pages, but you choose your own host.
Let's go through how I am publishing this post. First I write it (in vim!) and save it in my content folder, which stores all my posts for this year.
content/2013/trying-out-the-static-blog-thing.md
I like to move out to the root of my Blog folder, then run Pelican to update all my static pages.
$ pelican content/2013/ -s path/to/settings.py
The new static pages will be placed in
but you can always change that path in your settings.py
.
Then I simply $ git add .
in my output folder, throw on a commit message, then push it to Github.
Final thoughts
The entire set up process takes a bit of time, especially if you're making your own theme, but it's always nice to have ownership over your own content. That's just something you don't get on Tumblr or other browser based blogs. Pelican is an awesome option for anyone looking for a static blog generator and wanting to work in Python, I heartily recommend it.
[static blog]
[pelican]
[python]
[the architect]
[jinja2]
Pretty odd to have committed to writing 100 meaningful blog posts this year, and then promptly not post until Jan 6th. But as you can tell, my excuse is that I was spending all weekend building my new blog. Well I'm glad to say, here it is.
I'm now running on the static site generator, Pelican. It's awesome because it is actively developed (version 3.1.1 as of 12/4/12) and it is written in Python, which means I didn't have to default to Jekyll. It's not that I'm averse to Jekyll, I'd just rather work in the language I'm most comfortable in (not Ruby). Anyways, things I'm most excited about:
- Writing all my posts in Markdown
- Being hosted on Github Pages
- Having all my posts saved on my Dropbox
- New syntax highlighting color scheme
- Actually using my own domain
I'm planning on writing about my experience building this blog in a post later this week. Stay tuned.
(find old posts on my tumblr)
[pelican]
[new]
[github pages]
[jinja2]
[python]
[tumblr]