How matudapoke/mdtohtml works
1. Overall shape
- This repository is a Windows-native Markdown-to-HTML conversion tool, not a server app.
- The architecture is split between a local conversion pipeline and a browser-rendered presentation layer.
2. Entry points
- MDtoHTML.bat is the main user-facing entry point.
- It supports double-click, drag-and-drop, and “Open with” file association, making the batch file the top-level boundary for all user interaction.
3. Conversion engine
- scripts/Convert-MDtoHTML.ps1 is the core backend logic.
- It reads the selected Markdown file in UTF-8, loads the template assets, performs placeholder substitution, writes an HTML file, and launches it in the default browser.
4. Template assembly
- The generated HTML is built from templates/template.html plus injected content from templates/style.css and templates/script.js.
- The template uses placeholders for title, CSS, JavaScript, and raw Markdown content, so visual design and behavior are customizable without changing the converter logic.
5. Client-side rendering boundary
- Markdown is not rendered during file conversion; it is rendered inside the browser after the HTML opens.
- This means the PowerShell step only packages content, while the browser performs the actual Markdown parsing and interactive UI behavior.
6. External browser dependencies
- The browser page relies on CDN-loaded libraries, specifically marked for Markdown rendering and highlight.js for code highlighting.
- This creates an external dependency boundary: the tool works locally, but rendering quality depends on internet access for those libraries.
7. Interactive features in the HTML layer
- The browser-side script provides runtime features such as syntax highlighting, table of contents generation, and light/dark theme switching.
- These are presentation-layer concerns, separate from the file conversion pipeline.
8. Refresh/reconversion path
- The README describes a refresh button that can re-convert the original Markdown via a custom mdtohtml:// protocol.
- That creates an optional callback path from browser UI back into the local Windows execution environment.
9. Protocol registration subsystem
- scripts/Register-Protocol.bat and scripts/Unregister-Protocol.bat manage the custom protocol registration in the user registry (HKCU).
- This is an auxiliary subsystem that enables the browser-to-tool round trip for refreshing content.
10. Output and lifecycle management
- Generated files are written to %TEMP%\MDtoHTML\ with a filename derived from the source name and a hash.
- The converter also performs cleanup of old HTML outputs, removing files older than 60 minutes so temporary artifacts do not accumulate.
11. Data flow
- Source Markdown file → PowerShell reads it → template assets are loaded → placeholders are replaced → HTML is written to temp storage → default browser opens the result.
- If protocol registration is enabled, the browser can later request a fresh conversion through the custom scheme.
12. Repository boundaries
- The repo has three clear layers: Windows launch/association, conversion and file output, and browser-side rendering/UI.
- That separation is the key thing to capture in an architecture diagram: the batch/PowerShell layer prepares static HTML, while the browser layer provides the interactive experience.
Main entry points: Convert-MDtoHTML.ps1 Converter · MDtoHTML.bat MDtoHTML.bat · Register-Protocol.bat Register · Unregister-Protocol.bat Unregister
Components 14
Windows entry
Batch entry points and protocol registration on the local machine.
- MDtoHTML.bat · Top-level user entry for double-click, drag-and-drop, and file association.
MDtoHTML.bat - Register · Registers the custom mdtohtml:// protocol in HKCU.
scripts/Register-Protocol.bat - Unregister · Removes the custom protocol registration.
scripts/Unregister-Protocol.bat - mdtohtml:// · Optional callback path from browser UI back to local reconversion.
Conversion pipeline
PowerShell-driven Markdown-to-HTML assembly and temp file output.
- Converter · Reads Markdown, fills the template, writes HTML, and opens the result.
scripts/Convert-MDtoHTML.ps1 - Markdown file · Source Markdown selected by the user or opened through file association.
- Template · HTML scaffold with placeholders for title, content, CSS, and script.
templates/template.html - Styles · Presentation rules injected into the generated page.
templates/style.css - Client script · Browser-side behavior for rendering and interactive controls.
templates/script.js - Temp output · Temporary HTML output location under %TEMP% with cleanup of old files.
Browser presentation
The generated page and its client-side rendering behavior.
- HTML output · The produced HTML file opened in the browser.
- Browser · Default browser that renders the page and runs client-side features.
External deps
Libraries loaded from a CDN at render time.
- marked · External Markdown parser loaded by the page.
- highlight.js · External syntax-highlighting library loaded by the page.
Connections 19
- MDtoHTML.bat → Converter: launches · Main execution path starts the PowerShell converter.
- MDtoHTML.bat → Register: manages · Optional setup path for protocol registration.
- MDtoHTML.bat → Unregister: manages · Optional removal path for protocol registration.
- Markdown file → Converter: feeds · The selected Markdown source is read by the converter.
- Converter → Template: loads · Uses the HTML template as the page scaffold.
- Converter → Styles: injects · Embeds stylesheet content into the generated HTML.
- Converter → Client script: injects · Embeds client-side script content into the generated HTML.
- Converter → Temp output: writes · Emits the generated HTML into temporary storage.
- Template → HTML output: becomes · Template placeholders are expanded into a concrete HTML file.
- Styles → HTML output: styles · CSS is included in the produced page.
- Client script → HTML output: powers · JavaScript is included in the produced page.
- Temp output → HTML output: contains · Temporary directory holds the generated output file.
- HTML output → Browser: opens in · The converter launches the result in the default browser.
- Browser → marked: uses · Browser page depends on CDN-loaded Markdown parsing.
- Browser → highlight.js: uses · Browser page depends on CDN-loaded code highlighting.
- Browser → mdtohtml://: refreshes · Refresh UI can invoke the custom protocol to reconvert the source.
- Register → mdtohtml://: registers · Adds the custom scheme to the Windows registry.
- Unregister → mdtohtml://: removes · Deletes the custom scheme registration from the Windows registry.
- mdtohtml:// → Converter: reconverts · Protocol callback can re-run the local conversion pipeline.