md-explorer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 md-explorer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# md-explorer
+
+A web-based file explorer for browsing and reading Markdown and HTML files. Point it at any directory and get a navigable file tree with rendered Markdown preview.
+
+## Install
+
+```bash
+npm install -g md-explorer
+```
+
+Or run directly with npx:
+
+```bash
+npx md-explorer ./docs
+```
+
+## Usage
+
+```bash
+md-explorer [directory] [options]
+```
+
+### Arguments
+
+| Argument    | Description                              |
+|-------------|------------------------------------------|
+| `directory` | Directory to serve (default: current dir)|
+
+### Options
+
+| Option           | Description                                      |
+|------------------|--------------------------------------------------|
+| `-p, --port PORT`| Port to listen on (default: 3000, or `PORT` env) |
+| `-h, --help`     | Show help message                                |
+
+## Examples
+
+```bash
+# Serve current directory on default port
+md-explorer
+
+# Serve a specific directory
+md-explorer ./docs
+
+# Serve on a custom port
+md-explorer ./docs --port 8080
+
+# Use PORT environment variable
+PORT=4000 md-explorer ~/notes
+```
+
+## Features
+
+- Collapsible file tree sidebar with lazy-loaded subdirectories
+- Rendered Markdown preview using [marked](https://github.com/markedjs/marked)
+- Inline HTML/HTM file viewing via iframe
+- Dot-files and `node_modules` are hidden automatically
+- Path traversal protection on all API routes
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "md-explorer",
+  "version": "1.0.0",
+  "description": "Web-based file explorer for Markdown & HTML",
+  "bin": {
+    "md-explorer": "server.js"
+  },
+  "files": [
+    "server.js",
+    "public/"
+  ],
+  "scripts": {
+    "start": "node server.js"
+  },
+  "keywords": [
+    "markdown",
+    "explorer",
+    "file-browser",
+    "html",
+    "viewer",
+    "cli",
+    "server"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iamthemovie/md-explorer.git"
+  },
+  "dependencies": {
+    "express": "^4.21.0",
+    "marked": "^15.0.0"
+  }
+}

package/public/app.js

