How I made this website

2020-08-06 update: I have rebuilt the site using Franklin.jl, a static site generator using the Julia language. Franklin is very nice for working with a mixture of text, math, and code (especially Julia code). I'm keeping the original post as-is for the sake of completeness.

2015-04-02

You might be like me: a person with some computing skills but no experience in web development, who needs a simple website for personal or professional purposes. You don't mind learning a few new things–-especially getting familiar with tools you can use elsewhere too–-but you don't have a lot of time to spare. There are many ways to get a website going, but here's how I decided to proceed. This will likely be most interesting to people who, like me, are in an academic environment and work in a quantitative discipline.

I was looking for ways to build a simple static site (no server-side scripts or databases) with the following characteristics:

Easily maintainable.
Uses standard text file formats and isn't linked to a specific publishing platform or content management system.
Can typeset mathematics for the web, for example: \(\bar{X}=\sum_{i=1}^n X_i\) and

\[\Phi (x) = \int_{-\infty}^x\frac{1}{\sqrt{2\pi}\sigma}\exp\left({-\frac{(t-\mu)^2}{2\sigma^2}}\right)dt,\]

preferably using a \(\LaTeX\)-like input format.

Supports off-line development of the site with publishing by simple file transfer to the server.
Produces sites that look okay on mobile or desktop browsers.

To achieve this, I'm using:

Markdown to write the site's content in plain-text files,
Pandoc to convert these into HTML documents,
CSS to style the website, and
A couple of other utilities to make site maintenance easier.

The excellent (and free) pandoc "universal document converter" is the primary tool that makes this arrangement possible. It is a command-line software utility that can transform numerous types of document formats into each other.

Pandoc implements a full-featured flavor of markdown. Briefly, Markdown is a system for encoding rich document formatting (different typefaces, headings, list formats, etc.) in a plain-text file using simple text markups. An important goal in Markdown is to ensure that the text document remains comfortably human-readable. The original Markdown is found here. It has spawned numerous variants that are now used on different websites and software products.

From what I can see, the pandoc markdown implementation includes almost any feature you could reasonably want^[1]. Most importantly, it has support for mathematical typesetting using latex, so if you already know latex you don't need to learn anything new. It also supports a variety of ways of getting your math to display on web pages; I'm using the MathJax option. Another handy feature is the ability to specify that certain files be included in your HTML document before and after the body. That way you can set up headers and footers that are re-used across the different pages of the site.

If you use R and RStudio, it is worth learning some Markdown, as you can use it to create documents that mix text, math, code, and output (see here)^[2].

Cascading style sheets (CSS) is a system for controlling how web page content is displayed. By using a global stylesheet you can separate content and format on your website, and easily change the style of all pages in the site by just editing the stylesheet. It's not too hard to learn the basics of CSS, and it's not hard to find a markdown-related stylesheet online that you can learn from and edit.

So the process of producing or updating the website is:

Decide on the folder structure for the site.
For each desired .html file, produce a .md (markdown) file with the content.
Process each .md file into .html using pandoc. In the command line, tell pandoc which header and footer files to include, and which stylesheet to use.
Publish the folder structure to the server, e.g. by ftp.

Finally, here are a few extra points I've found make things easier:

I've started using git for version control of the website. If you don't use such a system and you write code or long documents, it's definitely worth checking out.
One problem with the procedure for publishing the site is that you have to run pandoc separately on all markdown files you've changed. It helps to automate this process. I use the awesome file manager XYplorer and with it I've created a script that allows me to process all .md files in my website's folder structure with one click.
If you make hyperlinks among your pages in a way that's suitable for use on your web server, you won't be able to use the links when you simply open the .html files locally on your computer. You need a local server on your machine to test your website. An easy way to do this on Windows 8 is using the built in Internet Information Services.

[1]	Including gratuitous footnotes.

[2]	Rmarkdown also uses pandoc + latex to produce documents.