Markdown Notes API

A simple REST API for managing Markdown notes, built with FastAPI. Upload Markdown files, list saved notes, render them as HTML, and run spell-checking on note content — all via standard HTTP endpoints.

This project is an implementation of the Markdown Note-taking App challenge from roadmap.sh.

Features

• Upload Markdown files (.md only) and save them to a local directory
• List all saved notes with their file sizes
• Render any saved note as HTML
• Spell-check arbitrary text and get suggested corrections
• Auto-generated interactive API documentation (Swagger UI)
• Defense against path-traversal attacks on filename inputs

Requirements

• Python 3.9+

Setup

# Clone the repository
git clone https://github.com/dohu012/markdown-notes-api.git
cd markdown-notes-api

# Create and activate a virtual environment
python -m venv venv
# Windows PowerShell:
.\venv\Scripts\Activate.ps1
# macOS / Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Running

uvicorn main:app --reload

The server starts at http://127.0.0.1:8000. Interactive API docs are available at http://127.0.0.1:8000/docs.

API Reference

POST /notes

Upload a Markdown file. The file is saved to the local notes/ directory.

Request: multipart/form-data with a file field.

Response:

{
  "filename": "example.md",
  "size": 128,
  "message": "Uploaded"
}

Errors:

• 400 — file is not .md

---

GET /notes

List all saved notes.

Response:

{
  "count": 2,
  "notes": [
    {"filename": "example.md", "size": 128},
    {"filename": "todo.md", "size": 256}
  ]
}

---

GET /notes/{filename}/html

Render the specified note as HTML.

Response: text/html — the rendered Markdown.

Errors:

• 400 — invalid filename (contains path separators or ..)
• 404 — note not found

---

POST /grammar-check

Check the spelling of an arbitrary text and return misspelled words with suggestions. (English only.)

Request body:

{
  "text": "I havv a beuatiful catt"
}

Response:

{
  "text": "I havv a beuatiful catt",
  "misspelled_count": 3,
  "errors": [
    {"word": "havv", "suggestion": "have", "candidates": ["have", "havoc"]},
    {"word": "beuatiful", "suggestion": "beautiful", "candidates": ["beautiful"]},
    {"word": "catt", "suggestion": "cat", "candidates": ["cat", "catty"]}
  ]
}

Data Storage

Uploaded notes are stored as .md files in the local notes/ directory, which is created automatically on first upload. This directory is gitignored.

Project Structure

markdown-notes-api/
├── main.py             # FastAPI application
├── requirements.txt    # Python dependencies
├── notes/              # Uploaded notes (gitignored)
├── venv/               # Virtual environment (gitignored)
└── README.md

Tech Stack

• FastAPI — modern Python web framework
• uvicorn — ASGI server
• markdown — Markdown to HTML conversion
• pyspellchecker — English spell checking
• python-multipart — file-upload support

License

MIT