@@ -0,0 +1,119 @@
+(function () {
+  const treeEl = document.getElementById('tree');
+  const contentEl = document.getElementById('content');
+  const collapseBtn = document.getElementById('collapse-btn');
+  const sidebar = document.getElementById('sidebar');
+  let activeLabel = null;
+
+  // --- Toggle sidebar ---
+  collapseBtn.addEventListener('click', () => {
+    sidebar.classList.toggle('collapsed');
+  });
+
+  // --- Fetch and render tree ---
+  async function fetchEntries(dirPath) {
+    const url = dirPath
+      ? '/api/tree?path=' + encodeURIComponent(dirPath)
+      : '/api/tree';
+    const res = await fetch(url);
+    return res.json();
+  }
+
+  async function loadTree() {
+    const entries = await fetchEntries('');
+    treeEl.innerHTML = '';
+    const ul = buildTreeUl(entries);
+    treeEl.appendChild(ul);
+  }
+
+  function buildTreeUl(nodes) {
+    const ul = document.createElement('ul');
+
+    for (const node of nodes) {
+      const li = document.createElement('li');
+
+      if (node.type === 'directory') {
+        const label = document.createElement('div');
+        label.className = 'tree-label';
+        label.innerHTML =
+          '<span class="tree-icon">&#9656;</span>' +
+          escapeHtml(node.name);
+
+        const childUl = document.createElement('ul');
+        childUl.className = 'tree-children';
+        let loaded = false;
+
+        label.addEventListener('click', async () => {
+          const opening = !childUl.classList.contains('open');
+          if (opening && !loaded) {
+            const children = await fetchEntries(node.path);
+            const freshUl = buildTreeUl(children);
+            while (freshUl.firstChild) childUl.appendChild(freshUl.firstChild);
+            loaded = true;
+          }
+          childUl.classList.toggle('open');
+          label.querySelector('.tree-icon').innerHTML =
+            childUl.classList.contains('open') ? '&#9662;' : '&#9656;';
+        });
+
+        li.appendChild(label);
+        li.appendChild(childUl);
+      } else {
+        const label = document.createElement('div');
+        label.className = 'tree-label';
+        const ext = node.name.split('.').pop().toLowerCase();
+        const icon = ext === 'md' ? '&#128196;' : '&#127760;';
+        label.innerHTML =
+          '<span class="tree-icon">' + icon + '</span>' +
+          escapeHtml(node.name);
+
+        label.addEventListener('click', () => handleFileClick(node, label));
+        li.appendChild(label);
+      }
+
+      ul.appendChild(li);
+    }
+
+    return ul;
+  }
+
+  // --- File click handlers ---
+  function handleFileClick(node, label) {
+    const ext = node.name.split('.').pop().toLowerCase();
+
+    if (ext === 'html' || ext === 'htm') {
+      window.open('/raw/' + node.path, '_blank');
+    } else if (ext === 'md') {
+      loadMarkdown(node.path, label);
+    }
+  }
+
+  async function loadMarkdown(filePath, label) {
+    if (activeLabel) activeLabel.classList.remove('active');
+    label.classList.add('active');
+    activeLabel = label;
+
+    try {
+      const res = await fetch('/api/file?path=' + encodeURIComponent(filePath));
+      if (!res.ok) {
+        contentEl.innerHTML = '<p class="placeholder">Error loading file.</p>';
+        return;
+      }
+      const data = await res.json();
+      document.title = data.title + ' — MarkdownX';
+      contentEl.innerHTML = data.html;
+    } catch {
+      contentEl.innerHTML = '<p class="placeholder">Error loading file.</p>';
+    }
+  }
+
+  // --- Utilities ---
+  function escapeHtml(str) {
+    const el = document.createElement('span');
+    el.textContent = str;
+    return el.innerHTML;
+  }
+
+  // --- Init ---
+  loadTree();
+})();

package/public/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>MarkdownX</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <div id="app">
+    <aside id="sidebar">
+      <div id="sidebar-header">
+        <strong>MarkdownX</strong>
+      </div>
+      <nav id="tree"></nav>
+    </aside>
+    <button id="collapse-btn" title="Toggle sidebar">&#x2630;</button>
+    <main id="content">
+      <p class="placeholder">Select a file from the sidebar.</p>
+    </main>
+  </div>
+  <script src="app.js"></script>
+</body>
+</html>

package/public/style.css

