Server API

The server.py module provides the create_app() factory function that creates a FastAPI application with all routes, WebSocket support, and file system watching for the markdown editor.

create_app()

Create the FastAPI application for the markdown editor.

def create_app(
    handler: FileHandler | DirectoryHandler,
    mode: str = "file"
) -> FastAPI

handler

FileHandler | DirectoryHandler

required

File or folder access service. Use FileHandler for single-file mode or DirectoryHandler for folder mode.

mode

str

default:"file"

Editor mode, either "file" or "folder". Must match the handler type.

app

FastAPI

Configured FastAPI application with routes, static assets, WebSocket support, and file system watching.

The mode parameter must be either "file" or "folder". Any other value raises ValueError.

Raises:

ValueError - If mode is not "file" or "folder"

Example

from pathlib import Path
from markdown_os.file_handler import FileHandler
from markdown_os.directory_handler import DirectoryHandler
from markdown_os.server import create_app
import uvicorn

# Single-file mode
file_handler = FileHandler(Path("notes.md"))
app = create_app(file_handler, mode="file")

# Folder mode
dir_handler = DirectoryHandler(Path("./docs"))
app = create_app(dir_handler, mode="folder")

# Run the server
uvicorn.run(app, host="0.0.0.0", port=8000)

Application Lifecycle

The application uses FastAPI’s lifespan context manager to start and stop file system observers:

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup: Start watchdog observer for file changes
    observer = Observer()
    observer.start()
    
    try:
        yield  # Application runs
    finally:
        # Shutdown: Stop observer and cleanup handlers
        observer.stop()
        observer.join(timeout=3)
        handler.cleanup()

HTTP Routes

GET /

Serve the editor web page.

@app.get("/")
async def read_root() -> FileResponse

response

FileResponse

The main editor application HTML page (index.html).

GET /favicon.ico

Redirect browser default favicon.ico requests to the SVG favicon.

@app.get("/favicon.ico")
async def favicon() -> RedirectResponse

redirect

RedirectResponse

302 redirect to /static/favicon.svg.

GET /api/mode

Return the current server mode.

@app.get("/api/mode")
async def get_mode() -> dict[str, str]

mode

dict[str, str]

Mode payload with value "file" or "folder".Example: {"mode": "folder"}

GET /api/file-tree

Return the markdown file tree for folder mode.

@app.get("/api/file-tree")
async def get_file_tree() -> dict[str, Any]

tree

dict[str, Any]

Nested folder/file structure (see DirectoryHandler.get_file_tree() for schema).

This endpoint is only available in folder mode. Returns 400 error in file mode.

Example Response:

{
  "type": "folder",
  "name": "docs",
  "path": "",
  "children": [
    {
      "type": "file",
      "name": "intro.md",
      "path": "intro.md"
    },
    {
      "type": "folder",
      "name": "guides",
      "path": "guides",
      "children": [...]
    }
  ]
}

GET /api/content

Return markdown content and metadata.

@app.get("/api/content")
async def get_content(file: str | None = None) -> dict[str, object]

str | None

Relative file path in folder mode (e.g., ?file=guides/intro.md). Not used in file mode.

response

dict[str, object]

Response containing:

content (str): Markdown content as UTF-8 string
metadata (dict): File metadata from FileHandler.get_metadata()
- In folder mode, includes additional relative_path field

Raises:

HTTPException(400) - If file parameter missing in folder mode or path invalid
HTTPException(404) - If file does not exist
HTTPException(500) - If file read fails

Example Response:

{
  "content": "# Introduction\n\nWelcome to the docs...",
  "metadata": {
    "path": "/home/user/docs/intro.md",
    "size_bytes": 1234,
    "modified_at": 1709251234.567,
    "created_at": 1709240000.123,
    "relative_path": "intro.md"
  }
}

POST /api/save

Persist markdown content to disk with atomic file replacement.

@app.post("/api/save")
async def save_content(payload: SaveRequest) -> dict[str, object]

Request Body (SaveRequest):

content

str

required

Full markdown document content to save.

file

str | None

Relative file path in folder mode. Not used in file mode.

response

dict[str, object]

Response containing:

status (str): Always "saved" on success
metadata (dict): Updated file metadata after save

Raises:

