How I Built My Blog
Tags: octograd2020
Published: 2020-05-20 14:06:35

## My Final Project
In the end, I built a small static site generator to build and deploy my Markdown-based blog to GitHub Pages.

## Demo Link
https://jinayjain.github.io/blog/

## Link to Code

{% github https://github.com/JinayJain/blog %}

# How It Works

The main idea behind this project is to build a **static site generator**,
something that will compile my blogposts into a single, deployable website.
The term, though, can mean many different things depending on how the system
is implemented, so I had to answer some questions before I started building.

1. How will I write my blogposts?
2. What tools will I use to compile the blog?
3. How will I deploy the blog?

What I ended up choosing was to use Markdown as my syntax for writing, NodeJS
to build the project, and GitHub pages to deploy (using the `gh-pages` NPM
package). These initial choices outlined the general series of steps needed to assemble my blog generator.

## Rendering Markdown Files

[Markdown](https://en.wikipedia.org/wiki/Markdown) (the syntax language for
GitHub README's and many texting platforms), has a relatively simple syntax
that enables a writer to define very basic text editing features: headers,
bolding/italics, links, or code. This allows programmers to easily convert Markdown into other formats like LaTeX documents, Beamer presentations, and HTML pages. In fact, the [pandoc](https://pandoc.org/) tool includes native support for converting markdown into a plethora of other file formats, allowing the user to control much of the styling and formatting of the document.

If I wanted to, I might have created a simple parser for Markdown myself.
But---of course---there was a neat NPM package that did the work for me,
[markdown-it](https://github.com/markdown-it/markdown-it). In my code, I
simply read the desired Markdown file as a string and the simple
`md.render(source)` would parse the document and convert it into HTML tags. `markdown-it` has several extensions that add extra syntax support for more specific needs. I added the `markdown-it-katex` package to include math equation rendering.

While rendering, a line like

```
$$ f(x)=\int_{0}^{1} x^2 dx $$
```

is converted into actual LaTeX-rendered math equations.

{% katex %}
f(x)=\int_{0}^{1} x^2 dx
{% endkatex %}

which makes life much easier than trying to explain a loss function with convoluted notation like `(y_i - p_i)^2`.

I plan on adding some other syntax features as my needs evolve, but the ability to extend the core funcitonality of Markdown is why it's such an appealing language for developers.

## Capturing Post Metadata

Some information about the posts---the title, creation date, URL,
etc.---shouldn't be directly shown to the user, so I created a way to handle
that data first before feeding it into `markdown-it`. Most SSG systems either
include this metadata in separate files or within a special section in their
Markdown called the front matter. I chose to use the latter, which meant my
Markdown files would have a small section above the Markdown storing the
metadata. For example, here's the front matter for this post:

```
---
title: How I Built My Blog
author: Jinay Jain
description: A reflection on how I created the static site generator behind this blog.
date: 1588601471
---
```

Those are only a few of the things I've added to the blog and I hope to keep updating the system as my requirements change, but for now, these few features are all I need to get started with blogging.