Jarek Rozanski 3899ecce2f Server MD with Rust

2026-01-28 20:56:35 +01:00

4.7 KiB

Raw Blame History

Markdown Server

A Rust-based web server that serves Markdown files from a ./content directory as HTML. The URL path corresponds to the file path within the content directory.

Features

Automatic Markdown to HTML conversion - Uses pulldown-cmark for fast Markdown parsing
Flexible path resolution - Any URL path maps to ./content/{path}.md
Configurable working directory - Specify where the ./content folder is located
Customizable host and port - Run on any interface and port
Automatic content discovery - Shows available content on startup

Installation

cargo build --release

Usage

# Default usage (current directory, port 8080)
./target/release/mhmmcontent

# Custom working directory
./target/release/mhmmcontent --workdir /path/to/your/content

# Custom port
./target/release/mhmmcontent --port 9090

# Custom host and port
./target/release/mhmmcontent --host 0.0.0.0 --port 8888

# All options
./target/release/mhmmcontent --workdir /path/to/content --host 0.0.0.0 --port 9090

How It Works

Directory Structure: Place your Markdown files in a ./content directory
URL Mapping: The server maps URL paths directly to file paths:
- http://localhost:8080/foo/bar → ./content/foo/bar.md
- http://localhost:8080/zap/zap → ./content/zap/zap.md
- http://localhost:8080/ → ./content/index.md
Markdown Processing: Files are converted to HTML with proper styling

Example

Given this directory structure:

content/
├── index.md
├── foo/
│   └── bar.md
└── zap/
    └── zap.md

The server will serve:

http://localhost:8080/ → content/index.md
http://localhost:8080/foo/bar → content/foo/bar.md
http://localhost:8080/zap/zap → content/zap/zap.md

Command Line Options

Options:
  -w, --workdir <WORKDIR>    Working directory containing the ./content folder [default: .]
  -p, --port <PORT>          Port to bind the server to [default: 8080]
      --host <HOST>          Host to bind the server to [default: 127.0.0.1]
  -t, --template <TEMPLATE>  Template/layout name to use (default: "default") [default: default]
  -h, --help                 Print help
  -V, --version              Print version

Templates

The server supports custom templates/layouts using Handlebars syntax. Templates are loaded from the ./layout directory in the working directory.

Template Features

Custom Layouts: Create your own HTML layouts with {{title}}, {{content}}, and {{path}} variables
Handlebars Syntax: Full support for Handlebars templating
Fallback: If a template doesn't exist, the server uses a built-in default template
Multiple Templates: Create different templates for different use cases

Template Variables

{{title}} - The title of the page (from the Markdown filename)
{{content}} - The rendered HTML content from the Markdown file
{{path}} - The URL path of the current page

Example Template Structure

layout/
├── default.hbs      # Default template
├── minimal.hbs      # Minimal template
└── custom.hbs       # Custom template

Creating a Custom Template

Create a layout directory in your working directory
Create a template file with .hbs extension (e.g., my-template.hbs)
Use Handlebars syntax with the available variables
Run the server with --template my-template

Note: The server now requires template files to exist. If you specify a template that doesn't exist, the server will fail with a clear error message indicating which template file is missing.

Example Template

<!DOCTYPE html>
<html>
<head>
    <title>{{title}}</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
        }
    </style>
</head>
<body>
    <header>
        <h1>My Custom Site</h1>
        <nav>
            <a href="/">Home</a> |
            <a href="/about">About</a>
        </nav>
    </header>
    <main>
        {{{content}}}
    </main>
    <footer>
        <p>Current path: {{path}}</p>
        <p>&copy; 2023 My Site</p>
    </footer>
</body>
</html>

Using Templates

# Use default template (looks for layout/default.hbs)
./mhmmcontent --template default

# Use custom template
./mhmmcontent --template my-template

# Use minimal template
./mhmmcontent --template minimal

Dependencies

actix-web - Web framework
pulldown-cmark - Markdown parser
clap - Command line argument parsing
walkdir - Directory traversal

Building

cargo build --release

Running

./target/release/mhmmcontent

Then visit http://localhost:8080/ in your browser.

4.7 KiB Raw Blame History