mdsplit

README

mdsplit – Markdown Splitting (Go CLI & Library)

mdsplit splits large Markdown files into smaller "slides" for easier viewing on mobile devices. It ships as a CLI and as a library so you can call it from your own code. No Node, headless browsers, or helper scripts. It is intended to be used in conjunction with the github.com/arran4/md2png project.

---

What it does

• Parses Markdown with goldmark and splits the result into multiple Markdown files.
• Intelligently splits content based on a maximum line count.
• Handles long tables by splitting them and adding a header to each part with a continuation note.
• Customizable slide size (vertical and horizontal).

---

Install

Clone and build:

git clone https://github.com/arran4/mdsplit.git
cd mdsplit
go build ./cmd/mdsplit

Dependencies are managed in go.mod and will be automatically downloaded by the go build command.

Requires Go 1.22 or newer.

---

CLI usage

./mdsplit -in README.md -out ./slides

Flags

Flag	Description	Default
-in	Markdown input file, or stdin when empty	—
-out	Output directory for the split files	.
-max-height	Maximum height of a slide in lines (overridden by -template-size)	40
-max-width	Maximum width of a slide in pixels (overridden by -template-size)	1024
-template-size	Predefined template size: card, horizontal-card, presentation, a4	—
-font-size	Font size in points	12
-dpi	DPI for rendering	96
-theme	light or dark (not yet implemented)	light

Template Size Presets

The -template-size flag provides convenient presets for common output formats:

• card: Vertical card format (600×800px at 96 DPI ≈ 25 lines)
• horizontal-card: Horizontal card format (800×600px at 96 DPI ≈ 18 lines)
• presentation: Standard presentation format (1920×1080px at 96 DPI ≈ 40 lines)
• a4: A4 page format (794×1123px at 96 DPI ≈ 50 lines)

When using a template size preset, the -max-height and -max-width values are automatically set. You can still override them by explicitly setting those flags.

Examples

Split a Markdown file into slides with custom height:

./mdsplit -in example.md -out ./slides -max-height 50

Split using a presentation template:

./mdsplit -in example.md -out ./slides -template-size presentation

Split using a card template with larger font:

./mdsplit -in example.md -out ./slides -template-size card -font-size 16

Split for A4 printing at high DPI:

./mdsplit -in example.md -out ./slides -template-size a4 -dpi 300

---

Library usage

package main

import (
        "os"

        "github.com/arran4/mdsplit"
)

func main() {
        err := mdsplit.Split([]byte("# Hello\nThis is a large Markdown file!"), mdsplit.SplitOptions{OutDir: "./slides", MaxHeight: 50})
        if err != nil {
                panic(err)
        }
}

SplitOptions exposes the same knobs as the CLI. Set custom dimensions.

---

How it works

1. Parse Markdown with yuin/goldmark and the goldmark-gfm extension.
2. Walk the AST and split the content into multiple smaller Markdown files based on a maximum line count.
3. If a table is too long, it is split into multiple slides, with the header repeated on each slide.
4. Write the split Markdown files to the output directory.

Everything happens in memory; there is no HTML renderer or external process.

---

Roadmap

• Use md2png's rendering engine to accurately measure slide height.
• Implement -max-width to control the width of the slides.
• Intelligent splitting of lists and code blocks.
• Support for different output formats (e.g., a single HTML file with multiple sections).
• Configurable themes via YAML/JSON.

---

License

mdsplit is available under the MIT License.

Documentation

Index

• func Run(in string, out string, maxHeight int, maxWidth int, theme string, ...) error
• func Split(data []byte, opts SplitOptions) error
• type SplitOptions
• type TemplateSize

Functions

func Run

func Run(in string, out string, maxHeight int, maxWidth int, theme string, templateSize string, fontSize int, dpi int) error

Run is a subcommand `mdsplit`

Flags:

in:           --in            (default: "")           Markdown input file, or stdin when empty
out:          --out           (default: ".")          Output directory for the split files
maxHeight:    --max-height    (default: 0)            Maximum height of a slide in lines. Overridden by template selection.
maxWidth:     --max-width     (default: 0)            Maximum width of a slide in pixels. Overridden by template selection.
theme:        --theme         (default: "light")      light or dark
templateSize: --template-size (default: "")           Predefined template size.
fontSize:     --font-size     (default: 12)           Font size in points
dpi:          --dpi           (default: 96)           DPI for rendering

Valid template sizes are: card, horizontal-card, presentation, a4.

func Split

func Split(data []byte, opts SplitOptions) error

Split takes a Markdown file as a byte slice and splits it into smaller files.

Types

type SplitOptions

type SplitOptions struct {
	OutDir       string
	MaxHeight    int
	MaxWidth     int
	Theme        string
	TemplateSize TemplateSize // Predefined template size (overrides MaxHeight/MaxWidth if set)
	FontSize     int          // Font size in points (default: 12)
	DPI          int          // DPI for rendering (default: 96)
}

SplitOptions holds the configuration for splitting the Markdown file.

type TemplateSize

type TemplateSize string

TemplateSize represents predefined template dimensions

const (
	// TemplateSizeCard is a vertical card format (600x800px at 96 DPI ≈ 25 lines)
	TemplateSizeCard TemplateSize = "card"
	// TemplateSizeHorizontalCard is a horizontal card format (800x600px at 96 DPI ≈ 18 lines)
	TemplateSizeHorizontalCard TemplateSize = "horizontal-card"
	// TemplateSizePresentation is a standard presentation format (1920x1080px at 96 DPI ≈ 40 lines)
	TemplateSizePresentation TemplateSize = "presentation"
	// TemplateSizeA4 is an A4 page format (794x1123px at 96 DPI ≈ 50 lines)
	TemplateSizeA4 TemplateSize = "a4"
)