md-serve

md-serve is a lightweight HTTP server based on Quarkus, specifically designed to serve Markdown files as rendered HTML without the complexity of traditional documentation platforms. Ideal for developers and teams, this tool transforms your Markdown documents—such as notes, project documentation, or personal wikis—into stylish, navigable web pages viewable in any browser.

Key Features

• Markdown to HTML: Effortlessly convert .md files into styled HTML pages using Handlebars templates.
• Directory Listings: Automatic generation of directory listings ensures easy navigation through your content.
• YAML Front Matter Support: Customize your pages with title overrides, template selection, and additional metadata in YAML front matter blocks.
• Breadcrumb Navigation: Enhanced user experience with breadcrumb trails that help navigate through your documents.
• Custom Templates: Support for three distinct role-based templates—default, directory, and error—which can be easily overridden with custom .hbs files.
• Error Handling: Render 404 and 500 error pages gracefully through the templating system.
• Path Traversal Protection: Ensures security while navigating directories.

Quick Example

Using md-serve is straightforward. To get started, a simple command launches the server:

./mvnw quarkus:dev

Access the local server interface at http://localhost:8080, serving the current working directory by default.

Front Matter Customization

Each Markdown file may include a YAML front matter block, enabling better control over its rendering:

---
title: My Page
author: Ada Lovelace
---

Content here.

The title key customizes the displayed title, while the template key allows selection of a specific template from the .md-serve/templates/ directory.

For anyone looking for a seamless, local solution to browse Markdown files in a browser, md-serve offers a swift, no-fuss approach that caters perfectly to personal or small-scale documentation needs.