This post is an overview of how to get up and running with a dissertation blog. I offer my own blog, “Queer Tools,” as an example, where I post my developing thoughts and share drafts of my work in progress.

To create the blog, I use a combination of open-source tools that are relatively easy to get up and running. First, for the actual writing, I use Markdown, a lowkey “markup language” for writing in plain text. Second, I use Github Pages to host the blog online for free. Then, I use the Reverie theme (powered by Jekyll) for managing my blog’s appearance, giving it a streamlined look. Finally, I’ve added digital annotation functionality with Hypothesis so people can comment on my drafts. Together, these tools create a public facing record of my work in progress, allowing interested folks to read and comment.

In what follows, I provide an overview of how to get your own blog up and running, with links to tutorials for each step. At first, some of these steps can seem overwhelming, but it is actually pretty straightforward as long as you follow the instructions for your Operating System. By the end of this workshop, not only will you have a custom blog, you will also have learned how to install programs with the command-line, which is essential for doing more complex digital projects. Also, developing familiarity with open source tools like Markup, Jekyll, Git, and Hypothesis allows you to create your own workflow that suits your academic goals. That being said, some minimal knowledge of the command-line is highly recommended, so please check out our command-line tutorial if you need a primer or refresher. If you get stuck, please reach out to the Digital Fellows for help!

Before getting started, make a new project folder. You can use the command-line to make the new folder and navigate inside it:

$ mkdir my-project

$ cd my-project

Now, the first step to building the blog is to get Jekyll working on your computer.

Jekyll

Jekyll is a “static site generator” that transforms plain-text files into websites. In simple terms, Jekyll takes text written in markdown (see Digital Fellow Rafa Portela’s instructions on using markdown), and automatically applies layouts and styling. By using Jekyll, you avoid the headache involved with databases, components, and styling that comes with building a website in the usual way.

To get the Jekyll website up and running, we need to install some prerequisites, specifically Ruby (version 2.5 or later), Jekyll, and Bundler. This process will be different according to your operating system and version, and you may even have them pre-installed on your computer, depending on your OS. For Windows, follow these instructions for installing Ruby, Jekyll, and Bundler for Windows. For Mac OSX, you will need to first install Ruby for Mac OSX, and then install Jekyll and Bundler for Mac OSX.

Warning: this is the most complicated step, as the process depends on your OS and specific system requirements. If you are not familiar with using your computer’s command line, or run into errors, please do not hesitate to reach out to the Digital Fellows.

Like I said, the process will be different depending on your system requirements, so be patient and take time to read the relevant instructions. Sometimes a quick google search that includes your operating system will be most helpful, like “Catalina install jekyll,” for example.

To test that the previous installations are working, open your command line, navigate to the project folder, and run

$ bundle exec jekyll serve

The output should look something like the following:

Configuration file: /Users/filipacalado/Desktop/one-more-test/_config.yml

     Source: /Users/filipacalado/Desktop/one-more-test

     Destination: /Users/filipacalado/Desktop/one-more-test/_site

 Incremental build: disabled. Enable with --incremental

    Generating...

     Jekyll Feed: Generating feed for posts

                  done in 0.616 seconds.

 Auto-regeneration: enabled for '/Users/filipacalado/Desktop/one-more-test'

    Server address: http://127.0.0.1:4000/

  Server running... press ctrl-c to stop.

Now, copy the server address (in the above example, you can see it’s http://127.0.0.1:4000/) into your web browser, and hit enter. You should see a sample site that says “Welcome to Jekyll.” To stop the server, hit control-c. You can start it back up again with the command “bundle exec jekyll serve.”

You now have a Jekyll site running on your local machine! I would spend some time playing around with this new space, adding new content. Check out Jekyll’s excellent documentation about creating posts, for starters. Once you get more comfortable with Jekyll, you can experiment with theming, that is, customizing the appearance of your blog. Jekyll themes allow you to choose a specific look, and many of them are ready “out of the box,” so you can focus on just creating the content. Personally, I use a theme called Reverie which offers a clean one-column layout. Other nice layouts include Hyde, which you can see at work in Jeffrey Moro’s neat dissertation blog.

Github Pages

The next step is to get this thing online, so others can see your site on the internet. For this task, I choose Github Pages because it offers free web hosting. Additionally, because Github Pages runs on Git, a software that offers version-control, it automatically creates backups every time you “push” (or save & publish) your site. This comes in very useful if, for example, you decide you want to find something you deleted or revert to a previous version of your draft.

If you don’t already have a Github account, create one on GitHub.com. Then, you need to create a github repository, initialize the repository locally, and add that repo to github. Follow these instructions for creating, initializing, and pushing your repo to Github. (Note: For the future, you’ll want to read up on a few basic commands for working with Git, and be sure to check out our workshop on using Git/Github on the command line).

Once you finish those steps, you need to activate Github Pages on your repo. To activate Github Pages, navigate to your repo’s main page, then click on the “Settings’ tab. Scroll down to the “GitHub Pages” section, and in the box that says “Source,” select “Master,” then “Save.” In a few minutes, you should see your new site at www.your-username.github.io/your-project-name/ (with your name and project in the place of your-username and your-project-name). In case you have any issues with the site, this page is a good place to start troubleshooting Github Pages and Jekyll. Also, if you notice that the styling is off (a common error), read through this post about adding your the correct styling path to your config file.

Hypothesis

Still with me? We are almost there! The last step is to add Hypothesis, a digital annotation tool that allows users to comment on your pages. I’ve used Hypothesis to share drafts in progress with my writing group. Because the tool is embedded in the web page, readers don’t have to download or install anything, they can just sign in and comment directly on my writing. This creates a very seamless way of getting feedback and participating in asynchronous conversations about my work.

To add Hypothesis, simply copy and paste the following code somewhere on that page’s markdown file where you want the annotation tool to appear (you can copy/paste the code snippet from here)

Save the page, and reload. The hypothesis toolbar should show up on the right-hand side.

Congratulations! You now have a fully working, public-facing, and annotatable blog! Remember, however, that this tutorial isn’t the only way to get up and running with a blog on Jekyll and Github Pages. The above process is just my preference, and there are so many other options for getting this done. If the above is difficult for you, consult one or more of the resources below, which offer approximately the same end result, just with different steps:

• Amanda Visconti’s in-depth guide to working with the command line, Jekyll, and Github pages.

• Jonathan McGlone’s quick guide to “Creating and Hosting a Personal Site on GitHub.”
• Landing page with official Github documentation for setting up a Github Pages site with Jekyll & the walkthrough for downloading Jekyll dependencies and activating Github.
• “Plug and play” with a Jekyll theme, such as Reverie or Poole.

This entry is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license.