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
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](https://google.com) to *Google*." >>> >>> print(md.html(raw_markdown)) Hi, this is a sentence with a link to Google.
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:
- GIFs of the install and run process that show simplicity, ease, and speed.
- Performance graphs of First Crack’s back-end performance versus other, similar engines. At less than two seconds to build a website of over one thousand pages,
- Performance graphs of the web pages First Crack builds versus the pages common content management systems build.
- Screenshots. This site is a live demo of the engine, but I like the idea of having a few pictures in there, too.
I have a lot of work ahead of me, but I look forward to it.