@@ -0,0 +1,194 @@
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  height: 100vh;
+  overflow: hidden;
+  color: #24292e;
+  background: #fff;
+}
+
+#app {
+  display: flex;
+  height: 100vh;
+  position: relative;
+}
+
+/* --- Sidebar --- */
+
+#sidebar {
+  width: 280px;
+  min-width: 280px;
+  background: #f6f8fa;
+  border-right: 1px solid #d0d7de;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  transition: min-width 0.15s, width 0.15s;
+}
+
+#sidebar.collapsed {
+  width: 0;
+  min-width: 0;
+}
+
+#sidebar-header {
+  display: flex;
+  align-items: center;
+  padding: 12px 16px;
+  border-bottom: 1px solid #d0d7de;
+  white-space: nowrap;
+}
+
+#collapse-btn {
+  position: absolute;
+  top: 8px;
+  left: 248px;
+  z-index: 10;
+  background: #f6f8fa;
+  border: 1px solid #d0d7de;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 16px;
+  padding: 2px 6px;
+  color: #57606a;
+  transition: left 0.15s;
+}
+
+#sidebar.collapsed ~ #collapse-btn {
+  left: 8px;
+}
+
+#collapse-btn:hover { background: #e1e4e8; }
+
+#tree {
+  overflow-y: auto;
+  flex: 1;
+  padding: 8px 0;
+  font-size: 14px;
+}
+
+/* --- Tree --- */
+
+#tree ul {
+  list-style: none;
+  padding-left: 16px;
+}
+
+#tree > ul { padding-left: 8px; }
+
+#tree li { user-select: none; }
+
+.tree-label {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 3px 8px;
+  border-radius: 4px;
+  cursor: pointer;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.tree-label:hover { background: #e1e4e8; }
+
+.tree-label.active {
+  background: #0969da;
+  color: #fff;
+}
+
+.tree-icon { flex-shrink: 0; width: 16px; text-align: center; font-size: 12px; }
+
+.tree-children { display: none; }
+.tree-children.open { display: block; }
+
+/* --- Content --- */
+
+#content {
+  flex: 1;
+  overflow-y: auto;
+  padding: 32px 48px;
+  max-width: 100%;
+}
+
+#content .placeholder {
+  color: #8b949e;
+  font-style: italic;
+  margin-top: 40vh;
+  text-align: center;
+}
+
+/* --- Markdown typography --- */
+
+#content h1, #content h2, #content h3,
+#content h4, #content h5, #content h6 {
+  margin-top: 24px;
+  margin-bottom: 16px;
+  font-weight: 600;
+  line-height: 1.25;
+}
+
+#content h1 { font-size: 2em; padding-bottom: 0.3em; border-bottom: 1px solid #d0d7de; }
+#content h2 { font-size: 1.5em; padding-bottom: 0.3em; border-bottom: 1px solid #d0d7de; }
+#content h3 { font-size: 1.25em; }
+
+#content p { margin-bottom: 16px; line-height: 1.6; }
+
+#content a { color: #0969da; text-decoration: none; }
+#content a:hover { text-decoration: underline; }
+
+#content ul, #content ol { padding-left: 2em; margin-bottom: 16px; }
+#content li { margin-bottom: 4px; line-height: 1.6; }
+
+#content blockquote {
+  padding: 0 1em;
+  color: #57606a;
+  border-left: 3px solid #d0d7de;
+  margin-bottom: 16px;
+}
+
+#content code {
+  background: #f6f8fa;
+  padding: 0.2em 0.4em;
+  border-radius: 3px;
+  font-size: 85%;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+}
+
+#content pre {
+  background: #f6f8fa;
+  padding: 16px;
+  border-radius: 6px;
+  overflow-x: auto;
+  margin-bottom: 16px;
+  line-height: 1.45;
+}
+
+#content pre code {
+  background: none;
+  padding: 0;
+  font-size: 85%;
+}
+
+#content table {
+  border-collapse: collapse;
+  margin-bottom: 16px;
+  width: auto;
+}
+
+#content th, #content td {
+  border: 1px solid #d0d7de;
+  padding: 6px 13px;
+}
+
+#content th { background: #f6f8fa; font-weight: 600; }
+
+#content img { max-width: 100%; }
+
+#content hr {
+  height: 2px;
+  background: #d0d7de;
+  border: none;
+  margin: 24px 0;
+}

