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
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.
- How will I write my blogposts?
- What tools will I use to compile the blog?
- 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 (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 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. 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.
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.
Top comments (1)
Very informative. Im planning to post similar content like yours. I will make it as a guide. Thanks!