Markdown to Static Site Generator

Project roadmap

1. 01

   Set up the project

   ~1h

   Install Node.js (LTS version) and create a project with TypeScript (tsc --init with strict mode and a Node target), plus markdown-it and gray-matter. Add scripts to build and run the tool. Create an example content/ folder with 5 Markdown pages, including one in a subfolder, and an image. Done when: npm run build compiles the tool, and running it prints Hello.

2. 02

   Find the Markdown files

   ~1h

   Write a function that reads the input folder recursively with fs.promises.readdir (with the withFileTypes option) and returns every .md file's path relative to the input folder, sorted. Collect other files, such as images and CSS, separately so they can be copied later. Done when: the tool prints every Markdown file in content/, including the one in the subfolder.

3. 03

   Convert Markdown to HTML

   ~1.5h

   For each file, read it, separate the front matter with gray-matter (title, and an optional order number for the menu), and convert the rest to HTML with markdown-it. Define a Page type with the input path, output path, title, order and HTML. If a page has no title, use its file name. Done when: every file becomes a Page with the correct title and HTML.

4. 04

   Apply a layout with navigation

   ~1.5h

   Create a layout.html template with placeholders such as {{title}}, {{nav}} and {{content}}. Build a navigation menu from all pages, sorted by order and then title, with links that work from any folder depth (relative links), and mark the current page. Escape page titles so special characters don't break the HTML. Done when: each generated page has the layout, the correct title and a working menu.

5. 05

   Write the output site

   ~1.5h

   Write each page to the output folder (default dist/), replacing .md with .html and keeping the folder structure, creating folders with fs.promises.mkdir and the recursive option. Copy the other files as they are, and clear the output folder before each build. Done when: opening dist/index.html in a browser shows the site, and the links and images work.

6. 06

   Add command-line flags

   ~1h

   Accept --input and --output folders and a --watch flag that rebuilds when a file in the input folder changes (with fs.watch). Print how many pages and files were written and how long the build took. Show a clear error for a missing input folder. Done when: ssg --input content --output public builds into public/, and --watch rebuilds after an edit.

7. 07

   Write tests

   ~1.5h

   Write tests with Vitest (or Node's built-in node:test) for the front matter and title handling, the navigation order, relative links from a subfolder, and a full build of a small test folder into a temporary directory, checking the generated files. Done when: npm test passes.

Resources

• Docsmarkdown-it
• Docsgray-matter (front matter parser)
• DocsNode.js file system (fs) documentation
• DocsTypeScript handbook