package/server.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+const express = require('express');
+const path = require('path');
+const fs = require('fs');
+const { marked } = require('marked');
+
+// --- CLI argument parsing ---
+
+function printHelp() {
+  console.log(`
+Usage: md-explorer [directory] [options]
+
+Serve a directory of Markdown & HTML files in a web-based explorer.
+
+Arguments:
+  directory        Directory to serve (default: current directory)
+
+Options:
+  -p, --port PORT  Port to listen on (default: 3000, or PORT env var)
+  -h, --help       Show this help message
+`);
+  process.exit(0);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let dir = '.';
+  let port = parseInt(process.env.PORT, 10) || 3000;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      printHelp();
+    } else if (arg === '-p' || arg === '--port') {
+      const val = args[++i];
+      if (!val || isNaN(parseInt(val, 10))) {
+        console.error(`Error: ${arg} requires a numeric port argument`);
+        process.exit(1);
+      }
+      port = parseInt(val, 10);
+    } else if (arg.startsWith('-')) {
+      console.error(`Unknown option: ${arg}\nRun md-explorer --help for usage.`);
+      process.exit(1);
+    } else {
+      dir = arg;
+    }
+  }
+
+  return { dir, port };
+}
+
+const { dir, port: PORT } = parseArgs(process.argv);
+const ROOT = path.resolve(dir);
+
+if (!fs.existsSync(ROOT) || !fs.statSync(ROOT).isDirectory()) {
+  console.error(`Error: "${ROOT}" is not a directory`);
+  process.exit(1);
+}
+
+const app = express();
+
+const ALLOWED_EXT = new Set(['.md', '.html', '.htm']);
+const SKIP_DIRS = new Set(['node_modules']);
+
+// --- Path security ---
+
+function safePath(userPath) {
+  const resolved = path.resolve(ROOT, userPath);
+  if (!resolved.startsWith(ROOT + path.sep) && resolved !== ROOT) {
+    return null;
+  }
+  return resolved;
+}
+
+// --- List single directory (non-recursive) ---
+
+function listDir(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const results = [];
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    if (SKIP_DIRS.has(entry.name)) continue;
+
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(ROOT, fullPath);
+
+    if (entry.isDirectory()) {
+      results.push({
+        name: entry.name,
+        path: relPath,
+        type: 'directory',
+      });
+    } else if (ALLOWED_EXT.has(path.extname(entry.name).toLowerCase())) {
+      results.push({
+        name: entry.name,
+        path: relPath,
+        type: 'file',
+      });
+    }
+  }
+
+  // Sort: directories first, then alphabetical
+  results.sort((a, b) => {
+    if (a.type === b.type) return a.name.localeCompare(b.name);
+    return a.type === 'directory' ? -1 : 1;
+  });
+
+  return results;
+}
+
+// --- Static files ---
+
+app.use(express.static(path.join(__dirname, 'public')));
+
+// --- API: directory tree ---
+
+app.get('/api/tree', (req, res) => {
+  const userPath = req.query.path || '';
+  const resolved = userPath ? safePath(userPath) : ROOT;
+  if (!resolved) return res.status(403).json({ error: 'Forbidden' });
+
+  const entries = listDir(resolved);
+  res.json(entries);
+});
+
+// --- API: render markdown file ---
+
+app.get('/api/file', (req, res) => {
+  const userPath = req.query.path;
+  if (!userPath) return res.status(400).json({ error: 'Missing path parameter' });
+
+  const resolved = safePath(userPath);
+  if (!resolved) return res.status(403).json({ error: 'Forbidden' });
+
+  const ext = path.extname(resolved).toLowerCase();
+  if (ext !== '.md') return res.status(400).json({ error: 'Only .md files supported' });
+
+  let content;
+  try {
+    content = fs.readFileSync(resolved, 'utf-8');
+  } catch {
+    return res.status(404).json({ error: 'File not found' });
+  }
+
+  const html = marked(content);
+
+  // Extract title from first heading or filename
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  const title = titleMatch ? titleMatch[1] : path.basename(resolved, ext);
+
+  res.json({ html, title });
+});
+
+// --- Raw HTML file serving ---
+
+app.get('/raw/*', (req, res) => {
+  // Express 4 wildcard: everything after /raw/
+  const userPath = req.params[0];
+  if (!userPath) return res.status(400).send('Missing path');
+
+  const resolved = safePath(userPath);
+  if (!resolved) return res.status(403).send('Forbidden');
+
+  const ext = path.extname(resolved).toLowerCase();
+  if (ext !== '.html' && ext !== '.htm') {
+    return res.status(400).send('Only .html/.htm files supported');
+  }
+
+  res.sendFile(resolved, (err) => {
+    if (err) res.status(404).send('File not found');
+  });
+});
+
+// --- Start ---
+
+const server = app.listen(PORT, () => {
+  console.log(`md-explorer serving "${ROOT}" at http://localhost:${PORT}`);
+});
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    console.error(`Error: Port ${PORT} is already in use. Try a different port with --port.`);
+    process.exit(1);
+  }
+  throw err;
+});