OpeningDesign/Utility_Apps
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Utility_Apps/Bat/convert_md_to_svg_html_only/readme.md

4.6 KiB
Raw Permalink Blame History

Markdown to SVG Converter

Converts Markdown files to multi-page SVG files with automatic page breaking.

Features

  • Automatic page breaks - Intelligently inserts page breaks based on character count
  • Multi-page support - Creates separate SVG files for each page (e.g., document-1.svg, document-2.svg)
  • Customizable dimensions - Control page size, zoom level, and characters per page
  • Timestamp checking - Only converts files that have been modified since last conversion
  • YAML configuration - Per-file settings via YAML front matter

Requirements

  • Windows with PowerShell
  • Pandoc
  • CSS file (OD.css in OD_css folder)

Installation

  1. Download/clone this repository
  2. Ensure Pandoc is installed and in your PATH
  3. Place your CSS file at OD_css/OD.css
  4. Place convert_md_to_svg_html_only.bat and convert_md_to_svg_html_only_dependency.ps1 in the same directory as your markdown files

Usage

Basic Usage

Simply run the batch file in a folder containing .md files:

convert_md_to_svg_html_only.bat

The script will:

  1. Find all .md files recursively
  2. Check if conversion is needed (timestamp comparison)
  3. Auto-insert page breaks based on character count
  4. Convert to HTML with embedded CSS
  5. Split into multiple SVG files

YAML Configuration

Add YAML front matter to your markdown files to customize settings:

---
page-width: 185
page-height: 640
zoom: 0.265
chars-per-page: 3000
---

# Your Document Title

Content goes here...

Configuration Parameters

Parameter Default Description
page-width 152.4 Page width in millimeters
page-height 457.2 Page height in millimeters
zoom 0.265 Zoom factor for content scaling
chars-per-page 3000 Target characters per page (excludes HTML comments)

Tuning Page Breaks

The chars-per-page parameter controls how much content fits on each page:

  • Content clipping? Lower the value (try 2500 or 2000)
  • Too much blank space? Raise the value (try 3500 or 4000)
  • Different content density? Adjust per document in YAML

How Page Breaking Works

  1. Counts characters in markdown (excluding HTML comments)
  2. When threshold is reached, looks for the next heading
  3. Inserts <!-- PAGE_BREAK --> before that heading
  4. HTML is split at these markers to create separate SVG pages

Manual Page Breaks

You can also manually insert page breaks anywhere in your markdown:

Some content here...

<!-- PAGE_BREAK -->

Content for next page...

Output Files

For a file named GENERAL NOTES.md with 3 pages:

GENERAL NOTES-1.svg
GENERAL NOTES-2.svg
GENERAL NOTES-3.svg

Skipping Files

The script automatically skips files where the SVG is newer than the markdown. To force reconversion, either:

  1. Touch/modify the .md file
  2. Delete the existing .svg files

Advanced: Default Settings

Edit the batch file to change defaults:

SET DEFAULT_PAGE_WIDTH=152.4
SET DEFAULT_PAGE_HEIGHT=457.2
SET DEFAULT_ZOOM=0.265
SET DEFAULT_CHARS_PER_PAGE=3000

Troubleshooting

SVGs are blank or malformed

  • Check that OD.css exists in the OD_css folder
  • Verify Pandoc is installed: pandoc --version
  • Check PowerShell execution policy: Get-ExecutionPolicy

Content is clipping between pages

  • Lower chars-per-page value (try 2500, 2000, or even 1500)
  • Check that headings exist in your document for break placement

Script exits immediately

  • Ensure .md files are present in the current directory or subdirectories
  • Check file timestamps - SVGs might already be up to date

Page breaks not at good locations

  • The script only breaks before headings (#, ##, etc.)
  • Ensure your document has headings at reasonable intervals
  • Manually add <!-- PAGE_BREAK --> markers if needed

File Structure

your-project/
├── OD_css/
│   └── OD.css                                    # Your CSS styles
├── convert_md_to_svg_html_only.bat              # Main batch script
├── convert_md_to_svg_html_only_dependency.ps1   # PowerShell helper
├── document1.md                                  # Your markdown
├── document1-1.svg                              # Generated SVGs
├── document1-2.svg
└── document1-3.svg

Tips

  • Keep headings regular - Page breaks only occur before headings
  • Use HTML comments - They're excluded from character counting
  • Test with one file first - Tune settings before batch processing
  • Version control - The script modifies .md files to insert breaks; commit before running