MD to HTML Converter (md2html-nav)

A Markdown-to-HTML converter that transforms plain Markdown into a HTML documentation page. This tool is ideal for technical documentation, wikis, engineering blogs, API docs, and project pages.

📚 Table of Contents

• ✨ Install (NPM)
• 🚀 Usage (CLI)
• 💡 Why This Tool?
• 📘 Description
• 🧩 Template Features Explained
  • Sidebar Table of Contents
  • Minimap Navigation
  • Syntax Highlighting
  • Mermaid Diagram Support
  • Scroll Progress Bar
  • ScrollSpy
  • Copy Code Buttons
  • Theme Switcher
  • Floating Back-to-Top Button
• 📦 Installation
• ▶️ Usage Examples
• 🐞 Reporting Issues
• 🤝 Contributing
• 📄 License
• 📬 Contact

✨ Install (NPM)

npm install -g md2html-nav

This installs the CLI globally so you can run the converter from anywhere.

🚀 Usage (CLI)

Convert a Markdown file into a polished HTML document:

md2html-nav input.md output.html

Example:

md2html-nav README.md docs.html

This generates a fully‑styled HTML page using the built‑in template, sidebar TOC, minimap, syntax highlighting, Mermaid diagrams, theme switching, scroll progress, and FAB-to-top.

⚡ Mode Comparison (Default vs Standalone vs Copy Assets)

| Mode | Command | Output | Offline Support | JS/CSS Handling | Best For | |------|---------|--------|-----------------|-----------------|----------| | Default | md2html-nav in.md out.html | Single HTML | ❌ Partial | References external scripts & CDN CSS | Hosting with own asset pipeline | | Standalone | md2html-nav in.md out.html --standalone | Single HTML | ✅ Full | JS + CSS are inlined | Email, sharing, GitHub wiki, S3 | | Copy Assets | md2html-nav in.md out.html --copy-scripts | HTML + assets/ folder | ✅ Full | JS + CSS copied locally | Offline sites, GitHub Pages, docs folders |

Examples:

# Single self-contained HTML (recommended for sharing)
md2html-nav guide.md guide.html --standalone

# Output HTML + JS/CSS copied next to it
md2html-nav handbook.md handbook.html --copy-scripts

🔥 Mode Details (Impact & Use Cases)

1️⃣ Default Mode

md2html-nav input.md output.html

• Injects Markdown into template
• Leaves external <script src="..."> and CDN <link> untouched
• Fastest and smallest output
• Requires proper hosting (JS/CSS must resolve)
• Useful for: build pipelines, custom hosting setups

2️⃣ Standalone Mode

md2html-nav input.md output.html --standalone
# or
md2html-nav input.md output.html --inline

Produces one single, portable HTML file:

• Inlines all JavaScript from /scripts/
• Downloads CDN CSS and inlines it
• Removes external <script> and <link>
• Works perfectly offline
• Useful for:
  • Emailing documentation
  • Sharing single-file reference docs
  • GitHub wikis
  • S3 buckets
  • PDF export workflows

3️⃣ Copy Assets Mode

md2html-nav input.md output.html --copy-scripts

Outputs:

output/
  page.html
  assets/
    js/*.js
    css/*.css

• Copies all /scripts/*.js → assets/js/
• Downloads CDN CSS → assets/css/
• Rewrites <script> + <link> to point to local assets
• Works 100% offline while keeping HTML clean
• Best for:
  • GitHub Pages
  • Netlify
  • Offline documentation bundles
  • Delivering documentation as a folder

📁 Working With Templates

md2html-nav supports multiple templates stored under:

templates/
   <template-name>/
      template.html
      scripts/
         <JavaScript files used by that template>

Each template may define its own layout, styling, theme logic, and scripts.

🔍 List Available Templates

md2html-nav --list-templates

Example output:

Available templates:
 - default
 - minimal
 - dark-docs

🎨 Use a Template

md2html-nav input.md output.html --template dark-docs

If no template is specified, default is used.

🛠 Template Support Matrix

| Feature | Built into template | CLI Affects? | Required to work | |--------|----------------------|--------------|------------------| | Sidebar TOC | ✔ Yes | No | template + scripts folder | | Minimap | ✔ Yes | No | template + scripts folder | | Dark Mode | Depends on template | No | template-level theme.js | | Assets copied | No | ✔ Copy mode | --copy-scripts | | Assets inlined | No | ✔ Standalone | --standalone |

⚠ Important:
In default mode, the generated HTML still references scripts and styles inside the selected template folder.
This mode assumes you will host these assets yourself or use a deployment pipeline.

If you want everything to work out-of-the-box:

• Use --standalone (fully self-contained file), or
• Use --copy-scripts (HTML + assets/ folder).

💡 Why This Tool?

Most Markdown-to-HTML tools output very plain HTML.
md2html-nav instead focuses on developer documentation quality:

• Organizes long docs using a navigation sidebar
• Gives fast visual context with a minimap
• Makes reading easier with syntax highlighting
• Produces beautiful Mermaid diagrams automatically
• Provides modern UI elements — themes, FAB, scrollspy
• Zero configuration. Zero build tools. Pure Node.js.

It is perfect for:

• API documentation
• Engineering blogs
• Internal wikis
• Technical guides
• Lightweight documentation sites

If you want beautiful documentation without setting up an entire static site generator, this tool is for you.

📘 Description

This project converts Markdown files into beautiful, ready-to-publish HTML pages with:

• Fully responsive design
• Sidebar table of contents
• Minimap navigation
• Syntax highlighting
• Mermaid diagrams
• Dark/light theme toggle
• Scroll progress bar
• Floating “Back to Top” button
• Copy‑code buttons
• Smooth scrolling & scrollspy

All done with plain Node.js — no bundlers, frameworks, or compilers.

🧩 Template Features Explained

Below is a detailed explanation of all UI components inside template.html and scripts/.

Sidebar Table of Contents

Automatically generated from your Markdown headings (h1, h2, h3).
Benefits:

• Always visible for large documentation
• Highlights the current section (scrollspy)
• Perfect for deep, technical articles

Minimap Navigation

A miniature outline showing your entire document structure.
Useful for:

• Quickly jumping across sections
• Visualizing the layout of long documents

Syntax Highlighting

Uses highlight.js for colorful code blocks.

Just write:

```js
console.log("Hello");
```

It appears beautifully styled.

Mermaid Diagram Support

Write diagrams directly inside Markdown!

Example:

flowchart TD
    A --> B

Supports:

• Flowcharts
• Sequence diagrams
• State diagrams
• Class diagrams
• Gantt charts

Scroll Progress Bar

A thin progress bar at the top shows how far the reader has scrolled — great for UX.

ScrollSpy

Highlights the active section in the sidebar while scrolling, improving navigation in large docs.

Copy Code Buttons

Every code block gets a one‑click Copy button.
Super useful for tutorials and API docs.

Theme Switcher

Toggle between dark and light themes.
User preference is stored in localStorage.

Floating Back-to-Top Button

A modern round FAB in the lower-right corner.
Smoothly scrolls the user back to the top.

📦 Installation

npm install

▶️ Usage Examples

Convert any Markdown file:

node convert.js input.md output.html

Batch convert:

for f in docs/*.md; do md2html-nav "$f" "${f%.md}.html"; done

🐞 Reporting Issues

This Project uses GitHub's integrated issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below:

• Before you log a bug, please search the issue tracker to see if someone has already reported the problem.
• If the issue doesn't already exist, create a new issue
• Please provide as much information as possible with the issue report.
• If you need to paste code, or include a stack trace use Markdown +++```+++ escapes before and after your text.

🤝 Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Kindly refer to CONTRIBUTING.md for important Pull Request Process details

1. In the top-right corner of this page, click Fork.

2. Clone a copy of your fork on your local, replacing YOUR-USERNAME with your Github username.

   git clone https://github.com/YOUR-USERNAME/Spring-Boot-Application-Template.git

3. Create a branch:

   git checkout -b <my-new-feature-or-fix>

4. Make necessary changes and commit those changes:

   git add .

   git commit -m "new feature or fix"

5. Push changes, replacing <add-your-branch-name> with the name of the branch you created earlier at step #3. :

   git push origin <add-your-branch-name>

6. Submit your changes for review. Go to your repository on GitHub, you'll see a Compare & pull request button. Click on that button. Now submit the pull request.

That's it! Soon I'll be merging your changes into the master branch of this project. You will get a notification email once the changes have been merged. Thank you for your contribution.

Kindly follow Conventional Commits to create an explicit commit history. Kindly prefix the commit message with one of the following type's.

build : Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ci : Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
docs : Documentation only changes
feat : A new feature
fix : A bug fix
perf : A code change that improves performance
refactor: A code change that neither fixes a bug nor adds a feature
style : Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
test : Adding missing tests or correcting existing tests

📄 License

Distributed under the MIT License. See LICENSE.md for more information.

📬 Contact

Anantha Raju C - @anantharajuc - [email protected]

Project Link: https://github.com/AnanthaRajuC/md2html-nav/