HTTPException(400) - If file parameter missing in folder mode or path invalid
HTTPException(404) - If file does not exist
HTTPException(500) - If write fails

The server tracks internal writes with a timestamp to distinguish them from external file changes when file watching.

Example Request:

{
  "content": "# Updated Content\n\nNew paragraph...",
  "file": "guides/intro.md"
}

Example Response:

{
  "status": "saved",
  "metadata": {
    "path": "/home/user/docs/guides/intro.md",
    "size_bytes": 1456,
    "modified_at": 1709251456.789,
    "created_at": 1709240000.123,
    "relative_path": "guides/intro.md"
  }
}

POST /api/images

Save an uploaded image in the workspace images directory.

@app.post("/api/images")
async def upload_image(file: UploadFile) -> dict[str, str]

file

UploadFile

required

Uploaded image data from multipart form payload.

response

dict[str, str]

Response containing:

path (str): Relative image path for markdown (e.g., "images/photo-20240301-123456.png")
filename (str): Saved filename with timestamp

Constraints:

Allowed extensions: .png, .jpg, .jpeg, .gif, .webp, .svg, .bmp, .ico
Maximum size: 10 MB (10,485,760 bytes)
Filename sanitization: Non-alphanumeric characters replaced with hyphens, timestamp appended

Raises:

HTTPException(400) - If file format unsupported, empty, or too large

Example Response:

{
  "path": "images/screenshot-20240301-123456-789012.png",
  "filename": "screenshot-20240301-123456-789012.png"
}

GET /images/{filename:path}

Serve uploaded images from the workspace images directory.

@app.get("/images/{filename:path}")
async def serve_image(filename: str) -> FileResponse

filename

str

required

Relative filename under the images directory (e.g., "photo.png" or "subdir/photo.png").

response

FileResponse

Streamed image file response when present.

This endpoint validates that the path stays within the images directory. Directory traversal attempts (e.g., "../etc/passwd") return 400 error.

Raises:

HTTPException(400) - If path contains .. or escapes images directory
HTTPException(404) - If image not found

WebSocket Routes

WS /ws

Maintain WebSocket connections for external file-change notifications.

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket) -> None

websocket

WebSocket

required

Incoming WebSocket connection from the browser.

Message Format (Server → Client): File Mode:

{
  "type": "file_changed",
  "content": "# Updated markdown content..."
}

Folder Mode:

{
  "type": "file_changed",
  "file": "guides/intro.md",
  "content": "# Updated markdown content..."
}

The WebSocket connection stays open until the client disconnects. Clients should reconnect automatically if the connection drops.

Behavior:

Accepts connection and registers client in WebSocketHub
Keeps connection alive by receiving (and ignoring) client messages
Removes client on disconnect or error
Receives external file change notifications from watchdog observer

Helper Classes

WebSocketHub

Manage active WebSocket clients and fan-out messages.

class WebSocketHub:
    async def connect(self, websocket: WebSocket) -> None
    async def disconnect(self, websocket: WebSocket) -> None
    async def broadcast_json(self, payload: dict[str, str]) -> None

Methods:

connect

async method

Accept and register a new WebSocket client.

disconnect

async method

Remove a WebSocket client from the active set.

broadcast_json

async method

Send a JSON payload to all currently connected clients. Automatically removes stale clients that fail to receive.

MarkdownPathEventHandler

Watchdog handler for markdown file changes in file or folder mode.

class MarkdownPathEventHandler(FileSystemEventHandler):
    def __init__(
        self,
        notify_callback: Callable[[Path], None],
        should_ignore: Callable[[], bool],
        target_file: Path | None = None,
        root_directory: Path | None = None,
    ) -> None

Constructor Parameters:

notify_callback

Callable[[Path], None]

required

Callback invoked on external file changes with the changed file path.

should_ignore

Callable[[], bool]

required

Callback returning True to ignore events (used to skip internal writes).

target_file

Path | None

Single-file mode target markdown path. Mutually exclusive with root_directory.

root_directory

Path | None

Folder-mode workspace root path. Mutually exclusive with target_file.

Event Handling:

Listens for modified, moved, and created events
Filters out directory events (only files)
Validates events match target file or are markdown files in root directory
Throttles to max one notification per 0.2 seconds
Ignores events within 0.5 seconds of internal writes

App State

The FastAPI app stores state in app.state:

