notesmd

A blazingly fast, simple, and quite elegant CLI for turning Markdown notes into a static website.

What is notesmd?:

notesmd is a command line tool that transforms a directory of your markdown notes into a clean, modern, and navigable static HTML site (all custom coded btw). It's built with Bun and TypeScript and prioritizes speed and ease of use above all else.

It reads your .md files, parses metadata like title, author, and date from the front-matter, and then it injects that content into a customizable HTML template. The result is a complete, self-contained website ready to be deployed anywhere.

Key Features

• Blazingly fast: Built on Bun, it's incredibly fast
• Markdown first: Write your notes in standard Markdown with YAML front-matter
• Live-reload server: Run notes watch to start a local dev server that automatically rebuilds and refreshes your browser on any change
• Automatic index page: An index.html is automatically generated with a grid of all your posts, linking to each single one
• Scaffolding: You can get started in seconds with the notes init command
• Zero-config: Works right out of the box with sensible defaults

Why I Created It

When I was in school, I built a very similar tool myself. It was simple, extremely fast, and let me organize my class notes in a way that just made sense to me. I could write in Markdown, and it would quickly generate a site I could browse through. It wasn't pretty, but it was functional.

I found that existing apps like Obsidian, while they were powerful, were bloated for what I needed. I didn't need complex graphs or like an entire damn mountain of plugins, I just wanted to write decent notes and have them somewhat organized.

notesmd is the refined and recoded version of that original tool. It's a modern take on the same core idea: a lightweight, basically no nonsense, note-taking and publishiung workflow that looks great and works better.

Requirements

The only requirement is Bun (v1.0 or later). You can also run this app very similar through an npm package manager. So, npm, pnpm, yarn, etc.

How to Run It

Installation

It is published to the npm registry. All you have to do is install it.

bun install -g @atomisadev/notesmd

Usage & Commands

Here is a complete list of available commands.

notes init [directory-name]

Initializes a new project with a default file structure.

• if [directory-name] is provided, then it creates a new folder
• if you use . or ./ as the directory name, it initializes in the current folder.
• if you provide no name, then it defaults to creating a notes-project directory

Example

# Creates a project in a new folder called "cs112dsa"
notes init cs112dsa

# Create a project in the current folder
mkdir my-blog && cd my-blog
notes init .

notes build

Performs a one-time build, converting your files from the notes directory into a static site in the dist directory.

Example:

notes build

notes watch

This is for development. It starts a live-reloading development server. It will:

• Perform an initial build
• Start a web server (defaults to http://localhost:3000)
• Watch all your source files (notes/, public/, template.html) for changes & will automatically rebuild the site

Example

notes watch

notes serve

Starts a simple static web server for your dist directory, which allows you to preview the production build

Example

notes serve --port 8080

Example Workflow

Here's how you can go from zero to a running site in under a minute:

# 1. Create a new project
notes init cs112dsa

# 2. Go to the new project
cd cs112dsa

# 3. Start the dev server
notes watch

# 4. Open http://localhost:3000 in your browser and start editing your notes