First Crack Release Notes, April 2020

I spent most of my development time in April working on a project that I can, at best, call tangentially related to First Crack. After fighting with Flask, Bottle, and then Python’s own http.server library, I decided to write my own web framework. I won’t spend much time on this now, since I plan to deploy it in an Intranet soon and then release it after some real use, but I will say this: I liked Flask, but it has far too many dependencies to work in my target environment. I liked Bottle even more, since it mirrors most of Flask’s functionality without any dependencies, but it lacks the ability to handle concurrent connections. The surprisingly capable http.server library has zero dependencies and supports concurrent execution, but is ill-suited for building out an entire web application. My project, Swig¹, solves all of these problems. For now, though, let’s talk about First Crack — a day late, yes, but I hope not a dollar short.

After reading Blazing fast math rendering on the web, I decided to replace my boring <pre> code blocks with custom <div>s. The new code blocks support line numbers and syntax-specific prepends: $ gets added to the beginning of each line in a shell script, >>> for Python, etc. I plan to add automatic syntax highlighting to my Markdown parser in the style Ben Kuhn described back in 2018, based on the language identified after the three ` marks.

Speaking of style, last month’s work also entailed some minor tweaks to my CSS file: layout tweaks to the navigation bar, since my ancient iPad does not have a browser that supports CSS grid, and I upped the page border on mobile devices from 1% to 2%. It’s the little things.

I also changed the license under which I publish First Crack, and — by extension — the default one it ships with and the license under which I publish my work here. I now use the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. You can read more about it, and the reasoning that went into the switch, in License Your Work.

Feature Roadmap #

Along with general maintenance and my constant pursuit of optimization, I also want to get these things done.

Add Syntax Highlighting to Markdown Parser #

Now that First Crack wraps code blocks in <div> instead of <pre> elements, I can add automatic syntax highlighting. Ben Kuhn described an interesting, minimalist approach back in 2018; I plan to do something along these lines.

Release Markdown Parser #

I want to release my Markdown parser as its own project. I fixed a few bugs during the rewrite, but I still have some others to work out. At the least, I want to go public with greater coverage of the spec, and with the ability to handle multi-line strings and entire files at once. My main goal is to design a performant Markdown parser and then write an efficient implementation of it. Several people have already done some interesting work in this space. At present, it implements the subset of the spec I use on a regular basis, and handles files one line at a time.

Publish Implementation of Markdown Spec #

Along with the release of my Markdown parser, I will need to outline the peculiarities of my implementation. Parity with John Gruber’s spec would make sense, or something like GitHub Flavored Markdown which has much more detailed documentation, so I may go this route; if not, I will need to produce my own documentation. This would cover weird edge cases for the most part, but it would also give those who use my engine have some sort of explanation for why their article looks weird. In brief, my argument against going with a standard comes down to the fact that I have little use for most of those features and edge use cases. Once this becomes its own project, though, that others may use, this argument gets shakier. I will have to spend some time thinking about this before I move forward.

Improve Documentation #

A few of the ways I think I can improve the README in particular:

• Re-create usage GIFs. I had a few neat GIFs that showed off First Crack’s simple install process and easy use case, but I will have to re-create those after the rewrite.
• 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, I want to highlight this.
• 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.

As always, I look forward to the work ahead.

↩ Flask, Bottle, and Swig — are you getting it?