Today, I finally released Yak. It's been nearly two months since its inception. The combined coding time is probably under 24 hours, but thinking about the tiny details took the most of time. And it's hard to make time for programming, let alone sleep, in this bullshit country of mine.
Anyway, it's on PyPI, the Python package index. You can install Yak by running:
pip install yak
Yak is my first project in Python, and I had quite a fun time writing it. It's really a simple(and dirty) script if you look at the source code. I made using Yak as easy as possible, and the package includes a basic skeleton you can use right away. Included theme is the same as this blog.
All the articles I wrote on this blog made its way to the details of Yak, and they're what makes this project so meaningful for me. The RSS feed of articles by others I read while building Yak are here. They also played a key part in this project.
Special thanks to people at the LangDev IRC channel for the priceless discussions.
I scraped all the pieces of thoughts in my brain and actual pieces of writing on notes and put them together, and here is 'The Making of Yak' blog!
And guess what? This blog is powered by Yak! I'm planning to release it tomorrow =3
The writings here may seem trivial, but they're nevertheless a valuable memory to me :)
Here you can read about the implementation details of Yak. I'm writing this to guide myself when writing Yak, and for all those who are interested. This article can be used as a manual for Yak.
Basic philosophy: This blog, and Yak should minimize unnecessary work when writing blog posts.
Users can start using Yak right away by running:
yak init
This will create all the necessary files needed by Yak to bake a blog. It is encouraged to run the command above first, and edit the files from there.
You can get help by running:
yak --help
Yak will require three directories '_templates', '_posts', '_static', and the configuration file '_config.py' at the root of the blog directory.
The configuration file '_config.py' is a simple Python script defining constants for Yak to use when baking the blog. Here is the config file used by this blog, the bare minimum:
# -*- coding: utf-8 -*-
BLOG_AUTHOR = u"Jihyeok Seo"
BLOG_TITLE = u"The Making of Yak"
BLOG_URL = u"http://yak.limelog.net/"
BLOG_RIGHTS = u"Copyright © 2011–2012 Jihyeok Seo."
BLOG_SUBTITLE = u"Just another yak shaving blog."
All the file under the '_static' directory will be copied to the root of the output directory. You sould put stylesheets and favicon.ico files here. Optionally .htaccess files.
In the '_templates' directory, Yak will require four Jinja2 template files 'index.html' for the blog index page, 'post.html' for individual post pages, 'archive.html' for archive pages, and 'atom.xml' for the ATOM feed of the blog.
All files in the '_post' directory ending with '.md' are treated as blog posts, and rendered as Markdown. Yak will look for them recursively so you can organize them whatever way you like as long as they're under the '_post' directory.
The file name of posts must match the format 'YYYY-mm-dd-post-slug.md'. I set this restriction because they are going to make up the important permalinks.
When refering to an image, the image link may be absolute(with the 'http' prefix), or relative to the post file. For an example, if you have the image file and the post file in the same directory, you can include images like this: .
All metadata about the post documented below must be specified at the beginning of the post file. Time metadata is always interpreted as UTC.
You can set post title by writing 'Title: Post Title'. If none is specified, the slug becomes the post title.
You can write linked posts by writing 'Link: http://example.com/'.
You can set published 'time' by writing 'Time: HH:MM:SS'. If none is specified, midnight will be used. Be sure to set this if you have two or most posts with the same date, if not, your ATOM feed will not validate, and the order in which the posts are shown may not be desirable. If you find doing this very annoying, sorry about that. File metadata the OS passes are not very reliable.
You can set updated 'date' or 'time' by writing 'Updated: YY-mm-dd HH:MM:DD' or 'Updated: HH:MM:SS'. The updated date and time must be
What should be on the front page of a blog?
- The name of the author
- Recent posts
- Pagination?
- Link to archives
Read my short thoughts on names here.
Recent posts. But how recent? I think 20 is enough. Should we paginate? But how many people click on those tiny numbers? I never did. If the first 20 posts I see are good, that blog deserves to be in my feed list.
Links to archives. For how long of a time of posts should each archive keep? A month? A year? It depends on the writer, so I'll let them choose.
Brent Simmons has a good article on feeds.
Now some boring stuff.
There are two significant feed formats, ATOM and RSS. Until today, I thought RSS was better than ATOM as a format. Because to my eyes, it was the most commonly seen word. But looking at the specifications, it turned out that RSS sucks(as a format).
So ATOM will be the default feed format for this project.
Tom Preston-Werner, the cofounder of GitHub, wrote Jekyll, a blog-aware static site generator, for the whole GitHub community to use.
Octopress is another static blog generator based on Jekyll by Brandon Mathis.
Brent Simmons, the author of inessential.com, uses his own static blog generator.
Movable Type's default mode is static.
Yesterday, Marco Arment released his static blog generator Second Crack.
I bet there are bunch of other static blog generators out there. Hell, that's a lot of static generator for blogs. Why bother making another?
Because none above fit my exact needs. And well, some programmers like yak shaving.
WYSIWYG was a lie.
- You get much more than what you see. Unnecessarily generated markup that is longer than your writing.
- You lose all you see. Poor WYSIWYG editors sometimes screw up and decides to throw away all your writings.
- You totally get what you see. HTML-color for emphasis? Really?
And to quote Brian Kernighan,
The problem with ‘What You See Is What You Get’ is that what you see is all you’ve got.
WYSIWYG may seem easy to use, but they are a mess. In my opinion, John Gruber's Markdown is a much better solution for blogging. It adds semantics with minimum markup and mental load.
Page titles are important because they convey the critical information of 'what this page is about' and 'what site this page belongs to'. I've looked at the page titles of a few blogs, and most of the sane ones fall into these formats;
- Blog Name » Page Title
- Blog Name: Post Title
- Post Title | Blog Name
- Post Title — Blog Name
I've thought about exposure priority, decoration preferences, and some other things, but it turns out that there are proper uses for dashes, especially the em dash.
TL;DR;
Use the em dash, like this: Post Title — Blog Name
What social aspects are there of a blog? Well, since the rise of Facebook and all, 'social' has become somewhat like a buzzword. All human activity is social in some way. But hey, definition that you get right away is the best definition.
So, we have comments as an obvious example. In my opinion, comments are unnecessary for blogs. For those people who comment on blogs, you should start a blog and get your own voice. Get a proper online identity, not a fragmented one.
Because I'm writing a static blogging system, having an in-house commenting system means regenerating the whole website each time a comment is posted, which is a huge down for performance.
If you must use commenting, using an external system such as DISQUS is much better.
Permalinks are called premalinks because they are, or should be, permaneant. If something is going to be permanent on the web(well, everything on the web is), you want them to be meaningful and pretty.
By meaningful, I mean permalinks should include a published date or some kind, and a slug. By pretty, I mean no unnecessary clutter. The following is my ideal permalink format for a blog post. (I chose to include the 'day' in the permalink, due to an implementation detail).
http://yak.limelog.net/2012/01/02/permalinks/
That's much better than this:
http://blog.hona.kr/?p=201
or this:
http://limelog.net/post/11091170754
They are also what guides people to your website. People should be able to expect what kind of content they will recieve just by looking at the URL. That's why I dislike the act of URL-shortening. You never know what you're going to get. If it needs to be shortened, then someone's doing their job wrong.
For most blogs, people come to 'read'. They don't come to look at ads popping up here and there, especially not under their cursor, nor a full-screen terror.
If you are one of theses ad abusers, stop right now. You have no respect for your readers, nor your site. There are plenty of other ways to do ads, and do them right.
Again, people come to read. You don't want your lovely readers squinting at grey-on black texts or magnifying their viewport every time they visit your site.
Other than content, you should make readability the top priority. Accessibility often comes together, as long as you follow web standards.
To me, the author's name is important.
To others, the presence of a name shows that the author is taking responsibilities, and people get a feeling of authencity from the writings.
To the author himself, it is an oath to self, to be who one is, no more, no less. You will feel a sense of futility if you don't use your real name. Do not fear to be wrong. Nobody is right. Everyone is wrong.
When I was a little kid, I looked at the all-so-mighty Yahoo! and thought how the news headlines changed every time I hit refresh.
Is there someone at Yahoo who updates the index HTML file every second?
What a musing.
Serving dynamic content like that must be really slow. It's ironic that the slowness is still the case these days.
A blog doesn't need to be dynamic. Why not serve blog posts as static content? That way my writings won't end up in some cryptic database. Put those on a ramdisk and the bottleneck is the so-wide 100Mb/s home internet connection(in the case of Korea). Even better, with SSDs, we don't even need caching.
So my blog will be static. I need a static blog generator. A blog baking engine.
Tools are tools. If you want to write on the web, the only important thing is really, your passion to write.
But I, as a programmer, have never liked any of the blogging tools all the people are using. Wordpress is too heavy, I've seen too much of those blogs get fireballed. Tumblr is pretty but its permalinks are not, and there is too much downtime. etc etc etc.
So I've resisted my desire to write just because there is no publishing platform I like. It's been like that for three years, and here I am, regretting, still wondering why there isn't this simple tool I need.
That's it. Fuck waiting. I'm a goddamn programmer and I'll write my own.