app.state.handler: FileHandler | DirectoryHandler  # File access handler
app.state.mode: str  # "file" or "folder"
app.state.current_file: str | None  # Current file in folder mode
app.state.websocket_hub: WebSocketHub  # WebSocket client manager
app.state.last_internal_write_at: float  # Timestamp of last save (monotonic)

Complete Server Example

from pathlib import Path
from markdown_os.directory_handler import DirectoryHandler
from markdown_os.server import create_app
import uvicorn
import asyncio

async def main():
    # Create directory handler
    docs_dir = Path("~/Documents/notes").expanduser()
    handler = DirectoryHandler(docs_dir)
    
    # Create FastAPI app
    app = create_app(handler, mode="folder")
    
    # Configure uvicorn
    config = uvicorn.Config(
        app,
        host="0.0.0.0",
        port=8000,
        log_level="info",
        access_log=True
    )
    
    server = uvicorn.Server(config)
    
    try:
        # Run server
        print(f"Starting server for {docs_dir}")
        print("Open http://localhost:8000 in your browser")
        await server.serve()
    except KeyboardInterrupt:
        print("\nShutting down...")
    finally:
        # Cleanup is handled automatically by app lifespan
        pass

if __name__ == "__main__":
    asyncio.run(main())

File Watching Details

Watch Configuration

File Mode:

Watches: Parent directory of target file
Recursive: No
Events: Only for the specific target file

Folder Mode:

Watches: Entire workspace directory
Recursive: Yes
Events: All .md and .markdown files

Event Throttling

The file watcher implements two throttling mechanisms:

Time-based throttling: Maximum one notification per 0.2 seconds
Internal write filtering: Ignores events within 0.5 seconds of POST /api/save requests

def _should_ignore_watcher_event(app: FastAPI) -> bool:
    return (time.monotonic() - app.state.last_internal_write_at) < 0.5

This prevents the editor from receiving notifications for its own save operations, which would cause unnecessary UI updates and potential conflicts.

Static Files

Static assets are mounted from markdown_os/static/:

app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")

Available at:

/static/index.html - Main editor HTML
/static/js/*.js - JavaScript modules
/static/css/*.css - Stylesheets
/static/favicon.svg - Application icon

Error Handling

The server maps internal exceptions to HTTP status codes:

Exception	Status Code	Scenario
`FileReadError` (“does not exist”)	404	File not found
`FileReadError` (other)	500	Read failure
`FileWriteError`	500	Write failure
`FileNotFoundError`	404	File not found
`ValueError`	400	Invalid path or parameter

def _status_for_read_error(error: FileReadError) -> int:
    if "does not exist" in str(error):
        return 404
    return 500

Source Reference

See the complete implementation in markdown_os/server.py.

Python API

REST API

create_app()

Example

Application Lifecycle

HTTP Routes

GET /

GET /favicon.ico

GET /api/mode

GET /api/file-tree

GET /api/content

POST /api/save

POST /api/images

GET /images/{filename:path}

WebSocket Routes

WS /ws

Helper Classes

WebSocketHub

MarkdownPathEventHandler

App State

Complete Server Example

File Watching Details

Watch Configuration

Event Throttling

Static Files

Error Handling

Source Reference

Build docs developers (and LLMs) love

Python API

REST API

​create_app()

​Example

​Application Lifecycle

​HTTP Routes

​GET /

​GET /favicon.ico

​GET /api/mode

​GET /api/file-tree

​GET /api/content

​POST /api/save

​POST /api/images

​GET /images/{filename:path}

​WebSocket Routes

​WS /ws

​Helper Classes

​WebSocketHub

​MarkdownPathEventHandler

​App State

​Complete Server Example

​File Watching Details

​Watch Configuration

​Event Throttling

​Static Files

​Error Handling

​Source Reference

Build docs developers (and LLMs) love

create_app()

Example

Application Lifecycle

HTTP Routes

GET /

GET /favicon.ico

GET /api/mode

GET /api/file-tree

GET /api/content

POST /api/save

POST /api/images

GET /images/{filename:path}

WebSocket Routes

WS /ws

Helper Classes

WebSocketHub

MarkdownPathEventHandler

App State

Complete Server Example

File Watching Details

Watch Configuration

Event Throttling

Static Files

Error Handling

Source Reference