Blog / Build with AI /
Building a markdown notes site with AI
Notes apps come and go. Plain text files do not.
That is the argument for Markdown: it is just text with a few symbols, so any editor on any device can open it, and it will still open in twenty years. A heading is # Heading. A list is lines starting with a dash. A link is the link text in square brackets followed by the address in round ones.
The finished thing here: a folder of .md notes that a short script converts into a tidy set of web pages, with an index linking to each one. You write notes the way you like. The site builds itself.
Why bother turning notes into a site?
- Readable anywhere. Open them on your phone or share a link.
- Searchable and linkable. A website is easier to browse than a folder.
- A small public notebook, if you want to share what you learn.
- A lesson in how static sites work. Many blogs and documentation sites are built this way.
And it is a good size of project: one script, no database, nothing to log into. Choosing your first AI project explains why that matters.
What you need
- Node.js installed (a free download). It runs JavaScript outside the browser.
- A text editor.
- A project folder with a
notessubfolder containing a few Markdown files.
Create two or three sample notes first, with a heading and a few lines each. You’ll test with them.
Step 1: write the brief
Build a Node.js script that reads every .md file in a folder called notes, converts each to HTML using the marked library, wraps it in a simple HTML page template with a title and basic CSS, and writes it to a folder called dist. Also create dist/index.html listing every note as a link, sorted alphabetically. Use ES modules. Keep it under 50 lines and explain how to install and run it.
The constraints help: one library, one input folder, one output folder.
Step 2: what the script looks like
You will get something close to this. The point is to recognise the parts, not to type it:
import { marked } from "marked";
import fs from "node:fs";
fs.mkdirSync("dist", { recursive: true });
const files = fs.readdirSync("notes").filter((f) => f.endsWith(".md"));
for (const file of files) {
const name = file.replace(".md", "");
const body = marked.parse(fs.readFileSync(`notes/${file}`, "utf8"));
const page = `<!doctype html><meta charset="utf-8"><title>${name}</title>
<main>${body}</main>`;
fs.writeFileSync(`dist/${name}.html`, page);
}
In words: make an output folder, find the Markdown files, convert each one, wrap it in a page and save it.
To run it, you will usually do the following in the project folder:
npm init -yto create a package file.npm install markedto add the library.- Add
"type": "module"topackage.jsonso the import syntax works. node build.jsto run it.
If it errors, paste the exact error message back to the assistant. Error messages are the most useful thing you can give it.
Step 3: add the index
The script should also make index.html, a list of links. That is a loop that builds a list item per file. Ask for it as a separate change after the first part works, not all at once. Iterating with AI explains the habit.
Step 4: make it pleasant
Once it works, improve one thing at a time:
- A shared stylesheet so every page looks the same.
- Readable width: a max width of around 70 characters of text.
- Navigation: a link back to the index on each page.
- Dates: read them from a line at the top of each note, or from the file’s modified date.
- Titles: use the first
#heading instead of the filename. - Search: a small box that filters the index list in the browser.
Each is a separate prompt. Resist building all of it on day one.
Watch out for these
- Unsafe HTML. Markdown can contain raw HTML. If only you write the notes, that’s fine. If anyone else can add notes, you need to sanitise output. Security basics for AI-built web apps explains why.
- Private notes by accident. A notes folder often holds things you’d never publish: passwords, client details, half-formed opinions. Keep a separate folder for what is public, and build only from that.
- Odd filenames. Spaces and capital letters in filenames make messy web addresses. Use lowercase and hyphens.
- Broken internal links. If one note links to another with a
.mdending, the web version needs.html. Ask the script to rewrite those. - The library changing. Libraries release new versions. If a later install behaves differently from your tutorial, check its current documentation.
Hosting
The dist folder is just static files. Upload it to any static host, or even open the files straight from your computer. If you do publish it, add a title and description for search, and think about whether you want it indexed at all. A private notebook can use a “noindex” tag, and password protection from your host if needed.
Alternatives, and when to use them
You do not need to build this yourself. Ready-made tools exist, such as static site generators and note-publishing services. Building your own is worth it if you want to understand how the pieces fit, or you want something tiny and exactly shaped to your needs.
If you already run WordPress, you might just paste Markdown through a plugin or editor block. But a small script teaches you what those tools are doing under the bonnet.
Key takeaways
- Markdown files are the most durable way to keep notes.
- A short script can turn a folder of them into a website.
- Keep the first version minimal: one library, one folder in, one folder out.
- Build upgrades one at a time and test with a few notes.
- Keep private notes out of the public folder.
Related reading
- Building a portfolio site with AI
- Adding analytics to a site you built with AI
- Building a page notes extension with AI
What would you put in your notes folder first: things you are learning, or things you want to be able to find in a hurry?