README Writer
Describe your project or paste rough notes. Get a complete README with the sections real developers expect, no padding.
New to this? Read the guide.
What it produces
Real output from this tool, not a mock-up.
What went in
- What your project is
- A small CLI that watches a directory of markdown files and rebuilds a static site when anything changes. Built it because the existing options were either too heavy or needed a config file to do anything. Zero config by default, reads frontmatter for title and date, outputs plain HTML with no client side JavaScript. Supports a custom template. Install with npm, run with a single command pointed at a folder.
- Tech stack
- Node 22, TypeScript, marked for markdown parsing, chokidar for file watching. No framework.
- Project type
- CLI tool
- Sections to include or exclude
- Include a quick start near the top. Include a section on the custom template format. Do not include a contributing section or a code of conduct, it is a personal project.
What came back
# mdsite A small CLI that watches a directory of markdown files and rebuilds a static site whenever anything changes. No config file needed, no client side JavaScript in the output. ## Quick start ```bash npx mdsite ./content ``` Point it at a folder of markdown files and it builds a static site, then watches for changes and rebuilds automatically. ## Install ```bash npm install -g mdsite ``` ## Usage ``` mdsite <directory> ``` ```bash mdsite ./content ``` ```bash mdsite ./content --template ./templates/post.html ``` Run it pointed at a directory of markdown files. It reads frontmatter for title and date, converts each file to plain HTML, and rebuilds when a file changes. ## Options or flags - `--template`: path to a custom HTML template to use instead of the default output ## Custom template format By default mdsite outputs plain HTML with no template needed. If you pass `--template`, it expects an HTML file with placeholders that get replaced per page: - `{{title}}`: the title from frontmatter - `{{date}}`: the date from frontmatter - `{{content}}`: the rendered HTML body of the markdown file Example template: ```html <!DOCTYPE html> <html> <head><title>{{title}}</title></head> <body> <h1>{{title}}</h1> <p>{{date}}</p> {{content}} </body> </html> ``` Frontmatter in your markdown files should look like: ``` --- title: My Post date: 2024-01-15 --- Content goes here. ``` ## Tech stack - Node 22 - TypeScript - [marked](https://www.npmjs.com/package/marked) for markdown parsing - [chokidar](https://www.npmjs.com/package/chokidar) for file watching No framework, just a CLI script.
When to use it
Use this when the project works and the README is a single line. It writes the sections developers actually look for, in the order they look for them, without padding it out with badges and a table of contents nobody needs.