First Crack Release Notes, June 2019

Since re-releasing First Crack, I have made some great progress on the project. Not enough for version 2.0, though, so I spent the last few days thinking about how I wanted to post new versions. In short, I decided not to.

Traditional software versioning implies a cycle of feature integration — feedback — improvement that I neither have the user base nor the inclination to do. I also don’t want to take such a formal approach to a hobby I work on in my spare time. I still want to talk about improvements, so instead of versions, I plan to post monthly release notes for First Crack. This series will serve as a written record of the changes I make and the thought process behind them, as well as a good way for those interested in the project to keep up with it.

June Activity #

First, the changes I made in June. These are now live at Github and Bitbucket.

Public Release #

It took me a long time to re-releases First Crack, but I finally did it. This new version does more, builds a more feature-rich website, and implements a larger subset of the Markdown spec. It now has the versatility and polish a public project should, unlike its predecessor. This release was long overdue, but — I think — worth the wait.

Python 3 Migration #

I started writing First Crack in 2012, with Python 2; I ported it to Python 3 in June. This involved swapping a few print statements with the new print() functions.

Canned "Pretty Print" #

I believe in generating valid HTML files that also look good: the former because I care about being a good programmer, and the latter because it makes debugging easier. First Crack still builds valid HTML files, but I canned “pretty print”. It created too many problems with <pre> blocks that I could not solve with the old Markdown parser. I plan to revisit this once I work out the kinks in the new one.

Stateful Markdown Parser #

Ahead of First Crack’s re-release, I identified the Markdown parser as the oldest, hackiest part of the code base. As the least optimized, most called method in the project, re-writing it seemed like a great idea. This had the potential to have a huge positive impact, and so I set out with a few goals in mind. I wanted to build a more reliable parser, less susceptible to weird edge cases, that implemented more of the Markdown spec. This would mean more overhead, so I also wanted the method to stay fast. I set out to do this over the next few months, but ended up finishing it a couple days later. The new version met each of my goals, and runs about 25% faster than its predecessor. I plan to release it as its own project soon.

Improved Documentation #

I made the last change in June to First Crack’s documentation. In particular, I spent some time fleshing out the README, with the goal of doing a better job explaining the aspects that make my project great. I settled on four short bullet points on First Crack’s front- and back-end features. I now highlight the project’s strengths right at the start: a lightweight, full-featured, beautiful blog with a custom landing page, and a fast, easy to use, platform-agnostic engine to build it.

July Plan #

Going forward, I plan to focus my efforts on these areas in July, 2019.

Re-Implement "Pretty Print" #

See above, but in brief: now that First Crack uses a stateful Markdown parser, I would like to re-implement the “pretty print” feature I canned before the re-write. I like reading well-formatted HTML.

Release Markdown Parser #

Speaking of the new Markdown parser, I would also like to release it as its own project in July. Usage would look like this:

$ python3 >>> import Markdown >>> md = Markdown() >>> >>> raw_markdown = "Hi, **this** is a sentence with a [link]( to *Google*." >>> >>> print(md.html(raw_markdown)) Hi, <strong>this</strong> is a sentence with a <a href="">link</a> to <em>Google</em>.

Before I can do that, though, I have a few bugs to work out with the Markdown implementation, and I would like to enable parsing multi-line strings and entire files at once.

Publish Implementation of Markdown Spec #

There are some peculiarities to my implementation of the Markdown spec, so I want to outline those differences in a formal document. I picture something similar to the original Markdown syntax document on Daringfireball.

Guided Setup #

I would also like to add a guided setup to my project. Right now, First Crack forces the user to fill out a config file before it builds their website. I would like to make this a guided process, where First Crack asks the user questions and builds that config file itself. At this stage, I want to focus on lowering the barrier to entry for a new user, and making First Crack more attractive.

Better Documentation #

I did a lot to improve First Crack’s documentation in June, but I will always have more work in this area. That will look like more robust comments in the scripts, but I want to focus on the README. As the first document most people will read about the project, I want to make it compelling, informative, and fun. I have a few broad ideas going into this, based on good examples from other projects:

I have a lot of work ahead of me, but I look forward to it.