md-lv 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-01-25
+
+### Added
+
+- **ESM Support**: Full ECMAScript Modules support with `"type": "module"`
+- **Express 5.x**: Upgraded from Connect to Express 5.x framework
+- **Mermaid Diagrams**: Render flowcharts, sequence diagrams, and more
+- **MathJax Support**: LaTeX math formula rendering with `$...$` and `$$...$$`
+- **Dark Mode**: Automatic theme switching based on system preferences
+- **Search Functionality**: Client-side file search with real-time results
+- **Keyboard Navigation**: Vim-style navigation (j/k) and shortcuts
+- **Security Headers**: CSP, X-Content-Type-Options, X-Frame-Options, etc.
+- **Path Traversal Protection**: Enhanced security against directory traversal attacks
+- **Modern UI**: Improved styling with CSS custom properties
+- **README Command**: `mdv readme` to find and open nearest README.md
+- **Port Auto-Selection**: Automatically find available port if specified port is in use
+- **Integration Tests**: Comprehensive test suite with Jest and Supertest
+- **GitHub Actions CI**: Automated testing on Node.js 18, 20, and 22
+
+### Changed
+
+- **CLI Parser**: Migrated from meow to Commander.js
+- **Directory Structure**: Reorganized to `src/`, `routes/`, `middleware/`, `utils/`
+- **Template System**: Simplified HTML templating with mustache-style variables
+- **Logging**: Unified logger with configurable log levels
+- **Error Handling**: Centralized error handling with custom error pages
+- **Node.js Requirement**: Minimum version is now Node.js 18.0.0
+
+### Removed
+
+- **CommonJS Support**: No longer supports `require()` imports
+- **Connect Framework**: Replaced with Express 5.x
+- **Bluebird**: Using native Promises
+- **meow**: Replaced with Commander.js
+- **markdown-it**: Moved to client-side marked.js rendering
+- **LiveReload**: Removed in favor of manual refresh (may be re-added)
+
+### Security
+
+- Path traversal prevention with symlink resolution
+- Null byte injection protection
+- Security headers (CSP, X-Frame-Options, etc.)
+- Input validation and HTML escaping
+
+### Fixed
+
+- Unicode file name handling
+- URL encoding in breadcrumbs
+- Memory leaks in template caching
+
+## [1.x.x] - Previous Versions
+
+See the [archived markserv changelog](archived-markserv/CHANGELOG.md) for previous version history.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 markdown-viewer 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,152 @@
+# markdown-viewer
+
+> Serve Markdown files as HTML with live features
+
+A lightweight local server that renders Markdown files as beautiful HTML pages, with support for GitHub Flavored Markdown, syntax highlighting, Mermaid diagrams, and MathJax formulas.
+
+## Features
+
+- **GitHub-style Markdown** - Full GFM support with tables, task lists, and more
+- **Syntax Highlighting** - Code blocks with automatic language detection
+- **Mermaid Diagrams** - Flowcharts, sequence diagrams, and more
+- **MathJax Support** - LaTeX math formulas (`$...$` and `$$...$$`)
+- **Directory Browsing** - Navigate through your files with ease
+- **Dark Mode** - Automatic theme switching based on system preferences
+- **Search** - Find files quickly with built-in search
+- **Keyboard Navigation** - Navigate with vim-style keys (j/k)
+- **Security** - Path traversal protection and security headers
+
+## Installation
+
+```bash
+npm install -g markdown-viewer
+```
+
+Or use npx:
+```bash
+npx markdown-viewer
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Serve current directory
+mdv
+
+# Serve specific directory
+mdv --dir /path/to/docs
+
+# Serve on custom port
+mdv --port 8080
+
+# Open README.md automatically
+mdv readme
+```
+
+### CLI Options
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--port` | `-p` | `3000` | Server port |
+| `--host` | `-H` | `localhost` | Bind address |
+| `--dir` | `-d` | `.` | Document root |
+| `--no-watch` | | `false` | Disable file watching |
+| `--quiet` | `-q` | `false` | Suppress output |
+| `--debug` | | `false` | Enable debug mode |
+
+### Subcommands
+
+#### `mdv readme`
+
+Find and display the nearest README.md file:
+
+```bash
+cd /path/to/project
+mdv readme
+```
+
+This command searches up the directory tree to find README.md and opens it in your browser.
+
+## Supported Content
+
+### Markdown Features
+
+- Headings, paragraphs, lists
+- Tables (GFM)
+- Task lists
+- Code blocks with syntax highlighting
+- Blockquotes
+- Links and images
+- Horizontal rules
+
+### Mermaid Diagrams
+
+````markdown
+```mermaid
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[OK]
+    B -->|No| D[Cancel]
+```
+````
+
+### Math Formulas
+
+Inline: `$E = mc^2$`
+
+Block:
+```markdown
+$$
+\sum_{i=1}^n i = \frac{n(n+1)}{2}
+$$
+```
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Alt + ←` | Go to parent directory |
+| `Alt + Home` | Go to root |
+| `j` / `↓` | Next item (in directory listing) |
+| `k` / `↑` | Previous item |
+| `Enter` | Open selected item |
+| `/` | Focus search |
+| `Escape` | Close search results |
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/your-username/markdown-viewer.git
+cd markdown-viewer
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Start development server
+npm start
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- [marked](https://marked.js.org/) - Markdown parser
+- [highlight.js](https://highlightjs.org/) - Syntax highlighting
+- [Mermaid](https://mermaid.js.org/) - Diagram rendering
+- [MathJax](https://www.mathjax.org/) - Math formulas

package/bin/mdv.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli.js';
+
+run(process.argv);

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "md-lv",
+  "version": "1.0.0",
+  "description": "Serve Markdown files as HTML with live features - syntax highlighting, Mermaid diagrams, and MathJax formulas",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "src/index.js",
+  "bin": {
+    "mdv": "bin/mdv.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "public/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "start": "node bin/mdv.js",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js tests/unit",
+    "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js tests/integration",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "markdown",
+    "server",
+    "html",
+    "viewer",
+    "mermaid",
+    "mathjax",
+    "syntax-highlighting",
+    "gfm",
+    "github-flavored-markdown",
+    "documentation",
+    "docs",
+    "cli"
+  ],
+  "author": "Watanabe Riku",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/no-problem-dev/markdown-viewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/no-problem-dev/markdown-viewer/issues"
+  },
+  "homepage": "https://github.com/no-problem-dev/markdown-viewer#readme",
+  "dependencies": {
+    "express": "^5.0.0",
+    "commander": "^12.0.0",
+    "chokidar": "^3.5.0",
+    "open": "^10.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0",
+    "supertest": "^6.0.0"
+  }
+}

package/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect width="100" height="100" rx="15" fill="#0366d6"/>
+  <text x="50" y="70" font-family="system-ui, sans-serif" font-size="60" font-weight="bold" text-anchor="middle" fill="white">M</text>
+</svg>

package/public/js/app.js

@@ -0,0 +1,174 @@
+/**
+ * markdown-viewer Client-side JavaScript
+ */
+
+document.addEventListener('DOMContentLoaded', async () => {
+  // Markdown レンダリング
+  renderMarkdown();
+
+  // シンタックスハイライト
+  highlightCode();
+
+  // Mermaid 図のレンダリング
+  await renderMermaid();
+
+  // MathJax レンダリング（Mermaid の後）
+  await renderMath();
+});
+
+/**
+ * Markdown をレンダリング
+ */
+function renderMarkdown() {
+  const source = document.getElementById('markdown-source');
+  const rendered = document.getElementById('markdown-rendered');
+
+  if (source && rendered && typeof marked !== 'undefined') {
+    const markdown = source.textContent;
+
+    // カスタムレンダラーで Mermaid コードブロックを処理
+    let mermaidCounter = 0;
+    const renderer = {
+      code({ text, lang }) {
+        if (lang === 'mermaid') {
+          const id = `mermaid-diagram-${mermaidCounter++}`;
+          return `<div class="mermaid" id="${id}">${escapeHtmlForMermaid(text)}</div>`;
+        }
+        // デフォルトのコードブロックレンダリング
+        const escaped = escapeHtmlForMermaid(text);
+        const langClass = lang ? ` class="language-${lang}"` : '';
+        return `<pre><code${langClass}>${escaped}</code></pre>`;
+      }
+    };
+
+    // marked.js の設定とカスタムレンダラーを適用
+    marked.use({
+      gfm: true,
+      breaks: false,
+      pedantic: false,
+      renderer
+    });
+
+    // Markdown をレンダリング
+    rendered.innerHTML = marked.parse(markdown);
+  }
+}
+
+/**
+ * Mermaid 図をレンダリング
+ */
+async function renderMermaid() {
+  const mermaidDivs = document.querySelectorAll('.mermaid');
+
+  if (mermaidDivs.length === 0) return;
+
+  // Mermaid がロードされるまで待機（ESM モジュールは window.mermaid に公開される）
+  if (typeof window.mermaid === 'undefined') {
+    // Mermaid は ESM モジュールとして読み込まれるため、ポーリングで待機
+    let attempts = 0;
+    while (typeof window.mermaid === 'undefined' && attempts < 30) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      attempts++;
+    }
+
+    // 再度チェック
+    if (typeof window.mermaid === 'undefined') {
+      console.warn('Mermaid library not loaded');
+      mermaidDivs.forEach(div => {
+        div.innerHTML = `<pre class="mermaid-error">Mermaid library not loaded</pre>`;
+      });
+      return;
+    }
+  }
+
+  try {
+    // Mermaid を初期化（まだ初期化されていない場合）
+    window.mermaid.initialize({
+      startOnLoad: false,
+      theme: 'default',
+      securityLevel: 'loose',
+      flowchart: {
+        useMaxWidth: true,
+        htmlLabels: true
+      }
+    });
+
+    // 各 Mermaid ブロックをレンダリング
+    for (const div of mermaidDivs) {
+      const code = div.textContent;
+      const id = div.id || `mermaid-${Date.now()}`;
+
+      try {
+        const { svg } = await window.mermaid.render(id + '-svg', code);
+        div.innerHTML = svg;
+        div.classList.add('mermaid-rendered');
+      } catch (err) {
+        console.error('Mermaid rendering error:', err);
+        div.innerHTML = `<pre class="mermaid-error">Mermaid Error: ${escapeHtmlForMermaid(err.message || 'Unknown error')}</pre>`;
+        div.classList.add('mermaid-error');
+      }
+    }
+  } catch (err) {
+    console.error('Mermaid initialization error:', err);
+  }
+}
+
+/**
+ * シンタックスハイライトを適用
+ */
+function highlightCode() {
+  if (typeof hljs !== 'undefined') {
+    document.querySelectorAll('pre code').forEach((block) => {
+      hljs.highlightElement(block);
+    });
+  }
+}
+
+/**
+ * MathJax で数式をレンダリング
+ * @param {Element} container - レンダリング対象のコンテナ要素（省略時は content 全体）
+ */
+async function renderMath(container) {
+  const target = container || document.getElementById('markdown-rendered') || document.getElementById('content');
+
+  if (!target) return;
+
+  // MathJax がロードされるまで待機（最大2秒）
+  if (!window.MathJax || !window.MathJax.typesetPromise) {
+    let attempts = 0;
+    while ((!window.MathJax || !window.MathJax.typesetPromise) && attempts < 20) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      attempts++;
+    }
+
+    if (!window.MathJax || !window.MathJax.typesetPromise) {
+      console.warn('MathJax library not loaded after 2 seconds');
+      return;
+    }
+  }
+
+  try {
+    await window.MathJax.typesetPromise([target]);
+  } catch (err) {
+    console.error('MathJax rendering error:', err);
+  }
+}
+
+/**
+ * Mermaid 用の HTML エスケープ（最小限）
+ */
+function escapeHtmlForMermaid(str) {
+  if (typeof str !== 'string') return '';
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+// グローバルに公開
+window.mdv = {
+  renderMarkdown,
+  highlightCode,
+  renderMermaid,
+  renderMath
+};

package/public/js/navigation.js

@@ -0,0 +1,201 @@
+/**
+ * markdown-viewer Navigation Enhancement
+ * Keyboard navigation and UI improvements
+ */
+
+document.addEventListener('DOMContentLoaded', () => {
+  initKeyboardNavigation();
+  initDirectoryListNavigation();
+  initBackToTop();
+});
+
+/**
+ * キーボードナビゲーションを初期化
+ */
+function initKeyboardNavigation() {
+  document.addEventListener('keydown', (e) => {
+    // Alt + Left Arrow: 親ディレクトリへ
+    if (e.altKey && e.key === 'ArrowLeft') {
+      e.preventDefault();
+      navigateToParent();
+    }
+
+    // Alt + Home: ルートへ
+    if (e.altKey && e.key === 'Home') {
+      e.preventDefault();
+      navigateToRoot();
+    }
+
+    // Alt + Up Arrow: ページ先頭へ
+    if (e.altKey && e.key === 'ArrowUp') {
+      e.preventDefault();
+      window.scrollTo({ top: 0, behavior: 'smooth' });
+    }
+
+    // Alt + Down Arrow: ページ末尾へ
+    if (e.altKey && e.key === 'ArrowDown') {
+      e.preventDefault();
+      window.scrollTo({ top: document.body.scrollHeight, behavior: 'smooth' });
+    }
+
+    // "/" キー: 検索フォーカス（検索機能がある場合）
+    if (e.key === '/' && !isInputFocused()) {
+      const searchInput = document.getElementById('search-input');
+      if (searchInput) {
+        e.preventDefault();
+        searchInput.focus();
+      }
+    }
+
+    // Escape: フォーカス解除
+    if (e.key === 'Escape') {
+      document.activeElement.blur();
+    }
+  });
+}
+
+/**
+ * 親ディレクトリへナビゲート
+ */
+function navigateToParent() {
+  const breadcrumbs = document.querySelectorAll('#breadcrumbs a');
+  if (breadcrumbs.length >= 1) {
+    // 最後から2番目のリンク（親ディレクトリ）
+    const parentLink = breadcrumbs[breadcrumbs.length - 1];
+    if (parentLink) {
+      window.location.href = parentLink.href;
+    }
+  }
+}
+
+/**
+ * ルートディレクトリへナビゲート
+ */
+function navigateToRoot() {
+  window.location.href = '/';
+}
+
+/**
+ * ディレクトリ一覧のキーボードナビゲーション
+ */
+function initDirectoryListNavigation() {
+  const directoryList = document.querySelector('.directory-listing');
+  if (!directoryList) return;
+
+  const items = directoryList.querySelectorAll('li a');
+  let currentIndex = -1;
+
+  document.addEventListener('keydown', (e) => {
+    if (isInputFocused()) return;
+
+    // j/k または ArrowDown/ArrowUp でリスト内を移動
+    if (e.key === 'j' || e.key === 'ArrowDown') {
+      e.preventDefault();
+      currentIndex = Math.min(currentIndex + 1, items.length - 1);
+      focusItem(currentIndex);
+    }
+
+    if (e.key === 'k' || e.key === 'ArrowUp') {
+      e.preventDefault();
+      currentIndex = Math.max(currentIndex - 1, 0);
+      focusItem(currentIndex);
+    }
+
+    // Enter で選択したアイテムを開く
+    if (e.key === 'Enter' && currentIndex >= 0) {
+      items[currentIndex].click();
+    }
+
+    // g で先頭へ
+    if (e.key === 'g' && !e.ctrlKey && !e.metaKey) {
+      currentIndex = 0;
+      focusItem(currentIndex);
+    }
+
+    // G (Shift + g) で末尾へ
+    if (e.key === 'G') {
+      currentIndex = items.length - 1;
+      focusItem(currentIndex);
+    }
+  });
+
+  function focusItem(index) {
+    // 前のフォーカスを解除
+    items.forEach(item => item.parentElement.classList.remove('keyboard-focus'));
+
+    if (index >= 0 && index < items.length) {
+      items[index].parentElement.classList.add('keyboard-focus');
+      items[index].focus();
+      items[index].scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+    }
+  }
+}
+
+/**
+ * 「トップへ戻る」ボタンを初期化
+ */
+function initBackToTop() {
+  // ボタンを作成
+  const button = document.createElement('button');
+  button.id = 'back-to-top';
+  button.innerHTML = '↑';
+  button.title = 'Back to top (Alt + ↑)';
+  button.setAttribute('aria-label', 'Back to top');
+
+  // スタイル設定
+  Object.assign(button.style, {
+    position: 'fixed',
+    bottom: '20px',
+    right: '20px',
+    width: '40px',
+    height: '40px',
+    borderRadius: '50%',
+    border: 'none',
+    backgroundColor: 'var(--color-link, #0366d6)',
+    color: 'white',
+    fontSize: '20px',
+    cursor: 'pointer',
+    opacity: '0',
+    visibility: 'hidden',
+    transition: 'opacity 0.3s, visibility 0.3s',
+    zIndex: '1000',
+    boxShadow: 'var(--shadow-md, 0 4px 6px rgba(0, 0, 0, 0.1))'
+  });
+
+  document.body.appendChild(button);
+
+  // スクロール時の表示制御
+  window.addEventListener('scroll', () => {
+    if (window.scrollY > 300) {
+      button.style.opacity = '1';
+      button.style.visibility = 'visible';
+    } else {
+      button.style.opacity = '0';
+      button.style.visibility = 'hidden';
+    }
+  });
+
+  // クリックでトップへ
+  button.addEventListener('click', () => {
+    window.scrollTo({ top: 0, behavior: 'smooth' });
+  });
+}
+
+/**
+ * 入力フィールドにフォーカスがあるかチェック
+ */
+function isInputFocused() {
+  const active = document.activeElement;
+  return active && (
+    active.tagName === 'INPUT' ||
+    active.tagName === 'TEXTAREA' ||
+    active.isContentEditable
+  );
+}
+
+// グローバルに公開
+window.mdvNav = {
+  navigateToParent,
+  navigateToRoot,
+  isInputFocused
+};