# matudapoke/mdtohtml architecture

> Architecture diagram of the GitHub repository matudapoke/mdtohtml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matudapoke/mdtohtml
- Repository: https://github.com/matudapoke/mdtohtml

## Overview

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: [`scripts/Convert-MDtoHTML.ps1`](https://github.com/matudapoke/mdtohtml/blob/main/scripts/Convert-MDtoHTML.ps1) (Converter), [`MDtoHTML.bat`](https://github.com/matudapoke/mdtohtml/blob/main/MDtoHTML.bat) (MDtoHTML.bat), [`scripts/Register-Protocol.bat`](https://github.com/matudapoke/mdtohtml/blob/main/scripts/Register-Protocol.bat) (Register), [`scripts/Unregister-Protocol.bat`](https://github.com/matudapoke/mdtohtml/blob/main/scripts/Unregister-Protocol.bat) (Unregister)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_windows["Windows entry"]
  node_bat["MDtoHTML.bat<br/>entrypoint<br/>[MDtoHTML.bat]"]
  node_reg_proto["Register<br/>registry tool"]
  node_unreg_proto["Unregister<br/>registry tool"]
  node_mdtohtml_proto{{"mdtohtml://<br/>custom scheme"}}
end

subgraph group_convert["Conversion pipeline"]
  node_convert_ps1["Converter<br/>pipeline"]
  node_md_input["Markdown file<br/>input"]
  node_template_html["Template<br/>html shell<br/>[template.html]"]
  node_style_css["Styles<br/>theme css<br/>[style.css]"]
  node_script_js["Client script<br/>ui logic<br/>[script.js]"]
  node_temp_out[("Temp output<br/>artifact dir")]
end

subgraph group_browser["Browser presentation"]
  node_generated_html["HTML output<br/>artifact"]
  node_browser_rt(("Browser<br/>runtime"))
end

subgraph group_external["External deps"]
  node_marked_lib["marked<br/>cdn library"]
  node_hljs_lib["highlight.js<br/>cdn library"]
end

node_bat -->|"launches"| node_convert_ps1
node_bat -->|"manages"| node_reg_proto
node_bat -->|"manages"| node_unreg_proto
node_md_input -->|"feeds"| node_convert_ps1
node_convert_ps1 -->|"loads"| node_template_html
node_convert_ps1 -->|"injects"| node_style_css
node_convert_ps1 -->|"injects"| node_script_js
node_convert_ps1 -->|"writes"| node_temp_out
node_template_html -->|"becomes"| node_generated_html
node_style_css -->|"styles"| node_generated_html
node_script_js -->|"powers"| node_generated_html
node_temp_out -->|"contains"| node_generated_html
node_generated_html -->|"opens in"| node_browser_rt
node_browser_rt -.->|"uses"| node_marked_lib
node_browser_rt -.->|"uses"| node_hljs_lib
node_browser_rt -.->|"refreshes"| node_mdtohtml_proto
node_reg_proto -->|"registers"| node_mdtohtml_proto
node_unreg_proto -->|"removes"| node_mdtohtml_proto
node_mdtohtml_proto -.->|"reconverts"| node_convert_ps1

click node_bat "https://github.com/matudapoke/mdtohtml/blob/main/MDtoHTML.bat"
click node_convert_ps1 "https://github.com/matudapoke/mdtohtml/blob/main/scripts/Convert-MDtoHTML.ps1"
click node_reg_proto "https://github.com/matudapoke/mdtohtml/blob/main/scripts/Register-Protocol.bat"
click node_unreg_proto "https://github.com/matudapoke/mdtohtml/blob/main/scripts/Unregister-Protocol.bat"
click node_template_html "https://github.com/matudapoke/mdtohtml/blob/main/templates/template.html"
click node_style_css "https://github.com/matudapoke/mdtohtml/blob/main/templates/style.css"
click node_script_js "https://github.com/matudapoke/mdtohtml/blob/main/templates/script.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bat,node_reg_proto,node_unreg_proto,node_mdtohtml_proto toneBlue
class node_convert_ps1,node_md_input,node_template_html,node_style_css,node_script_js,node_temp_out toneAmber
class node_generated_html,node_browser_rt toneMint
class node_marked_lib,node_hljs_lib toneRose
```

## Components

### Windows entry

Batch entry points and protocol registration on the local machine.

- [MDtoHTML.bat](https://github.com/matudapoke/mdtohtml/blob/main/MDtoHTML.bat): entrypoint · Top-level user entry for double-click, drag-and-drop, and file association. · `MDtoHTML.bat`
- [Register](https://github.com/matudapoke/mdtohtml/blob/main/scripts/Register-Protocol.bat): registry tool · Registers the custom mdtohtml:// protocol in HKCU. · `scripts/Register-Protocol.bat`
- [Unregister](https://github.com/matudapoke/mdtohtml/blob/main/scripts/Unregister-Protocol.bat): registry tool · Removes the custom protocol registration. · `scripts/Unregister-Protocol.bat`
- **mdtohtml://**: custom scheme · Optional callback path from browser UI back to local reconversion.

### Conversion pipeline

PowerShell-driven Markdown-to-HTML assembly and temp file output.

- [Converter](https://github.com/matudapoke/mdtohtml/blob/main/scripts/Convert-MDtoHTML.ps1): pipeline · Reads Markdown, fills the template, writes HTML, and opens the result. · `scripts/Convert-MDtoHTML.ps1`
- **Markdown file**: input · Source Markdown selected by the user or opened through file association.
- [Template](https://github.com/matudapoke/mdtohtml/blob/main/templates/template.html): html shell · HTML scaffold with placeholders for title, content, CSS, and script. · `templates/template.html`
- [Styles](https://github.com/matudapoke/mdtohtml/blob/main/templates/style.css): theme css · Presentation rules injected into the generated page. · `templates/style.css`
- [Client script](https://github.com/matudapoke/mdtohtml/blob/main/templates/script.js): ui logic · Browser-side behavior for rendering and interactive controls. · `templates/script.js`
- **Temp output**: artifact dir · Temporary HTML output location under %TEMP% with cleanup of old files.

### Browser presentation

The generated page and its client-side rendering behavior.

- **HTML output**: artifact · The produced HTML file opened in the browser.
- **Browser**: runtime · Default browser that renders the page and runs client-side features.

### External deps

Libraries loaded from a CDN at render time.

- **marked**: cdn library · External Markdown parser loaded by the page.
- **highlight.js**: cdn library · External syntax-highlighting library loaded by the page.

## Connections

- 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.