Creating a research website

After making this website, I thought it might be worthwhile to write about some of the things that I learned along the way, with the intention of helping other researchers interested in making a site as well as cataloging what I did so that I don’t forget. To create this site I used Jekyll and GitHub Pages. This is a really nice way to do things because your website is maintained as a GitHub repository and is hosted for free. I’m pretty sure you can even get GitHub to do most of the work for you using their Automatic Page Generator. All you would have to do is start a GitHub account and create a repository called username.github.io (substitute your own username) and you’re on your way.

Everything in the site is written in Markdown, an easy-to-use, text-based formatting language that is used for generating HTML code. There were two additional things that I wanted to be able to do when I was making this site: (1) have links open in new tabs and (2) render style math equations. The first of these was pretty quick to figure out using a simple Google search, plus the fact that Markdown supports raw HTML code.

Jekyll-based sites convert your Markdown files into HTML, so any raw HTML code simply gets embedded in the rest of the code when it is converted (for the most part). The HTML code for opening links in new tabs is just:

<a href="http://website-url.com" target="_blank">link_text</a>

However, instead of http://website-url.com for the url and link_text for the text that the user will click to follow the link, you’ll want to change it to fit whatever you’re linking to. So, for example, if I wanted to create a link to GitHub that opened in a new tab I would just type

<a href="https://github.com/" target="_blank">GitHub</a>

This can be typed directly in the middle of a paragraph or anywhere else in your markdown file (at least I think it can—I’ve never personally run into any problems):

Version control with <a href="https://github.com/" target="_blank">GitHub</a> is a great way to track changes to your code.

Which will show up like this:

Version control with GitHub is a great way to track changes to your code.

Typesetting equations

Figuring out how to typeset equations on a page took a little bit more digging but eventually I found a bit of HTML code that links with MathJax to render equations written in style. For equations, you need to add this line of code to your markdown file. You can also just add it to the HTML layout files and it will be added automatically so that you don’t have to do it every time.

<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

This allows you to write equations using a \\[ ... \\] delimiter surrounding the equation for displayed math or \\( ... \\)for inline equations when you put everything on its own line. Take the following code for example:

The Binomial distribution has the following form:

\\[
P(x \vert p) = \binom{n}{x} p^x (1-p)^{n-x}
\\]

The Beta distribution has two parameters: \\( \alpha \\) and \\( \beta\\).

Which will show up like this on the page:

The Binomial distribution has the following form:

\[ P(x \vert p) = \binom{n}{x} p^x (1-p)^{n-x} \]

The Beta distribution has two parameters: \( \alpha \) and \( \beta \).

The only other thing that I changed after this was switching from the default MathJax rendering to using the SVG style. This was because the equations were showing up in a weird blue color. There is a list of rendering styles that you can access on the MathJax website.


Other than these two additional features, I have been following the typical workflow for using Markdown on a Jekyll-based site. The Jekyll home page is probably the best place to get started for making your own site.