Markdown to Gemtext Converter

A client-side web application that converts Markdown files to Gemtext format, built with vanilla HTML, CSS, and JavaScript. Supports drag-and-drop upload, live preview, batch processing, and download.

Live demo: https://gemtext.brennan.day

External Dependencies

This project uses minimal external resources for enhanced functionality:

• marked.js v12 (CDN) — Markdown parser and lexer

  • Loaded from https://cdn.jsdelivr.net/npm/marked@12/marked.min.js
  • Used to parse Markdown tokens for conversion to Gemtext
  • License: MIT

• JSZip v3.10.1 (CDN) — ZIP file creation library

  • Loaded from https://cdn.jsdelivr.net/npm/[email protected]/dist/jszip.min.js
  • Used for batch download functionality
  • License: MIT or GPLv3

• Font Awesome 6.6.0 (CDN) — Icon library for UI elements

  • Loaded from https://cdn.jsdelivr.net/npm/@fortawesome/[email protected]/css/all.min.css
  • Used for all interface icons (upload, settings, download, etc.)
  • License: CC BY 4.0 (Font Awesome) / CC BY-SA 4.0 (Font Awesome Free)

Overview

Gemtext is the native text format for the Gemini protocol, a simpler alternative to the web. This converter transforms standard Markdown into clean Gemtext while preserving essential structure and links.

• No server processing — everything runs in your browser
• Your files never leave your device
• Works offline once loaded
• Open source and privacy-focused

Features

• Drag-and-drop upload of .md, .markdown, and .txt files
• Live preview with rendered and raw Gemtext views
• Batch processing with ZIP download
• Settings modal for conversion options
• Responsive design for mobile and desktop
• Accessibility with ARIA labels and keyboard navigation

Usage

Web App

1. Open https://gemtext.brennan.day in your browser
2. Drag Markdown files onto the drop zone or click to select files
3. View the converted Gemtext in the preview pane
4. Toggle between rendered and raw views
5. Download individual .gmi files or a ZIP archive of all files
6. Adjust settings in the gear menu for different conversion behaviors

CLI Tool

A command-line version is also available as an npm package:

npm install -g md2gmi

Basic usage:

md2gmi README.md                    # Convert to stdout
md2gmi README.md -o README.gmi     # Convert to file
md2gmi < README.md > README.gmi    # Use stdin/stdout
cat README.md | md2gmi              # Pipe from stdin

For more CLI options and documentation, see CLI_README.md or run:

md2gmi --help

Conversion Rules

• Headings H4–H6 are downgraded to H3 (###)
• Inline links are extracted to => URL text lines
• Ordered lists become unordered (*)
• Nested lists are flattened with indentation
• Tables become preformatted blocks
• Images become => URL alt-text links
• Bold, italic, strikethrough, and inline code are stripped
• HTML tags are removed; entities are decoded
• Code blocks are preserved with language tags

Settings

• Link placement: After paragraphs or at document end
• Heading downgrade: Limit headings to level 3
• Table conversion: Preformat or skip
• List flattening: Flatten nested lists with indentation
• Image handling: Convert to links or skip
• Frontmatter: Strip or render as preformatted
• Line endings: LF or CRLF
• Source comments: Add conversion metadata

Development

Local Development

# Serve the project locally
python3 -m http.server 8765
# or
npx serve .

Then visit http://localhost:8765

Project Structure

markdown2gemtext/
├── index.html              # Main SPA
├── css/
│   ├── main.css            # Core styles and dark theme
│   ├── preview.css          # Gemtext preview styling
│   └── responsive.css      # Mobile layout
├── js/
│   ├── converter.js        # Markdown → Gemtext conversion
│   ├── fileHandler.js      # File loading and downloads
│   ├── preview.js          # Preview rendering
│   └── app.js              # Main application orchestration
├── test/                   # Test cases and expected outputs
└── docs/
    └── SPEC.md             # Technical specification

Testing

The test/ directory contains edge-case Markdown files and their expected Gemtext outputs. Use these to verify conversion correctness:

# Compare actual vs expected outputs
diff test/expected/*.gmi test/actual/*.gmi

Deployment

The app is designed for static hosting. Netlify configuration is included:

• netlify.toml — SPA routing and build settings
• No build step required — just deploy the files as-is

Privacy and Security

• All processing happens client-side in your browser
• No files are transmitted to any server
• No analytics or tracking
• No cookies or local storage beyond settings persistence
• Works offline after initial page load

Browser Support

• Modern browsers with ES6+ support
• Tested in Chrome, Firefox, Safari, Edge
• Mobile browsers supported

About

A 🍓 Berry House project by Brennan Kenneth Brown.

License

AGPL 3.0 — see LICENSE file for details.

Contributing

Contributions welcome. Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new conversion rules
5. Submit a pull request