markdown-bundle-browser

Markdown Bundle Browser

Purpose

Generate a single self-contained HTML file that embeds all markdown files from a directory. The result is a dark-themed document browser with a real directory tree, global search, offline markdown rendering and cross-document links — no server, no CDN, no network needed.

When to Use

Trigger when:

• User asks to "view all documents" / "浏览所有文档" from a project
• User reports that clicking .md file links doesn't work (browser cannot render raw markdown)
• User wants a single-page overview of a multi-file documentation set
• After completing a research project bootstrap (to package all deliverables)
• Any time there are 3+ markdown files and the user wants to browse them
• User wants to share a knowledge base as one portable HTML file

v2 Features

Workflow

Step 1: Locate Markdown Files

Identify the root directory containing markdown files. This is usually the project root or a docs/ directory. If the user specifies a specific folder, use that.

Step 2: Run the Bundle Script

Execute the bundled Python script:

python3 scripts/bundle.py  [--output index.html] [--title "My Title"]

Parameters:

• directory (required): Path to the root directory containing .md files. Recursively finds all .md files.
• --output (optional): Output HTML path. Defaults to index.html in the source directory.
• --title (optional): Browser page title. Defaults to "文档浏览".

The script:

1. Recursively finds all .md files (excluding hidden directories)
2. Reads each file's content
3. Builds a real directory tree (nested, expandable/collapsible)
4. Auto-assigns status badges based on filename heuristics or YAML config
5. Generates a single HTML with embedded content + built-in offline renderer
6. Reports file count and output size

Step 3: Preview the Result

After generation, use preview_url / present_files to open the HTML file for the user.

Step 4: Deliver

Attach both the generated HTML and the original markdown files if the user wants them.

Generated HTML Features

• Directory tree sidebar: Nested folders with expand/collapse, not flat groups
• Global search: Filter files by title AND content in real time
• Offline markdown rendering: Built-in lightweight GFM renderer, zero CDN
• Status badges: Each file gets a badge (完成/数据/实时/模板/积压)
• Cross-document links: Relative .md links in content become clickable jumps
• Auto TOC: h2/h3 headings generate an in-page table of contents
• Lazy rendering: Content parsed only when opened — handles 100+ files
• Dark theme + responsive: Sidebar auto-hides on mobile
• Self-contained: All contents embedded — no server, no network, no file:// issues

Optional YAML Config

title: "My Knowledge Base"
order: ["入口", "研究数据", "公司档案", "其他"]
group_rules:
  - match: "data/company_profiles"
    group: "公司档案"
    icon: "🏢"
badges:
  - match: "财报"
    label: "财报"

Run with: python3 bundle.py --config bundle.yaml

Category Auto-Detection (fallback when no config)

• 入口: README.md, MODULES.md
• 研究数据: Files under data/ directory
• 公司档案: Files under data/company_profiles/ or containing "公司"
• 任务与工作流: Files under tasks/ or agents/
• 模板: Files under templates/ or containing "template"
• 其他: Everything else

Limitations

• Very large markdown files (>100KB each) make the HTML larger but still load fine (lazy rendering)
• Badges are filename-heuristic based unless overridden via config
• The script skips hidden directories (starting with .)
• Emoji and special Unicode should work but test if issues arise