https://github.com/intellicode/mdserve
Rust Markdown Server
https://github.com/intellicode/mdserve
http-server markdown rust
Last synced: 4 months ago
JSON representation
Rust Markdown Server
- Host: GitHub
- URL: https://github.com/intellicode/mdserve
- Owner: Intellicode
- License: mit
- Created: 2025-02-27T20:31:26.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-08T20:02:40.000Z (about 1 year ago)
- Last Synced: 2025-06-23T01:04:42.878Z (12 months ago)
- Topics: http-server, markdown, rust
- Language: Rust
- Homepage:
- Size: 220 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
🚀 Markdown Server
A fast and lightweight server that serves markdown files as HTML pages with beautiful typography.
## Example
## Features
- 📝 GitHub Flavored Markdown support
- 🎨 Beautiful typography with Source Serif font
- 📁 Serves static files alongside markdown
- 📱 Responsive design
- 🔍 Automatic index.md rendering
- 🛠️ Customizable with YAML configuration
- ⚡ Built with Rust for maximum performance
## Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/markdown-server
cd markdown-server
# Build the project
cargo build --release
# Run the server
cargo run --release -- /path/to/your/markdown/files
```
## Usage
### Starting the Server
```bash
# With configuration file (required)
cargo run -- serve --config /path/to/config.yaml
# Backward compatibility mode
cargo run -- --config /path/to/config.yaml
```
### Exporting Static HTML
```bash
# Export markdown to HTML (config required)
cargo run -- export --output-dir /path/to/html --config /path/to/config.yaml
```
### Directory Structure
```
docs/
├── index.md # Served at /
├── guide.md # Served at /guide
└── tutorials/
├── index.md # Served at /tutorials/
└── basics.md # Served at /tutorials/basics
```
### Supported Markdown Features
- Headers (h1-h6)
- Lists (ordered and unordered)
- Code blocks with syntax highlighting
- Tables
- Task lists
- Blockquotes
- Links and images
- Strikethrough
- And more!
## Configuration
### Environment Variables
- `PORT`: Server port (default: 3000)
### Template Variables
When creating a custom template, the following variables are available:
- `{{content}}` - The markdown content converted to HTML
- `{{title}}` - Page title from frontmatter's `title` field (default: "Markdown Viewer")
- `{{header_title}}` - Header title from frontmatter's `title` field (default: "Wiki")
- `{{description}}` - Description from frontmatter's `description` field (default: "Markdown document")
- `{{frontmatter_block}}` - HTML block with formatted frontmatter information (author, date, description, tags)
- `{{navigation_links}}` - Navigation links from the configuration file (or default links if not provided)
### YAML Configuration File
You can customize the appearance and content of your markdown site using a YAML configuration file. Here's an example:
```yaml
# Source directory for markdown files (required)
source_dir: "/path/to/your/markdown/files"
# Template directory for HTML templates (optional, default: "./templates")
template_dir: "/path/to/templates"
# Custom CSS to be injected into the HTML page
custom_css: |
body {
max-width: 85ch; /* Wider content area */
}
h1, h2, h3 {
color: #1e5285; /* Custom heading colors */
}
# Custom HTML content for the page header
header: |
# Custom HTML content for the page footer
footer: |
© 2025 Your Organization
# Navigation links to be displayed in the header
navigation:
- text: Home
url: /
- text: Documentation
url: /docs
- text: GitHub
url: https://github.com/intellicode/mdserve
```
## Development
```bash
# Run tests
cargo test
# Run with hot reloading
cargo watch -x run -- /path/to/docs
# Check formatting
cargo fmt -- --check
# Run linter
cargo clippy
```
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Security
### Binary Verification
All official release binaries are signed using [Sigstore](https://sigstore.dev/), which provides keyless signing and verification. This allows you to verify that the binaries were built and signed as part of our official GitHub Actions release process.
#### Verifying a Binary
To verify a binary:
1. Install the Sigstore CLI:
```bash
brew install cosign
```
2. Download the binary and its signature files:
Visit the [Releases](https://github.com/Intellicode/mdserve/releases) page to download the binary for your platform along with sigstore bundle.
3. Verify the signature:
```bash
cosign verify-blob mdserve-darwin-arm64 \
--bundle mdserve-darwin-arm64.sigstore.json \
--certificate-identity "https://github.com/Intellicode/mdserve/.github/workflows/rust.yml@refs/tags/v0.5.3" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
```
This verification ensures that the binary was signed by the official GitHub Actions workflow during the release process.