First Crack is a content management system, or CMS, that I began designing in late 2011 after learning of Marco Arment's plans to build his own CMS called "Second Crack". My choice of the name "First Crack" is simply a nod of acknowledgment to Marco's work, not necessarily an indication that I believe First Crack to be a superior service.
Despite my efforts to make this process as streamlined as possible, I acknowledge that publishing through my CMS could be simplified and improved. Therefore, if you have any suggestions, questions, comments, or concerns, feel free to contact me through my website, zacjszewczyk.com, or on Twitter using the handle "@zacjszewczyk". Below I have provided a more in-depth explanation of the inner-workings of my CMS, as well as a short walkthrough to help you get up and running. Enjoy.
Types of Files:
In the previous paragraph, I mentioned that in order for content files to be correctly parsed by First Crack, they must be plaintext files utilizing the .txt file extension, formatted with Markdown. From John Gruber's page on Markdown, "Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)." For more information on Markdown, see the documentation page on Daringfireball.net. Before moving on though, I would like to provide a few basic instructions for writing in Markdown:
Paragraphs, in Markdown, are formatted very similarly to the layout here: simply write a paragraph, then end it with two spaces ( ) following the last character. Italic text is denoted by surrounding a portion of text with asterisk (*) marks: In this sentence, *this text is italic.* "this text is italic." would be italicized. Currently, First Crack does not support bold text. However, if the need presents itself, simply surround a portion of text with the HTML tags for bold, <strong> and </strong>: In this sentence, <strong>this text is bold.</strong> "this text is bold." would be displayed in bold text. To create a link in Markdown, use the following format: [name of link as it should be displayed](url). As an example, take [Google](http://www.google.com): this link would be parsed and printed to the page as <a href="http://www.google.com">Google</a>. Note that "http://www." must be past of the URL. Othwerwise, the CMS assumes that you are linking to a local file. With that, let's move on to block-level elements.
In addition to inline elements such as the <em>, <strong>, and <a> tags denoting italic text, bold text, and links, respectively, Markdown also provides for the use of heading elements <h1> through <h4>. For those unfamiliar with heading elements, the <h1>-<h6> tags are generally used to separate a title or heading from a body of text. In Markdown, heading elements are designated by surrounding the desired header with a number of hash marks. The number of hash marks corresponds to the integer following the "h" in the header elements: "# Header #" results in <h1>Header</h1>, "## Header ##" results in <h2>Header</h2>, and so on.
Making a Post:
Now that you are familiar with the directory structure, types of files First Crack requires, and have some understanding of markdown, the final section of this readme file will be to provide a brief tutorial on creating and publishing a post with First Crack.
- First, create a new text document and save it to the Content directory. Choose any name you desire, though I recommend it be similar to or the same as the title of the article it represents.
- Once the text document has been named and saved, open it in your favorite plaintext editor. I recommend Sublime Text.
- Place the title on the first line. To specify a title, surround the title with a single hash tag, signifying that it is an <h1> element. The result should look like this: "# Article Title #".
- Leave a blank line after the title, before the first paragraph. To start a paragraph, simply type the contents of the paragraph, then end it with two spaces. Repeat this step for as many paragraphs as you want to article to contain.
- Save the document and run Update.py. Update.py will update the entire site to reflect the changes you have made. To view the new site, navigate to the Structure folder and open index.htm in your web browser. Congratulations, you have published your first article with First Crack.
Removing a Post:
To remove a post, simply delete the content file from the Content directory, then run Update.py. The CMS will remove the appropriate Structure file and rebuild the site to reflect your changes.
First Crack's Authoring Mode
First Crack also comes equipped with an "authoring" mode, which allows you to do the following: force a single article to rebuild, force all articles to rebuild, upload a specific article, upload the most recent five articles, re-upload the entire website, and upload all back-end files. Enter this mode by entering "./Update.py -a" at the command prompt, at which point the CMS will prompt you for further input.
So there you have it: First Crack. I have put a great deal of effort into this CMS over the last three years, and I believe it shows in the final product. I can't wait to see what you all think.