179 lines
4.7 KiB
Markdown
179 lines
4.7 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo build --release
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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
|
||
|
|
|
||
|
|
1. **Directory Structure**: Place your Markdown files in a `./content` directory
|
||
|
|
2. **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`
|
||
|
|
|
||
|
|
3. **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
|
||
|
|
|
||
|
|
1. Create a `layout` directory in your working directory
|
||
|
|
2. Create a template file with `.hbs` extension (e.g., `my-template.hbs`)
|
||
|
|
3. Use Handlebars syntax with the available variables
|
||
|
|
4. 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
|
||
|
|
|
||
|
|
```html
|
||
|
|
<!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>© 2023 My Site</p>
|
||
|
|
</footer>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
```
|
||
|
|
|
||
|
|
### Using Templates
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo build --release
|
||
|
|
```
|
||
|
|
|
||
|
|
## Running
|
||
|
|
|
||
|
|
```bash
|
||
|
|
./target/release/mhmmcontent
|
||
|
|
```
|
||
|
|
|
||
|
|
Then visit `http://localhost:8080/` in your browser.
|