I have failed many times in creating a website (or a blog) for myself. I tried blogger, WordPress and even jekyll with GitHub pages. None of them had the extreme simplicity I wanted or I was too stupid to figure it out. Running out of options, I decided to create a simple website myself.

I wanted to do my writing in markdown since the syntax is simple, easy and intuitive. Then these markdown files can be easily converted to plain HTML using a converter. Since, I wanted to write technical / scientific articles, rendering math and code highlighting were essential as well.

So, I wrote a small bash script that takes markdown files as input and convert them into HTML with code highlighting and beautiful math rendering. Bash script does the markdown to HTML conversion using Pandoc. MathJax is used for rendering math.

Also, the script was programmed to add a default header (contains the navigation bar, MathJax snippet for CDN etc.) and a footer (contains the last updated time of the page) to each each HTML file it converts. After the HTML file is generated, it has to be manually linked into the appropriate place in the existing website structure.

Structure of the web-page

Each web-page is a combination of three divisions: header, section and footer. As mentioned earlier header contains navigation bar and other required code snippets. section contains the HTML generated from the markdown file and the footer contains the last updated time of the page.

These three parts are combined by the bash script once it is invoked to convert a markdown file to a HTML file. Code for header is in header.html and it is added (by the bash script) at the beginning of every web-page created. Then the converted content from the respective markdown file is added in section division. A small piece of HTML code hard-coded in the bash script will be appended as a footer for each new web-page.

Below is a step by step description of what I did.

Install Pandoc

First I had to install a markdown to HTML converter. I googled a bit and found out that Pandoc suits the job as it provides code highlighting (along with a set of nice functionalities which can be found here) as well. Follow the installation guidelines found here to get it installed in your system.

Create header.html

header.html contains a bit of style information introducing the basic structure (header, section, footer) of the web-page and some meta data. Also, the code snippet to use MathJax has to be included in header.html if you want to render mathematics. You can find the code here.

Note: header.html ends with an unclosed <div> to enable content to be appended.

Click here to see my header.html

Create the bash script

Next I wrote a bash script and named it build.sh. This script takes a markdown file as input and outputs a HTML file after prepending header and appending footer. Code for footer is hard-coded in the bash script.

Below is the command to convert a file named index.md to HTML. The output file is automatically named index.html.

sh build.sh index

Note: You have to omit the extension .md. If you run the script without providing a file name, all the markdown files found in the current directory is converted to HTML files.

Note: Don’t forget to add -s option when calling Pandoc command in bash script to make sure that the output HTML file is a standalone version containing all CSS style instructions used for code highlighting.

Click here to see my build.sh

Create the index.md file

I created a index.md file (which will be converted into index.html) with a brief introduction about myself. index.md after conversion to HTML serves as the main page of your website.

Click here to see my index.md

Adding content

When you want to add more content, just write a markdown file, convert it to HTML using the script and then manually link it in the required place of the main site. For example, I linked this page under the blog section. You can deploy this minimal website in a server. I used Github pages to host mine.

To invoke the math mode in markdown one can use $$..$$, \[..\] or \(..\). Read more about this in MathJax docs. Here is an example rendering the formula for roots of a quadratic equation using MathJax. MathJax code for doing this is (in markdown):

$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$

Rendered output will be:
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$

Code highlighting is enabled by default in Pandoc. There are several ways to invoke code highlighting through markdown syntax. One method is to use ``` at the beginning and end of the block followed by the coding language.

The following code block,

```python
for i in range(10):
    print "This Works !!!"
```

will be converted into:

for i in range(10):
    print "This Works !!!"