Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 39 ยท Projects and Practice

Project: A Static Page Builder from Markdown

Build a tiny static site generator in Node - read Markdown files with front matter, render HTML with heading anchors, create an index and navigation, validate links, and write finished pages.

Static site generators such as Jekyll, Hugo, Eleventy and Astro all do the same job: turn a folder of Markdown files with front matter into a website. In this project you build a miniature one and see every part of this chapter at work: front matter parsing, a Markdown renderer, a template, an index page, navigation, and a link check that fails the build when a link is broken.

flowchart TD
  A["content/*.md"] --> B["split front matter / body"]
  B --> C["validate metadata"]
  B --> D["render Markdown to HTML + headings"]
  C --> E["sort by order"]
  D --> F["page template"]
  E --> G["index page + navigation"]
  F --> H["link check"]
  G --> H
  H --> I["write dist/*.html"]

Each Markdown file becomes a page; metadata drives the index and navigation.

Design

  • Input: an object mapping file names to text (in the sandbox, in place of a folder read with node:fs).
  • Metadata: title, order and an optional draft: true. Missing title or order is a build error.
  • Output: dist/<slug>.html for each page, plus dist/index.html.
  • Rendering: a small subset (headings with anchors, paragraphs, lists, code, emphasis, links). All text is escaped.
  • Checks: every internal link must point to a page or anchor that exists. Broken links fail the build.

The builder

Node.js A tiny static site generator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The good build produces index.html, guide.html and about.html (the draft is skipped), with the pages ordered by order, so Guide comes before About. Notice that the <b>now</b> in the guide was escaped rather than passed through. The broken build lists both problems (the file without front matter and the stale anchor) and writes nothing: failing the build on bad input is the point of the link check.

What a real generator adds

  • Files and watching: read with fs.readdir, write with fs.writeFile, rebuild when a file changes.
  • A real Markdown library (markdown-it, marked, unified/remark) and a real YAML parser for front matter; see Writing a Markdown-to-HTML Converter for why.
  • Templates with partials and loops (Liquid, Nunjucks, Blade, Go templates).
  • Collections and taxonomies: group by tags and generate tag pages.
  • Assets: copy images, hash file names, minify CSS.
  • Feeds and sitemaps: an Atom or RSS feed (XML) and a sitemap.xml generated from the same page list.
  • Incremental builds: skip pages whose source hash has not changed.
  • Security: sanitise output if authors are not fully trusted (Data Format Security).

Extensions to try

  1. Generate feed.xml (Atom) with the title and slug of every page, escaping the text.
  2. Support tags: [a, b] in the front matter and generate a page per tag.
  3. Add previous/next links using the sorted order.
  4. Check that no two pages have the same title or slug.
  5. Validate front matter against a schema (Command-Line Data Tools).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What drives the order of pages in the index?

    The builder sorts pages by the numeric order metadata.
  2. 2. Why does the build fail instead of writing pages when a link is broken?

    A build that fails on bad links protects readers from dead ends.
  3. 3. How does the builder handle raw HTML like <b> in Markdown?

    All text is escaped by the renderer; only generated tags become HTML.
  4. 4. Why give repeated headings unique ids?

    Duplicate ids would make links jump to the first match, so repeats get a numeric suffix.

Summary

  • A static site generator is front matter + Markdown + template + index + checks.
  • Metadata drives sorting, navigation and drafts; validation errors fail the build.
  • Heading ids, a table of contents and link/anchor checking come from the heading list.
  • Escaping every piece of text keeps the generated HTML safe.
  • Real tools add watchers, plugins, assets and feeds on the same skeleton.

Next: Practice: Data Format Exercises