How was this site built

How was this site built

website design programming

I described building this site in another post, and thought I'd add some detail. The previous version of this site was built using Hugo, that used Go. I thought I'd change it entirely and build a custom static site generator using Node.js, which is more understandable and usable, and add a rich set of regular and extended markdown support (things like LaTeX math formulas, tables, and some specialized cases like Sanskrit, given my interest in it). The site is responsive and supports both light and dark themes.

I also had some fun creating a KidZone page where my kids could submit articles. They also print out their daily math homework from a Linear-equations, Simultaneous-equations, and Integer arithmetic generator on that page :-)

I built this entire thing with Cursor.ai (and generated the landing page vide with Sora). I described my experience with AI tools in the other post.

Site Architecture Overview

Mainly implemented in JavaScript. Here's how it's structured:

Core Technologies

  • Node.js: The site uses Node.js for the build process
  • Handlebars: For templating HTML pages
  • Marked: For converting markdown to HTML
  • KaTeX: For rendering mathematical formulas
  • Prism.js: For syntax highlighting in code blocks
  • Firebase: For backend functionality (likes, views)

Project Structure

  • content/posts/: Contains markdown files for blog posts
  • templates/: Contains Handlebars templates for page layouts
  • js/: Contains JavaScript files for the build process and client-side functionality
  • css/: Contains CSS files for styling
  • public/: Contains static assets
  • posts/: Output directory for generated blog posts

Build Process

The site is built using a custom build script (js/build.js) that:

  1. Reads markdown files from the content/posts/ directory
  2. Processes frontmatter metadata using gray-matter
  3. Converts markdown to HTML using marked with custom renderers
  4. Applies Handlebars templates to generate HTML pages
  5. Outputs the final HTML files to the appropriate directories

Markdown Formatting

The site uses the marked library to parse markdown with several custom extensions:

Basic Markdown Features

  • Headers: Using #, ##, etc.
  • Emphasis: Using *italic* and **bold**
  • Lists: Ordered and unordered lists
  • Links: Using [text](url)
  • Images: Using ![alt](src)
  • Code blocks: Using triple backticks with optional language specification
  • Blockquotes: Using >

Custom Markdown Extensions

Quote Boxes

::: quote
This is a quote box
:::

YouTube Embeds

{% youtube id="videoId" %}

Twitter Embeds

{% tweet url="tweetUrl" %}

LaTeX Math Formulas

The site supports LaTeX math formulas using KaTeX with multiple syntax options:

  1. Inline Math:

    • Using single dollar signs:
    • Using \\( and \\):

  2. Block Math:

    • Using double dollar signs:
    • Using \\[ and \\]:
    • Using math code blocks:
      \int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}

The LaTeX renderer (js/latex-renderer.js) processes these formulas during the markdown conversion by:

  1. Identifying math expressions in the markdown
  2. Temporarily replacing them with markers
  3. Rendering them using KaTeX
  4. Replacing the markers with the rendered HTML

Sanskrit Verses

The site implements a custom markdown extension for Sanskrit verses:

:::sanskrit
[Sanskrit text in Devanagari script]
---
[Transliteration in Latin script]
---
[English translation]
:::

The Sanskrit renderer processes these blocks and applies specialized styling with a parchment-like background and appropriate typography for each section.

Tables

The site supports standard markdown tables with additional styling and responsive behavior:

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Tables support alignment options using colons in the separator row:

  • Left-aligned (default): | :--- |
  • Center-aligned: | :---: |
  • Right-aligned: | ---: |

Tables are styled with:

  • Clean borders and rounded corners
  • Header row with distinct background
  • Responsive behavior (horizontal scrolling on small screens)
  • Support for markdown formatting within cells (bold, italic, links, code)

Example of a table with alignment:

| Left-aligned | Center-aligned | Right-aligned |
| :----------- | :------------: | ------------: |
| Text         | Text           | Text          |
| Left         | Center         | Right         |

Getting Started

Prerequisites

  • Node.js (v14 or higher)
  • npm

Installation

  1. Clone the repository

    git clone https://github.com/yourusername/personal-website.git
cd personal-website

  2. Install dependencies

    npm install

Development

  • Build the site: npm run build
  • Start local server: npm run serve
  • Run tests: npm test

Summary

This site is a custom-built static site with a sophisticated markdown processing system that extends standard markdown with several custom features:

  1. Core Architecture: Node.js-based static site generator with Handlebars templating
  2. Standard Markdown: Support for all common markdown features
  3. Extended Markdown: Custom syntax for quotes, embeds, media, and responsive tables
  4. LaTeX Support: Comprehensive support for mathematical formulas using KaTeX
  5. Sanskrit Support: Custom block syntax for Sanskrit verses with specialized styling
  6. Table Support: Enhanced markdown tables with alignment options and responsive design

The custom markdown extensions provide a rich blog-authoring experience while maintaining a clean and performant static site architecture.

80