Things I've Learned About Properly Formatted Blog Posts

September 29, 2012 by Gabe | [mmd] |

Since moving this site to a static blog, I've developed a better perspective on meta data. When I was on WordPress, I assumed the platform would handle all of my meta data. Occasionally I added a custom field but for the most part, I was ignorant of my future needs and what WordPress would handle for me.

Working in a static blog like Pelican has made me much more aware of how I draft a post and what meta data I include.

File Names

Every post I write starts as a plain text file in Dropbox. When I'm ready to post, it is uploaded by FTP to my host where Pelican processes it and generates my site. All post drafts go into a single directory that Pelican scans. That means I need to be careful not to create a new draft file with the exact same file name, otherwise I may overwrite an existing file during upload.

To insure against overwriting a file, I name every new file with the date and post title.

Things Ive learned about properly formatted blog posts 2012-09-27.txt

The date guarantees that even if I use the same title (i.e. "OmniFocus Update.txt") the file will not overwrite an older post when it is uploaded.

It's also helpful to name the file with the post title. When I want to edit an existing post I generally use Sublime Text with Will Bond's excellent SFTP plugin (Previous Discussion). I know what the post title is so that's how I will search for it.

Meta Data

My post meta data is included in a Multimarkdown header. Pelican can access any field I include but some fields are recognized as blog specific fields. For example, the "date" and "author" and "status" fields are all Pelican standard fields. I have TextExpander snippets to make this process easy. One snippet gives me a an entire header ready to fill out.

Here's an example of full header of one of my posts

title: Folding Text is Growing Up [Link]
link: http://www.foldingtext.com/
date: 2012-09-27 07:30:00
status: draft
process: @post
tags: Mac, Link
synonym: plain text

I don't use the "author" field since I am the only person writing here. Pelican automatically uses my name as the author as defined in the configuration file.

I rarely use the "status" field, which works much like WordPress. Pelican publishes "draft" posts to a drafts directory that are not part of the site index. I typically write in Dropbox and publish with my own custom "process" tag. When I set the "process" attribute to "@post" the file is processed by Hazel on my Mac and sent to Pelican on my server. I might write more about that in the future.

But for quick posts, I can work directly off of my Pelican instance with Sublime Text and SFTP. That's when I set the status to "draft".

The two most critical pieces of information are the title and date fields. The "title" field is required by Pelican. That field is used for what it sounds like. It sets the title of the article.

The "date" field is not required, but still critical for me. Pelican will use the file creation modification date for determining the article date. That's a bad idea. If I restore from a backup or otherwise edit the file, it will completely throw off the post dates. Instead, I use the "date" field to set the post date. ALWAYS INCLUDE THE DATE AND TIME IN THE HEADER.

I've also been slowly adding linked-list articles. This uses my custom "link" field. I've written about that already. But I want to be prepared for a day when I may not have linked lists. I also want to make the linked article obvious in the text. So, beyond linking the article title, I always try to include a link in the first two sentences. If the linked title stops working either by accident or on purpose, each post will still make sense.

One last piece of custom meta data I've started to include: A synonym field. This is a place for me to add additional tags that Pelican does not publish but I can search. They are tags for me and they might be useful some time in the future but not on Macdrifter.

Short Story

I capture as much meta data as possible in the header. I don't know what might be useful in the future. By far, post dates are the most critical piece of meta data. I will never trust the system date, just the date I add.

I give files meaningful names. That means the file name also includes the date. Two files can have the same title, but unless I have a stroke, they will always have a different date.

I now put an outgoing link in the post body, even if the title links too.

blog comments powered by Disqus