I’m psyched about this little website. This post is about the tools and resources I used to make it.
In summary, this is a static website made with Jekyll software using the code editor called Atom to write posts in Markdown language. I also added a wishlist to the end, mostly to keep track of tools and tricks I may want to add.
Most of the internet we interact with on a day-to-day basis is “dynamic,” meaning we request something from a web server (e.g. click on a Facebook post or search for something on Amazon), which then talks to a database to pull all the relevant information and fill in a template (e.g. post content + comments, or product page with images, ratings, ads, etc.). The “static” web is much more old school: ask for something and the server gives you something, no database and comparatively little processing. Whatever is on the server has to be pretty much prebuilt and ready to go. This process is much simpler, faster, and more secure. The basic protocols are old and well established, unlikely to change or break. For most online writing, such as a blog, static is the way to go, especially if it is likely to be consumed over a mobile internet connection.
Jekyll is an open-source suite of open-source software for making static web pages.
The basic idea is create a workflow that starts with just writing, followed by a predefined file structure and styling format to store all your stuff and make it pretty, and finally automatically translate it all into something a web browser can use. Jekyll also integrates nicely with GitHub, which will host the site for free. GitHub also makes my favorite text editor, Atom. This leads to an integrated workflow: write in Atom → build in Jekyll+GitHub → publish on GitHub.
I found out about Jekyll from the Rebecca Stone, who is writing the wonderful py-wsi package. (This package makes massive digital pathology images tractable for deep learning.) As I read through her blog, I found this post on Jekyll and why she switched from WordPress. I read a few more posts like hers and was converted.
Some user-friendly Jekyll walkthroughs:
I stole the layout of this site from vangeltzo.com, whose beautiful design was Jekyll-ified (with permission!) by TaylanTatli on GitHub. I’m not the only one using this theme, by any means.
Jekyll themes are abundant online, generally easy to fork (“fork” means “copy for your own use without affecting the original”), and often well commented so they are straightforward to customize.
I had two basic requirements for my theme. First, it had to be pretty. Second, I wanted a responsive split screen. “Responsive” means it can adapt itself to look nice on any device from a phone to a huge desktop monitor. The split screen confines the content to an easily readable width on the right and gives consistent navigation on the left. The 50/50 split screen is a little extreme, but I think I like it this way. If I ever want to change it to something like 66/33, it is quite easy.
I’ll say more about specific choices, such as color, logo, and tagline in another post.
You can write all of your code entirely within GitHub, which has its own text editor. The above tutorials use this approach to make it easy to start. There’s nothing wrong with that.
A friend of mine, a fellow CCLCM student who is a much more legit programmer than me, recommended Atom, and I fell in love with only minimal doses of digital amortentia. It is ridiculously (almost dangerously) extensible, with community-supplied packages for an incredible breadth of programming languages and applications.
For the nerds, for example, it has full support for LaTeX and all the typesetting, figure-making, citation-porn, and mathy goodness you can handle. One of my favorite workflows is to write something in Markdown to get the basics down with minimal fuss in an easier language, and then use Pandoc to convert it to LaTeX, followed by any futzing with the LaTeX (if you like) before outputting to PDF. You can also (!) combine the languages rather seamlessly.
Here’s a post that details a full plain-text academic workflow with Atom.
For the poets, it can be a gorgeous and focused writing environment with infinitely more flexibility than Word. Here’s a post that describes how one creative writer uses Atom. The Zen package alone should entice you Hemingway types, but also take a look at the writing assistance tools detailed in previous hyperlink or the hyperlink in the next paragraph.
For me, the coolest thing is that I can have one central hub to do it all, with very little need for Word. If I use Atom to push things to GitHub, it also nearly replaces Google Docs for keeping everything safely in the cloud (caveat for the latter:as long as I don’t mind making my work public).
Note from 2019: I switched to VS Code. It’s very similar to Atom, but faster.
Markdown is a “text-to-HTML conversion tool for web writers [that] allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).” (click image or here for source).
It’s inspired by the way people used to mark up their plain-text emails to make them more readable, with all the “#” and “-“ and “***” you can handle. Therefore, if you look at the source of something written in Markdown, it’s still pretty darn legible. Those of you who have read and written medical charts, many of these are still in common use (the “#” problem list, for example).
Here are examples from a great GitHub Markdown cheatsheet. First is the code and then the rendered text.
Emphasis, aka italics, with *asterisks* or _underscores_. Emphasis, aka italics, with asterisks or underscores.
Strong emphasis, aka bold, with **asterisks** or __underscores__. Strong emphasis, aka bold, with asterisks or underscores.
Combined emphasis with **asterisks and _underscores_**. Combined emphasis with asterisks and underscores.
Section with a hashtag:
# H1
Section with a hashtag:
Section using underline style to accomplish the same thing:
Alt-H1
======
Section using underline style to accomplish the same thing:
Pretty cool, eh?
.md file in your favorite text editor.---
layout: post
title: "On the tools used to make this website"
toc: false #table of contents
categories:
- technical
tags:
- jekyll
- markdown
- atom
- hosting
- static web
- blog
- technical
---
BUNDLED WITH lines in the gemfile.lock).Integrate fancy plugins